Webhooks & Api
WebHooks (PostBack) – это механизм обратного вызова, позволяющий внешним сервисам отправлять обновления в вашего бота. Они играют ключевую роль в динамическом управлении диалогами и поведением бота.
Для того, чтобы подключить к вашему сервису необходимо получить уникальную ссылку для WebHooks.
Для получении ссылки
Откройте вашего бота
Настройки скрипта
Bot settings (шестеренка в левом меню)
Нажмите "Add Webhook"
Нажмите "SAVE" внизу экрана для сохранения изменений
Можно создать несколько ссылок на одного бота, это бывает полезно чтобы использовать несколько сервисов. Если у вас несколько ботов, каждая ссылка будет уникальна.
WebHooks позволяют изменять параметры диалогов, управлять переходами между шагами и добавлять теги. Это упрощает адаптацию бота к различным сценариям общения.
Для взаимодействия с чатами пользователей мы используем Telegram ChatID
chatId=1227280
На месте "1227280" вы должны передать Telegram ChatID пользователя, которому необходимо внести изменения.
ВАЖНО: Можно присваивать значения по Telegram ChatID даже тем пользователям, которые еще не начали общение с ботом. Т.е. когда пользователь начнет диалог, в Chatterfy уже будет присвоена информация, которую вы передавали ранее.
После того, как вы получили ссылку и научились работать с ключевым полем, вы можете управлять диалогом при помощи вебхуков, используя переменные такие как:
stepId
status=auto/manual/blocked
details.KEYCUSTOMFIELD=params
Переключения шагов
Для переключения пользователя на конкретный шаг необходимо отправить:
— chatId — ID чата в Telegram
— stepId — ID шага в вашем боте, на который необходимо перевести диалог
Передача дополнительной информации в диалог
Используйте параметр (объект) fields.anyKey для добавления дополнительных данных в диалог.
Пример 1 - сохранение уникального refID из внешней системы
https://app.chatterfy.ai/api/bots/webhooks/<POSTBACK_ID>/updateDialog?chatId=1227280&refID=12345
Пример, https://app.chatterfy.ai/api/bots/webhooks/8f1el0ed-a1d2-4a9d-bc30-2e19f2062789/updateDialog?chatId=1227280&refID=12345
Пример 2 - запись баланса пользователя
https://app.chatterfy.ai/api/bots/webhooks/<POSTBACK_ID>/updateDialog?chatId=1227280&userBalance=5000
Пример, https://app.chatterfy.ai/api/bots/webhooks/8f1el0ed-a1d2-4a9d-bc30-2e19f2062789/updateDialog?chatId=1227280&userBalance=5000
Использование сохраненных данных
Для использования данных в шаблонах, вставьте соответствующие переменные в двойные фигурные скобки.
Дефолтное использование параметров в ссылках
{{chatId}} - Telegram ID
{{username}} - Telegram username
{{name}} - имя пользователя
{{createdAt}} - дата создания диалога
{{fields.key любого кастом филда}} - записать и достать с кастом филдов можно через fields. Записывай любой ваш кастом филд, созданный в Bot Settings
{{tracker.key любого трекер филда}} - любой параметр из трекер филд, добавленный в параметрах кампании в Трекере
Например, https://some.service.com/signup?refId={{fields.refId}}
Примеры
Если пользователь открыл лендинг с utm параметром ad_name=test, то у пользователя будет трекер филд ad_name со значением test. Затем вы сможете его использовать в общении с пользователем, например https://some.service.com/signup?ad_name={{tracker.ad_name}}Также, каждый пользователь дополнительно имеет кликайди - уникальный параметр для каждого пользователя. Его значение можно получить, используя макрос {{tracker.clickid}}.
Если вы, например, хотите отправить приветственное сообщение с именем пользователя, то вы можете создать степ Send Message и в тексте сообщения добавить текст например Hello, {{name}} Частым примером использования параметров из чата является генерация ссылки на регистрацию в партнерке. Например, https://partner.com/signup?sub1={{tracker.clickid}}. Таким образом вы предоставите пользователю ссылку на регистрацию в партнерку и запишите в sub1 наш clickid. Если, например, clickid пользователя =test123, то пользователь получит ссылку https://partner.com/signup?sub1=test123 Исключение:
Если пользователь пришел в бота/личка вне кампании из трекера (например, открыл бота и нажал старт), то у данного лида не будет трекер даты и его нельзя будет трекать.
FAQ - Часто задаваемые вопросы 📍
1) После отправки ID клиента, могу ли я проверить его в своей БД и переключить степ в зависимости от результата?
Вы можете в степе вебхук слать себе айди, которого нужно переключить. Взяв нужный вам параметр, вы проверите нужно ли переключать степ или нет.
https://test.com?chatId={fields.chatId} Например, если пользователь имеет Telegram ID - 123, то вебхук отправится по адресу (URL) https://test.com?chatId=123. Затем вы можете отправить запрос на созданный вебхук в боте. https://app.chatterfy.ai/api/bots/webhooks/<POSTBACK_ID>/updateDialog?chatId=123&stepId=[степ на который нужно переключить пользователя]&status=auto
Last updated