# Webhooks & Api
{% hint style="success" %}
**WebHooks (PostBack)** – это механизм обратного вызова, позволяющий внешним сервисам отправлять обновления в вашего бота. Они играют ключевую роль в динамическом управлении диалогами и поведением бота.
{% endhint %}
Для того, чтобы подключить к вашему сервису необходимо п**олучить уникальную ссылку для WebHooks.**
Для получении ссылки
1. Откройте вашего бота
2. Настройки скрипта
3. Bot settings (шестеренка в левом меню)
4. Нажмите "Add Webhook"
5. Нажмите "SAVE" внизу экрана для сохранения изменений
Можно создать несколько ссылок на одного бота, это бывает полезно чтобы использовать несколько сервисов. Если у вас несколько ботов, каждая ссылка будет уникальна.
{% hint style="info" %}
**Уникальная ссылка выглядит так: <**POSTBACK\_ID**>/updateDialog**\
\
[**https://app.chatterfy.ai/api/bots/webhooks/55833627-242e-4061-9b0a-30da3e9cf7d4/updateDialog**](https://app.chatterfy.ai/api/bots/webhooks/55833627-242e-4061-9b0a-30da3e9cf7d4/updateDialog)
{% endhint %}
* WebHooks позволяют изменять параметры диалогов, управлять переходами между шагами и добавлять теги. Это упрощает адаптацию бота к различным сценариям общения.
* Для взаимодействия с чатами пользователей мы используем Telegram ChatID
**chatId=1227280**
На месте "1227280" вы должны передать Telegram ChatID пользователя, которому необходимо внести изменения.
{% hint style="danger" %}
**ВАЖНО:** \
Можно присваивать значения по Telegram ChatID даже тем пользователям, которые еще не начали общение с ботом. Т.е. когда пользователь начнет диалог, в Chatterfy уже будет присвоена информация, которую вы передавали ранее.
{% endhint %}
После того, как вы получили ссылку и научились работать с ключевым полем, вы можете управлять диалогом при помощи вебхуков, используя переменные такие как:
1. stepId
2. status=auto/manual/blocked
3. details.KEYCUSTOMFIELD=params
### Переключения шагов
Для переключения пользователя на конкретный шаг необходимо отправить:
— chatId — ID чата в Telegram
— stepId — ID шага в вашем боте, на который необходимо перевести диалог
{% hint style="info" %}
Отправлять параметры можно через **GET**.
**Пример: \/updateDialog?chatId=1227280\&stepId=046050f6-38f6-4b18-b9fa-e6582f5352d0**
{% endhint %}
### Передача дополнительной информации в диалог
Используйте параметр (объект) fields.anyKey для добавления дополнительных данных в диалог.
{% hint style="warning" %}
**Пример 1** - **сохранение уникального refID из внешней системы**
\/updateDialog?chatId=1227280\&refID=12345
Пример, \
\
{% endhint %}
{% hint style="warning" %}
**Пример 2 - запись баланса пользователя**
\/updateDialog?chatId=1227280\&userBalance=5000
Пример, \
\
{% endhint %}
### Использование сохраненных данных
Для использования данных в шаблонах, вставьте соответствующие переменные в двойные фигурные скобки.
{% hint style="info" %}
Например, для генерации персонализированных ссылок.
{% endhint %}
**Дефолтное использование параметров в ссылках**
{{chatId}} - Telegram ID
{{username}} - Telegram username
{{name}} - имя пользователя
{{createdAt}} - дата создания диалога
{{fields.key любого кастом филда}} - записать и достать с кастом филдов можно через fields. \
Записывай любой ваш кастом филд, созданный в Bot Settings
{{tracker.key любого трекер филда}} - любой параметр из трекер филд, добавленный в параметрах кампании в Трекере
Например,
## Примеры
Если пользователь открыл лендинг с utm параметром ad\_name=test, то у пользователя будет трекер филд ad\_name со значением test. Затем вы сможете его использовать в общении с пользователем, например , каждый пользователь дополнительно имеет кликайди - уникальный параметр для каждого пользователя. Его значение можно получить, используя макрос {{tracker.clickid}}.
Если вы, например, хотите отправить приветственное сообщение с именем пользователя, то вы можете создать степ Send Message и в тексте сообщения добавить текст например Hello, {{name}}\
\
Частым примером использования параметров из чата является генерация ссылки на регистрацию в партнерке. Например, . Таким образом вы предоставите пользователю ссылку на регистрацию в партнерку и запишите в sub1 наш clickid. Если, например, clickid пользователя =test123, то пользователь получит ссылку
\
**Исключение:**
Если пользователь пришел в бота/личка вне кампании из трекера (например, открыл бота и нажал старт), то у данного лида не будет трекер даты и его нельзя будет трекать.
## FAQ - Часто задаваемые вопросы 📍
### 1) После отправки ID клиента, могу ли я проверить его в своей БД и переключить степ в зависимости от результата?
{% hint style="success" %}
Вы можете в степе вебхук слать себе айди, которого нужно переключить. Взяв нужный вам параметр, вы проверите нужно ли переключать степ или нет.
[https://test.com?chatId={fields.chatId}](https://test.com?chatId={chatId}\&stepId={stepId})\
\
Например, если пользователь имеет Telegram ID - 123, то вебхук отправится по адресу (URL) [https://test.com?chatId=123](https://test.com?chatId={chatId}\&stepId={stepId}). Затем вы можете отправить запрос на созданный вебхук в боте. \
\
\/updateDialog?chatId=123\&stepId=\[степ на который нужно переключить пользователя]\&status=auto
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.chatterfy.ai/konstruktor-skriptov/nastroiki-skripta/bot-settings/webhooks-and-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.