API & Webhooks | Fasttrack

Рассылки по аудитории: описание 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 /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) * – название рассылки.

Пример: "Моя первая рассылка"

filter_chats (object) – фильтр пользователей. Укажите условия и критерии, которым должны соответствовать пользователи, чтобы получить рассылку.

Пример

{
  // ...
  "filter_chats": {
    "all": [
      {
        "platform": "Telegram",
        "type": "attribute"
      },
      {
        "timezone": "Europe/Moscow",
        "type": "profile_attribute"
      },
      {
        "pda_agreed__isnull": false,
        "type": "profile_tag"
      }
    ]
  },
  // ...
}

content_type (string) – тип контента.

Значения: "NODE" "TEXT"

Заметка: используйте значение NODE для запуска сценария, настроенного на платформе Fasttrack и TEXT для отправки обычного текстового сообщения.

text (string) – содержание текстового сообщения.

Пример

{
  // ...
  "content_type": "TEXT",
  "text": "Привет, мир!"
  // ...
}

node_name (string) – название сценария на платформе Fasttrack.

Пример

{
  ...
  "content_type": "NODE",
  "node_name": "Сценарий для демо рассылки"
  ...
}

Заметка: можно использовать параметр node, если нужно указать ID сценария, а не его название. Название может измениться, а идентификатор постоянный.

node (integer) – ID сценария на платформе Fasttrack.

Пример

{
  // ...
  "content_type": "NODE",
  "node": 73787
  // ...
}

Заполняется для рассылок с типом контента NODE.

Заметка: если передать в запросе одновременно параметры node и node_name, то приоритет будет у параметра node.

node_get_params (array) – список параметров для сценария.

Каждый объект в массиве содержит следующие поля:

name (string): название параметра
value (string): значение параметра

{
  // ...
  "content_type": "NODE",
  "node_name": "Сценарий для демо рассылки",
  "node_get_params": [
      {
        "name": "discount_code",
        "value": "WELCOME10"
      },
      {
        "name": "campaign_id",
        "value": "spring_sale_2024"
      }
    ]
  // ...
}

Указанные параметры и их значения будут доступны и могут быть обработаны в контексте выбранного сценария.

customer_filter_field (string) – идентификатор профиля для рассылок по готовому списку клиентов.

Значения: "UUID" "EXTERNAL_ID" "PHONE_NUMBER"

Список идентификаторов может быть передан через файл (см. customer_filter_file) или сразу в теле запроса (см. customer_filter_array)

customer_filter_file (string) – ссылка на файл со списком идентификаторов для рассылок по готовому списку клиентов.

Расширение файла .CSV
Файл должен быть загружен на S3
Название колонки соответствует значению customer_filter_field (в нижнем регистре)

Пример

{
  // ...
  "customer_filter_field": "UUID",
  "customer_filter_file": "https://example.com/file.csv"
  // ...
}

customer_filter_array (array) – список идентификаторов для рассылок по готовому списку клиентов.

Пример

{
  // ...
  "customer_filter_field": "UUID",
  "customer_filter_array": [
    "f108a674-1160-4049-8a37-eaab83bd9cd4",
    "7a0b517c-2f0b-407f-87e6-13eb651c32e1"
  ]
  // ...
}

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

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "content_type": "NODE",
  "node_name": "Название сценария",
  "node_get_params": [
    {
      "name": "foo",
      "type": "string",
      "value": "bar"
    },
    {
      "name": "foo1",
      "type": "string",
      "value": "bar1"
    }
  ]
}'

2. Рассылки по аудитории: Использование фильтра

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "filter_chats": {
    "all": [
      {
        "platform": "Telegram",
        "type": "attribute"
      },
      {
        "timezone": "Europe/Moscow",
        "type": "profile_attribute"
      },
      {
        "pda_agreed__isnull": false,
        "type": "profile_tag"
      }
    ]
  },
  "content_type": "TEXT",
  "text": "Привет, мир!"
}'

3. Рассылки по аудитории: Отложенная рассылка

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "content_type": "NODE",
  "node_name": "Название сценария",
  "planned_at": "2024-09-16T19:41:02.768Z"
}'

4. Рассылки по аудитории: Регулярная рассылка

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "content_type": "NODE",
  "node_name": "Название сценария",
  "regular_cron": "00 12 * * *"
}'

5. Рассылки по аудитории: Готовый список клиентов (список в файле)

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
    "name": "Название рассылки",
    "content_type": "NODE",
    "node_name": "Название сценария",
    "node_get_params": [
      {
        "name": "foo",
        "type": "string",
        "value": "bar"
      }
    ],
    "customer_filter_field": "UUID",
    "customer_filter_file": "https://example.com/file.csv"
  }'

6. Рассылки по аудитории: Готовый список клиентов (список в теле запроса)

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "content_type": "NODE",
  "node_name": "Название сценария",
  "node_get_params": [
    {
      "name": "foo",
      "type": "string",
      "value": "bar"
    }
  ],
  "customer_filter_field": "PHONE_NUMBER",
  "customer_filter_array": [
    "+79999999998",
    "+79999999999"
  ]
}'

7. Рассылки по аудитории: Доставка сообщений, если открыт чат с оператором

curl -X POST \
--location https://dashboard.fstrk.io/api/partners/mailings/ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access_token }' \
--data '{
  "name": "Название рассылки",
  "content_type": "NODE",
  "node_name": "Название сценария",
  "origin": "chat_center"
}'

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

При успешном выполнении запроса 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`

Реакция на отправленной сообщение в рассылке.

{
 "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Рассылки в WhatsApp

Last updated 1 year ago