Правила формирования ссылки события «Упомянут в запросе»

Что такое GET-запрос и как он формируется?

GET-запрос — по своей сути это открытие интернет страницы по ссылке. Это может делать как пользователь так и сторонний сервис.

В ссылке могут быть переданы параметры-переменные с разными значениями. Эти параметры записываются в ссылке так:

• ? — начало get-параметров страницы. Пишется в конце основной ссылки. Может быть ТОЛЬКО 1 на всю ссылку. Поэтому если уже видите ? в ссылке, то больше писать не нужно. После него пишут название параметра.
• = — стоит после названия параметра. После него идет значение параметра. Тоже любое.
• & — начало второго параметра. Другими словами это разделитель между разными параметрами. Дальше опять: название=значение. Таких символов должно быть на 1 меньше передаваемых параметров (первый начинается с ?).

Проще всего понять на примере:

skyjoom.com/blog?article=58&title=Формирование Запроса

В Автопилоте в событии «Упомянут в запросе» первый параметр уже добавлен (?s=…), поэтому нужно прописывать только дополнительные. Например:

&sid=000000&payment_link=skyjoom.com&content=Сообщение

Если запрос идет от имени какого-то сервиса, значения в параметры могут передаваться самим сервисом с помощью его внутренних переменных. Например для GetCourse (процесс по заказам):

&sid={object.user.vk_uid}&payment_link={object.payment_link}

Правила формирования запроса для Автопилота

По сути все правила сводятся к тому, какие именно параметры можно использовать. Поэтому:

Возможные параметры. Есть 4 типа дополнительных параметров:

1) Обязательные.

• sid - ID профиля ВКонтакте подписчика (игрока), для которого нужно выполнить событие. Обязательно должен быть числом. В примере переменная, которая превращается в ID во время выполнения запроса
  --- или ---
• email — email подписчика, для которого нужно выполнить событие. Сработает, если такой сохранен в Автопилоте.
  --- или ---
• surl — ссылка на профиль подписчика ВКонтакте. В некоторых случаях вам будет удобнее передавать ссылку на подписчика.
  --- или ---
• uid — то же, что и sid. Сработает, если sid не добавлен. Для интеграции с такими сервисами, как Гамаюн например, где ID подписчика уже предустановлен и его нельзя сменить.
  --- или ---
• sid_param — позволяет указать какой именно параметр содержит в себе VK ID игрока (или ссылку на его профиль или даже screen_name, который начинается с символа @). Подробнее как использовать смотрите тут
  --- или ---
• email_param — позволяет указать какой именно параметр содержит в себе email игрока. Работает аналогично предыдущему параметру.

2) Предустановленные (необязательные). Прописанные в системе и имеют конкретное назначение. Можно активно использовать их по этому назначению или при необходимости такие параметры можно переназначить в запросе.

• content— основное содержимое запроса
• И подстановки (переменные): subs_id, id_1, body_1, id_2, body_2, first_name, last_name, sex, bdate, screen_name, subs_link, vk_product_price, vk_product_title.
  Полный актуальный список переменных здесь.

3) Системные. Их нельзя перезаписывать, берутся из сервиса.

• s — или secret (для POST) — это секретный ключ вашего сообщества из настроек интеграции с ВК. Он должен совпадать с установленным. Обычно он просто сразу прописан в ссылке.

• eid — номер события. В GET-запросе тоже часть ссылки.

4) Произвольные. Вы можете добавить любой дополнительный параметр, отличный от указанных выше. И система передаст его команде :)

Переданный параметр можно использовать как «подстановку» в «действиях команды» для получения его значения.

Например чтобы отправить в ВК ссылку на оплату в сообщения ВК (для запроса из примера) можно использовать переменную %payment_link%

Значения параметров указывайте средствами сервиса, который отправляет запрос. Например для GetCourse (процесс по заказам):

&sid={object.user.vk_uid}&payment_link={object.payment_link}

Важно!

Никому не показывайте ссылку запроса и не передавайте ее сторонним лицам! Одной ссылки достаточно чтобы вызвать событие для любого подписчика

