API & Webhooks | Fasttrack

Рассылки в WhatsApp: описание API & Webhooks

Работа с API

OAuth-авторизация

Для работы с Fasttrack API вам понадобится уникальный access_token, которым необходимо передавать в заголовке для каждого запроса. Следуйте инструкции ниже, чтобы получить ключ доступа для вашего проекта:

Важно! Временно, приложения клиентов для использования API Fasttrack, регистрируются вручную, через менеджеров проекта.

Шаг 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.

200

{
  "access_token": "string"
}

Формат запросов

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. Они демонстрируют различные сценарии использования и настройки параметров для создания рассылок.

1. Рассылка в WhatsApp: Шаблон без переменных

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: Шаблон с переменными (значения в теле запроса)

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: Шаблон с переменными (значения в файле)

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: Шаблон с переменными (смешанный вариант)

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

{
  "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/

Метод для получения списка всех созданных рассылок.

Заголовки

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-объект с информацией о рассылке, включая полный набор параметров.

200

{
  "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).

Заголовки

Authorization

Bearer { access_token }

Path-параметры

uuid *

Идентификатор рассылки

Пример запроса

curl -X GET \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid } \
--header 'Authorization: Bearer { access_token }'

Результат запроса

200

{
  "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).

Устаревший метод. Статистика в рассылках по аудиториии проекта обновляется автоматически, поэтому данный метод на сегодняшний день не актуален.

Заголовки

Authorization

Bearer { access_token }

Path-параметры

uuid *

Идентификатор рассылки

Пример запроса

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/calculate/ \
--header 'Authorization: Bearer { access_token }'

Результат запроса

200

{
  "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/

Метод, который используется, чтобы остановить рассылку, которая уже началась.

Заголовки

Authorization

Bearer { access_token }

Path-параметры

uuid *

Идентификатор рассылки

Пример запроса

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/{ uuid }/stop/ \
--header 'Authorization: Bearer { access_token }'

Результат запроса

200

{
  "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мена статуса отправленного сообщения в рассылке.

{
 "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`

Реакция на отправленной сообщение в рассылк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

Сообщение прочитано

PreviousИнтерфейс платформы NextПерсональные рассылки

Last updated 1 year ago