Входящий Webhook
Webhook — это механизм автоматического оповещения одной системы о событиях в другой. Например, когда в Битрикс24 появляется новый клиент, webhook отправляет об этом данные в ChatApp — запускается нужный сценарий: например, система автоматические отправляет пользователю приветственное сообщение.
Блок «Входящий webhook» в ChatApp используют в качестве стартового блока в сценарии принятия запроса. Например, чтобы принимать запросы из Битрикс24 — как только информация о клиенте обновится, вебхук запустит нужный сценарий в ChatApp.
Как это работает
Для корректной работы блока необходимо заполнить его поля параметрами.
Параметры в вебхуке — какие данные вы хотите получать из других систем для работы вашего бота. Интеграция работает в три этапа:
1. Вебхук передаёт запрос.
2. Автоматически создаются локальные переменные.
3. Значения полученных в ответе на запрос параметров сохраняются в переменные, которые можно использовать в сценариях.
Запрос — специальная сгенерированная системой ссылка внизу блока. Она нужна для вызова сценария принятия запроса из сторонних сервисов. Это и есть вебхук, который используется для передачи данных в ChatApp.
Нажмите на кнопку «Добавить поле» для добавления нужного параметра.
Настройка блока «Входящий webhook»
1. Добавьте блок «Входящий webhook» на рабочую область в Редакторе сценариев.
2. Введите название сценария и сохраните его. Если сценарий не сохранен, работать с переменными не получится.
3. Создайте поля и впишите в них параметры, которые нужно передать. Например, параметры chat_id — телефон клиента и id — идентификатор карточки. Автоматически создаются локальные переменные с такими же названиями.
 |
Важно: в блок «Входящий webhook» нельзя добавлять системные переменные. |
4. В нижней части блока сформировалась ссылка запроса. Она нужна для настройки исходящего webhook в нужном сервисе.
Пример ссылки: https://constructorbot.chatapp.online/api/request/?token=3019b0ea-eb2a-40bf-aedb-4784d6879327&chat_id=&id=&template_id=19798
В ней:
/?token= — токен генерируется сам
&chat_id= — номер телефона клиента
&id= — идентификатор карточки
5. Добавьте блок «Отправка сообщения*».
6. В «ChatID» введем пременную {{chat_id}};
7. В поле «Линия» выберите линию, с которой будет отправляться сообщение, в поле «Мессенджер» выберите канал, по которому отправится сообщение.
8. Введите текст отправляемого сообщения, прикрепите эмодзи,
добавьте константу или переменную,
или результат работы блоков.
9. Сохраните ваш сценарий.
10. Перейдите в сервис, который будет отправлять запрос, и настройте в нем исходящий webhook. Процесс настройки может отличаться в зависимости от сервиса.
Получение параметров из тела запроса
1. Параметры, которые передаются через webhook, могут быть в ссылке — www.…/get/?token=…. В таком случае их нужно вписать в поля блока, как описано выше.
2. Также параметры могут приходить в теле запроса в формате .json. Тогда их не нужно вписывать в блок:
{
«Email1»: «…@gmail.com»,
«name_client»: «test»,
«chat_id»: «89999999999»,
«tranid»: «test»,
«formid»: «formtest»,
«utm_source»: «google»,
«utm_medium»: «cpc»,
«utm_campaign»: «promo»
}
Чтобы получить данные из таких параметров, укажите их в боте в фигурных скобках. Например, если ввести в тексте сообщения {{Email1}}, то когда придет webhook, подставится значение …@gmail.com.
 |
Важно: имена передаваемых параметров в теле запроса должны отличаться от системных переменных, которые уже есть в боте. В примере в конце передаваемого параметра «Email1» стоит цифра 1. |
 |
Важно: для корректного получения параметров из тела запроса, в ссылке должен быть только адрес токена www.…/get/?token=…. |
3. Некоторые сервисы передают webhook с вложенными параметрами. Это выглядит так:
{
«payment»: {
«name»: «Вася»
«Email1»: «…@gmail.com»,
}
}
В таком случае, чтобы получить имя клиента, укажите параметр, который содержит в себе параметр с именем — payment, а через точку укажите нужный параметр. Должно получиться так: {{payment.name}}.
4. Когда в вебхуке есть параметры в ссылке, бот принимает параметры из тела запроса. Если в ссылке и в теле запроса одинаковое название поля, то значение возьмется из тела запроса.
При получении POST-запроса бот смотрит параметры из ссылки и тела одновременно.
5. В некоторых случаях параметры содержат в себе вложенные списки. Тогда в одном параметре может оказаться 2 других параметра с одинаковым названием. В теле запроса список выделяется квадратными скобками, это будет выглядеть так:
«payment» : [ { «name»: «Вася» «email1»: «…@mail.ru» } { «name» : «Петя» «email1»: «…@yandex.ru» } ]
Как отличить друг от друга одинаковые параметры name?
Каждый элемент в списке имеет свой порядковый номер. Отсчет начинается с 0. Значит, параметр с именем “Вася” будет по счету — 0. В боте это будет указываться так:
payment[0].name — бот отправит “Вася”;
payment[1].name — бот отправит “Петя”.
 |
Внимание: элемент в формате json отделяется двумя фигурными скобками. Все что внутри будет считаться одним элементом, даже если он содержит несколько параметров. |
Возврат результатов блоков
С помощью блока «Входящий вебхук» также можно вернуть результаты работы блоков в теле ответа на запрос. Чтобы блок присылал ответ, нажмите на значок подсказки i в левом нижнем углу блока, скопируйте ссылку и используйте в нужном сервисе вместо стандартной ссылки запроса.