Если нет возможности прописать SID

Иногда бывает что какой-то сервис передает данные в JSON (или как POST, но в виде многомерного массива) и при этом не умеет передавать id подписчика в самом GET-запросе.

В таком случае вы можете получить значение параметра с любым другим названием (или элемента одного из дочерних уровней POST-массива или JSON-объекта) указав путь к нему с помощью параметра sid_param:
&sid_param=contact.vk.id ← пример написания в событии.

Пример многомерного JSON объекта для выражения выше:
{
contact": {
"name": "Олександр",
"vk": {"id":1234567,"club":12345}
},
}

Упрощенный пример (для запросов с просто странным гет-параметром):

&vk_uid=00000&sid_param=vk_uid ← пример готовых параметров для URL-адреса вебхука, где 00000 — это ID подписчика.

Поиск по номеру телефона

Если вам нужно найти подписчика по номеру телефона, то добавьте к параметрам следующий:

&player[param][name]=phone&player[param][path]=object.tel

где object.tel — путь в JSON.PATH к полю, где находится телефон

Поиск по API ID

Если вам нужно найти подписчика по API ID, то добавьте к параметрам следующий:

&api=1&to=json&return_player=1&api_id=26187274&player[param][path]=api_id&player[param][name]=apiid

где 26187274 — API ID игрока

При совпадении параметров ищет подходящий среди последних 30 вхождений, отсортированных по дате регистрации

Возврат данных

По умолчанию сервис в ответ на запрос отвечает: {"success":true}

Такой ответ означает, что запрос был помещен в очередь на выполнение и вскоре будет выполнен.

Для некоторых сервисов может быть полезно сменить ответ сервера. Например на слово ok. В таком случае к параметрам запроса нужно добавить: &to=ok. К слову, ok может быть заменено на любой другой нужный тест, который будет сообщать стороннему сервису, что вебхук успешно обработан.

Также иногда может быть необходимо дождаться выполнения команды и ответить серверу уже после её выполнения и обработки всех переменных. Например, когда в команде используется действие: Сменить ответ сервера. Чтобы активировать такой режим добавьте к ссылке параметр &api=1.

НО ИМЕЙТЕ В ВИДУ. В подобном режиме ↑ ответ может быть возвращен намного позднее таймаута запроса внешнего сервиса. Потому, что некоторые действия выполняются от 1 секунды. Не используйте подобные действия в таких командах. А также таймеров.

Если вам нужно получить в ответ данные подписчика в формате JSON (достав их из ВК или Автопилота), то добавьте к параметрам следующий: &return_player=1

Есть еще параметр &to=json, который делает страницу оптимальной для запросов из javascript. С ним также страница (с json-объектом данных) открывается в удобочитаемом виде на некоторых браузерах.

Интеграция с сервисом Tilda

Для интеграции с Тильдой, достаточно (и рекомендуется) использовать полную ссылку из события без доп. параметров (вариант 2 в примере). Вставьте ее в общие «настройки форм» сайта как параметр сервиса «Webhook».

Остальные параметры пропишите латиницей в параметры «Имя переменной» каждого поля формы.

Для возможности идентифицировать подписчика обязательно добавьте одно из следующих полей:

• email - эл. адрес (сработает, если такой сохранен в автопилоте);
• surl — ссылка на профиль подписчика в VK;
• sid — ID подписчика в VK.

Подробнее тут: vk.com/@skyautome-tilda.

При использовании собственного РНР скрипта, все аналогично.

Интеграция с amoCRM

Подробно про настройку вебхуков для амо написано здесь.

Интеграция с системой GetCourse.

Речь о получении запросов из ГК. Информация получена из статьи на их блоге.

Отправка запросов из GetCourse реализуется через процессы с помощью «операции» Вызов URL. В поле Url этой операции можно вставлять ссылку сформированную в Автопилоте. В теле этой ссылки можно использовать переменные процесса.

