# API & Webhooks ## Рассылки в WhatsApp: описание API & Webhooks *** * [Работа с API](#rabota-s-api) * [OAuth-авторизация](#oauth-avtorizaciya) * [Формат запросов](#format-zaprosov) * [Методы API](#metody-api) * [Метод для создания рассылки](#sozdanie-rassylki) * [Метод для получения списка рассылок](#spisok-rassylok) * [Метод для получения информации о рассылке](#informaciya-o-rassylke) * [Метод подсчета статистики для рассылки (Устаревший)](#podschet-statistiki) * [Метод для остановки запущенной рассылки](#ostanovka-rassylki) * [Вебхуки](#vebkhuki) * [Инструкция по настройке уведомлений](#nastroika-uvedomlenii) * [Описание события LEGACY\_WHATSAPP\_STATE](#legacy_whatsapp_state) *** ## Работа с API ### OAuth-авторизация Для работы с Fasttrack API вам понадобится уникальный `access_token`, которым необходимо передавать в заголовке для каждого запроса. Следуйте инструкции ниже, чтобы получить ключ доступа для вашего проекта: {% hint style="info" %} **Важно!** Временно, приложения клиентов для использования API Fasttrack, регистрируются вручную, через менеджеров проекта. {% endhint %} **Шаг 1: Подготовить `redirect_uri`** `redirect_uri` — это URL, на который сервер перенаправит вас после успешной авторизации, передавая временный код (`code`). Этот код затем используется приложением для обмена на ключ доступа (`access_token`). **Шаг 2: Зарегистрировать приложение** Сообщите менеджеру о том, что планируете использовать Fasttrack API и предоставьте `redirect_uri` для регистрации вашего приложения. Данные о приложении, которые вы получите: | `client_id` | Идентификатор вашего приложения. | | --------------- | --------------------------------- | | `client_secret` | Защищённый ключ вашего приложения | {% hint style="danger" %} **Внимание!** Параметр `client_secret` используется для идентификации и подтверждения подлинности вашего приложения в процессе OAuth-авторизации. Этот параметр является конфиденциальным и должен защищаться так же строго, как и пароли. {% endhint %} **Шаг 3: Получить временый код авторизации** Сформируйте URL следующего вида: ``` https://dashboard.fstrk.io/integrations/oauth/?{параметры} ``` После знака `?` в URL укажите следующие параметры: * **`client_id`** \* – Идентификатор вашего приложения; * **`redirect_uri`** \* – URL для получения временного кода авторизации * **`state`** – Произвольная строка, которая будет передана вместе с кодом. Пример URL: {% code overflow="wrap" %} ``` https://dashboard.fstrk.io/integrations/oauth/?client_id=1&redirect_uri=https://example.com/oauth/&state=dummy ``` {% endcode %} Перейдите по ссылке. Вы попадете на страницу со списком доступных проеков (их может быть несколько). Выберите проект для которого планируете получить `access_token`. Браузер переадресует вас обратно на URL, указанный в параметре `redirect_uri` с добавлением параметров `state` и временного кода авторизации (`code`). **Шаг 5: Получить** **`access_token`** ``` POST https://dashboard.fstrk.io/api/partners/oauth/ ``` Метод для получения `access_token` в рамках OAuth-авторизации. Пример запроса: ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/oauth/ \ --header 'Content-Type: application/json' \ --data '{ "client_id": "", "client_secret": "", "grant_type": "code", "code": "" }' ``` При успешном выполнении запроса API возвращает код ответа `200` и JSON-объект с параметром `access_token`.
200 ```json { "access_token": "string" } ```
### Формат запросов API работает по протоколу HTTP(S) и поддерживает методы REST (Representational State Transfer), такие как `GET`, `POST`, `PUT`, `PATCH` и `DELETE`. Каждый запрос имеет стандартный формат и требует обязательного использования корректных заголовков и параметров. **Базовый URL** ```http https://dashboard.fstrk.io/api/partners/ ``` **Заголовки** Каждый запрос к API Fasttrack требует заголовок `Authorization` для подтверждения прав доступа. Без этого заголовка сервер не обработает запрос и вернет ошибку. ```http Authorization: Bearer { access_token } ``` Для корректной работы с API Fasttrack запросы, которые передают данные, должны содержать заголовок Content-Type. Он указывает, что данные в запросе отправляются в формате JSON. ```http Content-Type: application/json ``` Также рекомендуется указывать заголовок Accept, чтобы явно запросить от сервера ответы в формате JSON. Это обеспечивает корректное восприятие данных на стороне клиента. ```http Accept: application/json ``` ## Методы API Список методов: * `GET` `/mailings/` – список рассылок * `POST` `/mailings/` – создание рассылки * `GET` `/mailings/{ uuid }/` – информация о рассылке * `POST` `/mailings/{ uuid }/calculate/` – подсчет статистики * `POST` `/mailings/{ uuid }/stop/` – остановка рассылки Протестировать API можно через Swagger по ссылке:\ [https://dashboard.fstrk.io/api/partners/docs/](https://dashboard.fstrk.io/api/partners/docs/#/4.%20%D0%9E%D1%82%D0%BF%D1%80%D0%B0%D0%B2%D0%BA%D0%B0%20%D0%BF%D0%B5%D1%80%D1%81%D0%BE%D0%BD%D0%B0%D0%BB%D1%8C%D0%BD%D1%8B%D1%85%20%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B9) Для тестирования, необходимо авторизоваться в Fasttrack. ### Создание рассылки ``` POST /mailings/ ``` Универсальный метод для создания новой рассылки. **Заголовки**
Content-Typeapplication/json
AuthorizationBearer { access_token }
**Тело запроса** `application/json` *** **`name`** *(string)* **\*** – название рассылки. Пример: `"Моя первая WA-рассылка"` *** **`content_type`** *(string)* – тип контента. Значение: `"WHATSAPP_TEMPLATE"` *** **`phone_numbers_file`** *(string)* – Ссылка на файл со списком телефонов. *** **`template_whatsapp`** *(string)* – ID согласованного WhatsApp-шаблона. Пример: `"name_of_approved_template"` *** **`template_variable`** *(object)* – Список заполненных переменных для шаблона. {% code title="Пример" %} ```json { // ... "template_whatsapp": "name_of_approved_template", "template_variables": { "v1": { "type": "GLOBAL", "value": "demo_mailing" }, "v2": { "type": "FILE" } } // ... } ``` {% endcode %} *** **`planned_at`** *(string)* – дата и время запуска для отложенных рассылок. * Формат: `ISO 8601` * Пример: `"2024-09-16T19:41:02.768Z"` *** **`regular_cron`** *(string)* – расписание для регулярных рассылок. * Формат: `CRON` * Пример: `"00 12 * * *"` (рассылка в 12:00 каждый день). *** **`origin`** *(string)* – признак источника рассылки. * Значения: `"chat_center"` `"system"` * По умолчанию: `"system"` Если указать `chat_center`, то рассылка будет отправлена всем пользователям, в том числе тем, у кого в момент рассылки открыта сессия с оператором. *** **Примеры запросов** Ниже приведены примеры запросов, оформленные в формате `cURL`. Они демонстрируют различные сценарии использования и настройки параметров для создания рассылок.
1. Рассылка в WhatsApp: Шаблон без переменных ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/ \ --header 'Authorization: Bearer { access_token }' \ --header 'Content-Type: application/json' --data '{ "name": "Моя первая рассылка в WA", "phone_numbers_file": "https://example.com/file.csv", "content_type": "TEMPLATE_WHATSAPP", "template_whatsapp": "name_of_approved_template" }' ```
2. Рассылка в WhatsApp: Шаблон с переменными (значения в теле запроса) ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/ \ --header 'Authorization: Bearer { access_token }' \ --header 'Content-Type: application/json' --data '{ "name": "Моя первая рассылка в WA", "phone_numbers_file": "https://example.com/file.csv", "content_type": "TEMPLATE_WHATSAPP", "template_whatsapp": "name_of_approved_template", "template_variables": { "v1": { "type": "GLOBAL", "value": "Мастер-класс" }, "v2": { "type": "GLOBAL", "value": "Пряничное дело" } } }' ```
3. Рассылка в WhatsApp: Шаблон с переменными (значения в файле) ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/ \ --header 'Authorization: Bearer { access_token }' \ --header 'Content-Type: application/json' --data '{ "name": "Моя первая рассылка в WA", "phone_numbers_file": "https://example.com/file.csv", "content_type": "TEMPLATE_WHATSAPP", "template_whatsapp": "name_of_approved_template", "template_variables": { "v1": { "type": "FILE" }, "v2": { "type": "FILE" } } }' ```
4. Рассылка в WhatsApp: Шаблон с переменными (смешанный вариант) ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/ \ --header 'Authorization: Bearer { access_token }' \ --header 'Content-Type: application/json' --data '{ "name": "Моя первая рассылка в WA", "phone_numbers_file": "https://example.com/file.csv", "content_type": "TEMPLATE_WHATSAPP", "template_whatsapp": "name_of_approved_template", "template_variables": { "v1": { "type": "GLOBAL", "value": "значение из запроса" }, "v2": { "type": "FILE" }, "v3": { "type": "FILE" }, "v4": { "type": "FILE" } } }' ```
**Результат запроса** При успешном выполнении запроса API возвращает код ответа `201` и JSON-объект с информацией о рассылке, включая полный набор параметров. Пример ответа:
201 ```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "state": "string", "filter_chats": "string", "content_type": "TEXT", "source_type": "PLATFORM", "text": "string", "node": 0, "node_name": "string", "node_get_params": [ { "name": "string", "value": "string", "type": "string", "is_edit": false, "param_type": "GLOBAL" } ], "origin": "system", "statistics": { "count_planned": 0, "count_sent": 0, "count_delivered": 0, "count_undelivered": 0, "count_read": 0, "count_clicked": 0, "count_jumped_url": 0, "count_replied": 0, "count_platforms": "string" }, "regular_cron": "string", "created_at": "2024-11-13T05:22:03.354Z", "planned_at": "2024-11-13T05:22:03.354Z", "completed_at": "2024-11-13T05:22:03.354Z", "duration": "string", "template_whatsapp": "string", "template_variables": "string", "phone_numbers_file": "string", "customer_filter_file": "string", "customer_filter_field": "UUID" } ```
### Список рассылок ``` GET /mailings/ ``` Метод для получения списка всех созданных рассылок. **Заголовки**
AuthorizationBearer { access_token }
**Query-параметры**
limitКол-во записей, которое вернется в результате запроса. Максимум 100.
offsetСмещение от начала выборки.
Параметры `limit` и `offset` позволяют контролировать объем возвращаемых данных и навигацию по страницам при выполнении запросов к API. **Пример запроса** 
curl -X GET \
--location https://dashboard.fstrk.io/api/partners/mailings/?offset=20&limit=20 \
--header 'Authorization: Bearer { access_token }'
**Результат запроса** При успешном выполнении запроса API возвращает код ответа `200` и JSON-объект с информацией о рассылке, включая полный набор параметров.
200 ```json { "count": 1, "next": "http://api.example.org/accounts/?offset=300&limit=100", "previous": "http://api.example.org/accounts/?offset=100&limit=100", "results": [ { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "state": "string", "filter_chats": "string", "content_type": "TEXT", "source_type": "PLATFORM", "text": "string", "node": 0, "node_name": "string", "node_get_params": [ { "name": "string", "value": "string", "type": "string", "is_edit": false, "param_type": "GLOBAL" } ], "origin": "system", "statistics": { "count_planned": 0, "count_sent": 0, "count_delivered": 0, "count_undelivered": 0, "count_read": 0, "count_clicked": 0, "count_jumped_url": 0, "count_replied": 0, "count_platforms": "string" }, "regular_cron": "string", "created_at": "2024-11-13T05:30:47.345Z", "planned_at": "2024-11-13T05:30:47.345Z", "completed_at": "2024-11-13T05:30:47.345Z", "duration": "string", "template_whatsapp": "string", "template_variables": "string", "phone_numbers_file": "string", "customer_filter_file": "string", "customer_filter_field": "UUID" } ] } ```
### Информация о рассылке ``` GET /mailings/{ uuid }/ ``` Метод для получения информации о рассылке по ее идентификатору (UUID). **Заголовки**
AuthorizationBearer { access_token }
#### **Path-параметры**
uuid *Идентификатор рассылки
Пример запроса ```sh curl -X GET \ --location https://dashboard.fstrk.io/api/partners/mailings/{ uuid } \ --header 'Authorization: Bearer { access_token }' ``` **Результат запроса** При успешном выполнении запроса API возвращает код ответа `200` и JSON-объект с информацией о рассылке, включая полный набор параметров.
200 ```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "state": "string", "filter_chats": "string", "content_type": "TEXT", "source_type": "PLATFORM", "text": "string", "node": 0, "node_name": "string", "node_get_params": [ { "name": "string", "value": "string", "type": "string", "is_edit": false, "param_type": "GLOBAL" } ], "origin": "system", "statistics": { "count_planned": 0, "count_sent": 0, "count_delivered": 0, "count_undelivered": 0, "count_read": 0, "count_clicked": 0, "count_jumped_url": 0, "count_replied": 0, "count_platforms": "string" }, "regular_cron": "string", "created_at": "2024-11-13T07:28:50.931Z", "planned_at": "2024-11-13T07:28:50.931Z", "completed_at": "2024-11-13T07:28:50.931Z", "duration": "string", "template_whatsapp": "string", "template_variables": "string", "phone_numbers_file": "string", "customer_filter_file": "string", "customer_filter_field": "UUID" } ```
### Подсчет статистики ``` POST /mailings/{ uuid }/calculate/ ``` Метод для подсчета статистики для рассылки по ее идентификатору (UUID). {% hint style="warning" %} **Устаревший метод.** Статистика в рассылках по аудиториии проекта обновляется автоматически, поэтому данный метод на сегодняшний день не актуален. {% endhint %} **Заголовки**
AuthorizationBearer { access_token }
#### Path-параметры
uuid *Идентификатор рассылки
**Пример запроса** ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/calculate/ \ --header 'Authorization: Bearer { access_token }' ``` **Результат запроса** При успешном выполнении запроса API возвращает код ответа `200` и JSON-объект с информацией о рассылке, включая полный набор параметров.
200 ```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "state": "string", "filter_chats": "string", "content_type": "TEXT", "source_type": "PLATFORM", "text": "string", "node": 0, "node_name": "string", "node_get_params": [ { "name": "string", "value": "string", "type": "string", "is_edit": false, "param_type": "GLOBAL" } ], "origin": "system", "statistics": { "count_planned": 0, "count_sent": 0, "count_delivered": 0, "count_undelivered": 0, "count_read": 0, "count_clicked": 0, "count_jumped_url": 0, "count_replied": 0, "count_platforms": "string" }, "regular_cron": "string", "created_at": "2024-11-13T11:13:39.975Z", "planned_at": "2024-11-13T11:13:39.975Z", "completed_at": "2024-11-13T11:13:39.975Z", "duration": "string", "template_whatsapp": "string", "template_variables": "string", "phone_numbers_file": "string", "customer_filter_file": "string", "customer_filter_field": "UUID" } ```
### Остановка рассылки ``` POST /mailings/{ uuid }/stop/ ``` Метод, который используется, чтобы остановить рассылку, которая уже началась. **Заголовки**
AuthorizationBearer { access_token }
**Path-параметры**
uuid *Идентификатор рассылки
**Пример запроса** ```sh curl -X POST \ --location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/stop/ \ --header 'Authorization: Bearer { access_token }' ``` **Результат запроса** При успешном выполнении запроса API возвращает код ответа `200` и JSON-объект с информацией о рассылке, включая полный набор параметров.
200 ```json5 { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "state": "string", "filter_chats": "string", "content_type": "TEXT", "source_type": "PLATFORM", "text": "string", "node": 0, "node_name": "string", "node_get_params": [ { "name": "string", "value": "string", "type": "string", "is_edit": false, "param_type": "GLOBAL" } ], "origin": "system", "statistics": { "count_planned": 0, "count_sent": 0, "count_delivered": 0, "count_undelivered": 0, "count_read": 0, "count_clicked": 0, "count_jumped_url": 0, "count_replied": 0, "count_platforms": "string" }, "regular_cron": "string", "created_at": "2024-11-13T11:24:25.229Z", "planned_at": "2024-11-13T11:24:25.229Z", "completed_at": "2024-11-13T11:24:25.229Z", "duration": "string", "template_whatsapp": "string", "template_variables": "string", "phone_numbers_file": "string", "customer_filter_file": "string", "customer_filter_field": "UUID" } ```
## Вебхуки API Fasttrack предоставляет возможность подписаться на уведомления о событиях, которые связаны с отправленными рассылками по аудитории проекта. Типы событий, связанных с рассылками по аудитории: | `MAILING_STATE` | Статусы сообщений в рассылке | | ------------------ | ------------------------------- | | `MAILING_REACTION` | Реакции на сообщения в рассылке | ### Настройка уведомлений * Откройте настройки проекта → Раздел "Вебхуки" * Заполните поле \[ Endpoint URL ] * Активируйте события `MAILING_REACTION` и `MAILING_STATE` ### `MAILING_STATE` Cмена статуса отправленного сообщения в рассылке. {% tabs %} {% tab title="Пример события" %} ```json { "event_type": "mailing.state", "payload": { "profile": { "uuid": "dae05733-3026-4eca-abcf-ed366fc3372b" }, "chat": { "uuid": "dfed60eb-08f2-4672-af6a-d859a350c435" }, "mailing": { "uuid": "a353f441-9f67-42e7-bb28-be3c3fc817b5" }, "message": { "state": "delivered" } }, "timestamp": 1651776060.8439758 } ``` {% endtab %} {% tab title="Параметры события" %} | `event_type` | Тип события | | -------------------------- | --------------------------------- | | `payload` | Информация о событии | | > `payload.profile` | Информация о клиенте | | >> `payload.profile.uuid` | Уникальный идентификатор профиля | | > `payload.chat` | Информация о пользователе | | >> `payload.chat.uuid` | Уникальный идентификатор чата | | > `payload.mailing` | Информация о рассылке | | >> `payload.mailing.uuid` | Уникальный идентификатор рассылки | | > `payload.message` | Информация о сообщении | | >> `payload.message.state` | Текущее состояние сообщения | | `timestamp` | Временная метка | | {% endtab %} | | | {% endtabs %} | | **Статусы сообщений** | `sent` | Сообщение отправлено | | ------------- | ----------------------- | | `undelivered` | Сообщение не доставлено | | `delivered` | Сообщени доставлено | | `read` | Сообщение прочитано | ### `MAILING_REACTION` Реакция на отправленной сообщение в рассылкjs {% tabs %} {% tab title="Пример события" %} ```json { "event_type": "mailing.reaction", "payload": { "uuid": "04191c1d-e7dd-4572-a544-6eb9c2855a5e", "chat": { "uuid": "a5f14878-bfdc-4af4-8b3c-249f6998f6f4", "platform": "Telegram" }, "type": "URL" }, "timestamp": 1651776060.8439758 } ``` {% endtab %} {% tab title="Параметры события" %} | `event_type` | Тип события | | -------------------------- | --------------------------------- | | `payload` | Информация о событии | | > `payload.uuid` | Информация о клиенте | | > `payload.chat` | Информация о пользователе | | >> `payload.chat.uuid` | Уникальный идентификатор профиля | | >> `payload.chat.platform` | Название канала | | > `payload.type` | Тип реакции | | `timestamp` | Уникальный идентификатор рассылки | | {% endtab %} | | | {% endtabs %} | | **Список реакций** | `URL` | Переход по ссылке | | ------- | ------------------- | | `CLICK` | Нажатие на кнопку | | `REPLY` | Ответное сообщение | | `READ` | Сообщение прочитано | --- # 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://docs.fstrk.io/knowledge_base/outbound-campaigns/mailings-wa/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.