Входящий 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 в левом нижнем углу блока, скопируйте ссылку и используйте в нужном сервисе вместо стандартной ссылки запроса.