Для различных задач существуют различные типы процессов. Далее покажем примеры и значения переменных. И разделим их по типам процесса.

1) Пользователь:

• {object.first_name} — имя,
• {object.last_name} — фамилия,
• {object.name} — имя полностью,
• {object.id} — идентификатор (ID пользователя),
• {object.email} — эл. адрес,
• {object.phone} — телефон,
• {object.avatar_url} — ссылка на аватар пользователя,
• {object.заголовок_поля} — данные из дополнительного поля пользователя, нужно вписать заголовок поля. Например {object.vk_uid}, где vk_uid — заголовок поля.

Рекомендую использовать доп.поля с заголовками латиницей без пробелов.

Лайфхак: ID пользователя можно использовать для формирования ссылки на профиль подписчика в GС для уведомлений администраторам. Пример:

http://youraccountname.getcourse.ru/user/control/user/update/id/{object.id}

Или открытый профиль: http://youraccountname.getcourse.ru/pl/{object.id}

2) Заказ:

• {object.number} — номер заказа,
• {object.id} — идентификатор заказа,
• {object.positions} — состав заказа,
• {object.cost_money} — стоимость заказа,
• {object.left_cost_money} — сколько осталось заплатить,
• {object.payed_money} — сколько оплачено,
• {object.status} — статус заказа,
• {object.payment_link} — ссылка на оплату.

Также у заказа есть специальное поле user, по которому можно получить дополнительные данные о клиенте, оформившем заказ. Например:

• {object.user.first_name} - имя пользователя
• {object.user.vk_uid} — дополнительное поле профиля.
• и т.п. (см. выше в разделе Пользователь).

3) Покупка:

• {object.product_title} — название продукта,
• {object.start_at} — дата начала покупки,
• {object.finish_at} — дата окончания покупки,
• {object.start_at_ago} — время, прошедшее от старта,
• {object.finish_at_ago} — время, оставшееся до окончания,
• {object.period_string} — период доступа,
• {object.state} — статус покупки (текущее состояние),
• {object.link} — ссылка на покупку,
• {object.training_link} — ссылка на тренинг (если продукт связан с тренингом),
• {object.training_title} — название тренинга,
• {object.training_teacher_full_name} — полное имя основного преподавателя тренинга,
• {object.training_teacher_avatar_src} — путь к файлу аватарки преподавателя.

У покупки, как и у заказа, есть специальное поле user, по которому можно получить дополнительные данные о клиенте, оформившем покупку: {object.user.first_name} и т.п. (см. выше).

Еще немного дополнительной информации в процессах

Это для процесса по пользователям. Для процессов по заказам и покупкам добавляйте промежуточный параметр user, например:

{object.user.create_session.utm_source}

4. Партнёр пользователя:

• {object.partner.uid} — идентификатор партнёра,
• {object.partner.first_name} — имя партнёра,
• {object.partner.last_name} — фамилия партнёра,
• {object.partner.real_name} — автоматическое русскоязычное имя партнёра,
• {object.partner.email} — эл. адрес партнёра,
• {object.partner.phone} — номер телефона партнёра,
• {object.partner.user_hash},
• {object.partner.created_at} — дата регистрации партнёра.

5. Источник пользователя заказа (сессия, во время которой он зарегистрировался):

• {object.create_session.gcpc} — партнёрский код,
• {object.create_session.utm_source} — UTM-метки,
• {object.create_session.utm_medium}
• {object.create_session.utm_campaign}
• {object.create_session.utm_content}
• {object.create_session.utm_term}
• {object.create_session.utm_group}
• {object.create_session.clickid}
• и т.д.

6. Источник пользователя для заказов (сессия, во время которой он зарегистрировался):

• {object.user.create_session.gcpc} — партнёрский код,
• {object.user.create_session.utm_source} — UTM-метки,
• {object.user.create_session.utm_medium}
• {object.user.create_session.utm_campaign}
• {object.user.create_session.utm_content}
• {object.user.create_session.utm_term}
• {object.user.create_session.utm_group}
• {object.user.create_session.clickid}