# 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` | Сообщение прочитано |