Рассылки в WhatsApp: описание API & Webhooks
Работа с API
OAuth-авторизация
Для работы с Fasttrack API вам понадобится уникальный access_token
, которым необходимо передавать в заголовке для каждого запроса. Следуйте инструкции ниже, чтобы получить ключ доступа для вашего проекта:
Шаг 1: Подготовить redirect_uri
redirect_uri
— это URL, на который сервер перенаправит вас после успешной авторизации, передавая временный код (code
). Этот код затем используется приложением для обмена на ключ доступа (access_token
).
Шаг 2: Зарегистрировать приложение
Сообщите менеджеру о том, что планируете использовать Fasttrack API и предоставьте redirect_uri
для регистрации вашего приложения.
Данные о приложении, которые вы получите:
client_id
Идентификатор вашего приложения.
client_secret
Защищённый ключ вашего приложения
Внимание! Параметр client_secret
используется для идентификации и подтверждения подлинности вашего приложения в процессе OAuth-авторизации. Этот параметр является конфиденциальным и должен защищаться так же строго, как и пароли.
Шаг 3: Получить временый код авторизации
Сформируйте URL следующего вида:
https://dashboard.fstrk.io/integrations/oauth/?{параметры}
После знака ?
в URL укажите следующие параметры:
client_id
* – Идентификатор вашего приложения;redirect_uri
* – URL для получения временного кода авторизацииstate
– Произвольная строка, которая будет передана вместе с кодом.
Пример URL:
https://dashboard.fstrk.io/integrations/oauth/?client_id=1&redirect_uri=https://example.com/oauth/&state=dummy
Перейдите по ссылке. Вы попадете на страницу со списком доступных проеков (их может быть несколько). Выберите проект для которого планируете получить access_token
.
Браузер переадресует вас обратно на URL, указанный в параметре redirect_uri
с добавлением параметров state
и временного кода авторизации (code
).
Шаг 5: Получить access_token
POST https://dashboard.fstrk.io/api/partners/oauth/
Метод для получения access_token
в рамках OAuth-авторизации.
Пример запроса:
curl -X POST \
--location https://dashboard.fstrk.io/api/partners/oauth/ \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"grant_type": "code",
"code": "<CODE>"
}'
При успешном выполнении запроса API возвращает код ответа 200
и JSON-объект с параметром access_token
.
Формат запросов
API работает по протоколу HTTP(S) и поддерживает методы REST (Representational State Transfer), такие как GET
, POST
, PUT
, PATCH
и DELETE
. Каждый запрос имеет стандартный формат и требует обязательного использования корректных заголовков и параметров.
Базовый URL
https://dashboard.fstrk.io/api/partners/
Заголовки
Каждый запрос к API Fasttrack требует заголовок Authorization
для подтверждения прав доступа. Без этого заголовка сервер не обработает запрос и вернет ошибку.
Authorization: Bearer { access_token }
Для корректной работы с API Fasttrack запросы, которые передают данные, должны содержать заголовок Content-Type. Он указывает, что данные в запросе отправляются в формате JSON.
Content-Type: application/json
Также рекомендуется указывать заголовок Accept, чтобы явно запросить от сервера ответы в формате JSON. Это обеспечивает корректное восприятие данных на стороне клиента.
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/
Для тестирования, необходимо авторизоваться в Fasttrack.
Создание рассылки
POST /mailings/
Универсальный метод для создания новой рассылки.
Заголовки
Content-Type
application/json
Authorization
Bearer { 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) – Список заполненных переменных для шаблона.
{
// ...
"template_whatsapp": "name_of_approved_template",
"template_variables": {
"v1": {
"type": "GLOBAL",
"value": "demo_mailing"
},
"v2": {
"type": "FILE"
}
}
// ...
}
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
. Они демонстрируют различные сценарии использования и настройки параметров для создания рассылок.
Результат запроса
При успешном выполнении запроса API возвращает код ответа 201
и JSON-объект с информацией о рассылке, включая полный набор параметров.
Пример ответа:
Список рассылок
GET /mailings/
Метод для получения списка всех созданных рассылок.
Заголовки
Authorization
Bearer { 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-объект с информацией о рассылке, включая полный набор параметров.
Информация о рассылке
GET /mailings/{ uuid }/
Метод для получения информации о рассылке по ее идентификатору (UUID).
Заголовки
Authorization
Bearer { access_token }
Path-параметры
uuid
*
Идентификатор рассылки
Пример запроса
curl -X GET \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid } \
--header 'Authorization: Bearer { access_token }'
Результат запроса
При успешном выполнении запроса API возвращает код ответа 200
и JSON-объект с информацией о рассылке, включая полный набор параметров.
Подсчет статистики
POST /mailings/{ uuid }/calculate/
Метод для подсчета статистики для рассылки по ее идентификатору (UUID).
Устаревший метод. Статистика в рассылках по аудиториии проекта обновляется автоматически, поэтому данный метод на сегодняшний день не актуален.
Заголовки
Authorization
Bearer { access_token }
Path-параметры
uuid
*
Идентификатор рассылки
Пример запроса
curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/calculate/ \
--header 'Authorization: Bearer { access_token }'
Результат запроса
При успешном выполнении запроса API возвращает код ответа 200
и JSON-объект с информацией о рассылке, включая полный набор параметров.
Остановка рассылки
POST /mailings/{ uuid }/stop/
Метод, который используется, чтобы остановить рассылку, которая уже началась.
Заголовки
Authorization
Bearer { access_token }
Path-параметры
uuid
*
Идентификатор рассылки
Пример запроса
curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/stop/ \
--header 'Authorization: Bearer { access_token }'
Результат запроса
При успешном выполнении запроса API возвращает код ответа 200
и JSON-объект с информацией о рассылке, включая полный набор параметров.
Вебхуки
API Fasttrack предоставляет возможность подписаться на уведомления о событиях, которые связаны с отправленными рассылками по аудитории проекта.
Типы событий, связанных с рассылками по аудитории:
MAILING_STATE
Статусы сообщений в рассылке
MAILING_REACTION
Реакции на сообщения в рассылке
Настройка уведомлений
Откройте настройки проекта → Раздел "Вебхуки"
Заполните поле [ Endpoint URL ]
Активируйте события
MAILING_REACTION
иMAILING_STATE
MAILING_STATE
MAILING_STATE
Cмена статуса отправленного сообщения в рассылке.
{
"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
}
Статусы сообщений
sent
Сообщение отправлено
undelivered
Сообщение не доставлено
delivered
Сообщени доставлено
read
Сообщение прочитано
MAILING_REACTION
MAILING_REACTION
Реакция на отправленной сообщение в рассылкjs
{
"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
}
Список реакций
URL
Переход по ссылке
CLICK
Нажатие на кнопку
REPLY
Ответное сообщение
READ
Сообщение прочитано
Last updated