Методы для интеграции

POST /api/partners/oauth/

🔓 Авторизация не требуется

Кратко: Получить или обновить OAuth-токен доступа.

Что делает: Выполняет OAuth 2.0-авторизацию. Поддерживает два режима: первичный обмен временного кода на токен доступа (grant_type: code) и обновление существующего токена по refresh_token (grant_type: refresh_token). Метод не требует предварительной авторизации — используется на начальном этапе подключения интеграции.

Тело запроса:

client_id (string, обязательный) — идентификатор интеграции
client_secret (string, обязательный) — секретный ключ интеграции
grant_type (string, обязательный) — тип запроса: code или refresh_token
code (string, опциональный) — временный код из первичной OAuth 2.0 авторизации (при grant_type: code)
refresh_token (string, опциональный) — токен обновления (при grant_type: refresh_token)

Возвращает: 200 OK:

access_token (string) — токен доступа
refresh_token (string) — токен обновления
token_type (string) — тип токена
expires_in (integer) — время жизни токена в секундах

Ошибки: 400 — неверные client_id или client_secret.

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

bash

# Обмен кода на токен
curl -X POST https://dashboard.fstrk.io/api/partners/oauth/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "code",
    "code": "temporary_code"
  }'

# Обновление токена
curl -X POST https://dashboard.fstrk.io/api/partners/oauth/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "refresh_token",
    "refresh_token": "your_refresh_token"
  }'

POST /api/partners/connector/

🔒 Только OAuth

Кратко: Универсальный метод для обмена событиями между внешней интеграцией и платформой.

Что делает: Принимает события трёх типов: создание сообщения (message_created), закрытие сессии (session_closed) и создание заметки (note_created). Позволяет отправлять текст, изображения, документы, WhatsApp-шаблоны, инициировать новые чаты через WhatsApp или Telegram Personal по номеру телефона или юзернейму. При закрытии сессии можно передать категорию и тему.

Тело запроса:

event (string, обязательный) — тип события: message_created — при отправке сообщения, session_closed — при закрытии чат-сессии, note_created — при отправке заметки
chat (object, обязательный):
- uuid (uuid) — UUID чата (обязателен при отсутствии phone_number)
- phone_number (string) — номер телефона (для инициации чата в WhatsApp/Telegram)
- username (string) — юзернейм (для инициации чата в Telegram Personal)
- variables (object) — переменные для добавления в контекст чата
sender (object, обязательный):
- name (string) — имя отправителя
- uuid (uuid) — UUID оператора на платформе Fasttrack
timestamp (integer, обязательный) — время события в миллисекундах (Unix)
message (object, опциональный):
- type (string, обязательный) — text, image, document, whatsapp_template, whatsapp_text, telegram_personal_text
- text (string) — текст (при type: text, whatsapp_text, telegram_personal_text)
- url (string, uri) — URL изображения или документа
- whatsapp_template (object) — шаблон: template_id, template_variables
- external_id (string) — идентификатор на стороне интеграции
note (object, опциональный) — заметка: text (string, обязательный)
session (object, опциональный) — при закрытии: category_name, theme_name

Возвращает: 200 OK:

status (string) — статус операции
chat_uuid (uuid) — UUID чата
profile_uuid (uuid) — UUID профиля клиента
message_uuid (uuid) — UUID созданного сообщения
external_id (string) — внешний идентификатор

Ошибки: 400 — некорректные данные; 403 — ошибка авторизации.

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

bash

# Отправить текстовое сообщение в существующий чат
curl -X POST https://dashboard.fstrk.io/api/partners/connector/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "event": "message_created",
    "chat": {
      "uuid": "00000000-0000-0000-0000-000000000000"
    },
    "message": {
      "type": "text",
      "text": "Текстовое сообщение"
    },
    "sender": {
      "name": "Иван",
      "uuid": "00000000-0000-0000-0000-000000000000"
    },
    "timestamp": 1624607235580
  }'
# Отправить картинку в существующий чат
curl -X POST https://dashboard.fstrk.io/api/partners/connector/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "event": "message_created",
    "chat": {
      "uuid": "00000000-0000-0000-0000-000000000000"
    },
    "message": {
      "type": "image",
      "url": "https://dashboard.fstrk.io/static/img/control-push-example.jpg"
    },
    "sender": {
      "name": "Иван",
      "uuid": "00000000-0000-0000-0000-000000000000"
    },
    "timestamp": 1624607235580
  }'

# Закрыть сессию с категорией и темой
curl -X POST https://dashboard.fstrk.io/api/partners/connector/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "event": "session_closed",
    "chat": {
      "uuid": "00000000-0000-0000-0000-000000000000"
    },
    "sender": {
      "name": "Иван"
    },
    "session": {
      "category_name": "Техподдержка",
      "theme_name": "Проблема с оплатой"
    },
    "timestamp": 1624607235580
  }'

Все примеры представлены в swagger

POST /api/partners/iframe/

🔒 Только OAuth

Кратко: Сформировать временную ссылку для встраивания чат-центра через iframe.

Что делает: Генерирует временный URL для работы чат-центра в формате inline frame с контекстом оператора и, опционально, профиля клиента.

Читать подробнее.

Тело запроса:

operator (object, обязательный):
- uuid (uuid, опциональный) — UUID оператора
- email (string, опциональный) — email оператора
profile (object, опциональный):
- uuid (uuid) — UUID профиля
- phone_number (string) — номер телефона
- external_id (string) — внешний идентификатор

Возвращает: 201 Created:

url (string, uri) — временная ссылка на iframe
expired_at (string, date-time) — дата и время истечения ссылки

Ошибки: 403 — ошибка авторизации.

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

bash

curl -X POST \ 
  --location https://dashboard.fstrk.io/api/partners/iframe/ \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer your_access_token" \
  --data '{
    "operator": {
      "uuid": "378737c4-e659-479a-9ba9-5307b81084a5"
      // или "email": "operator@example.com"
    },
    "profile": {
      "uuid": "f6e9f169-f4ce-4e3b-b340-d9b36133aec1"
      // или "external_id": "client-123"
      // или "phone_number": "+79991112233"
    }
  }'

PUT /api/partners/integrations/credentials/

🔒 Только OAuth

Кратко: Настроить или обновить параметры webhook-интеграции.

Что делает: Задаёт настройки вебхука: URL для получения событий, список типов событий и платформ. Полностью заменяет текущие настройки.

Тело запроса:

webhook_url (string, uri, обязательный) — URL для отправки событий
webhook_events (array of string, опциональный) — события: message_created, message_updated, operator_replied, session_updated, stream.status, stream.reaction
webhook_platforms (array of string, опциональный) — платформы: Telegram, Facebook, Instagram, Viber, Whatsapp, Vkontakte, Widget, Odnoklassniki, Email, API_Messenger, Avito, Auto_Ru, Max, Ozon, Telegram_Personal, Max_Personal

Возвращает: 200 OK — объект с текущими настройками интеграции.

Ошибки: 400 — некорректный URL или данные; 403 — ошибка авторизации.

Ваш сервис должен отвечать всегда код 200, иначе при подключении будет ошибка {"webhook_url":["URL для отправки событий недоступен."]}

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

bash

curl -X PUT https://localhost:8080/api/partners/integrations/credentials/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
  "webhook_url": "https://your-crm.com/webhook",
  "webhook_events": [
    "message_created",
    "message_updated",
    "operator_replied",
    "session_updated"
  ],
  "webhook_platforms": [
    "Telegram",
    "Whatsapp",
    "Viber",
    "Vkontakte",
    "Widget",
    "Instagram",
    "Odnoklassniki",
    "Facebook",
    "Email",
    "API_Messenger",
    "Avito",
    "Auto_Ru",
    "Max",
    "Ozon",
    "Telegram_Personal",
    "Max_Personal"
  ]
}'

DELETE /api/partners/integrations/credentials/

🔒 Только OAuth

Кратко: Полностью отключить интеграцию и удалить её настройки.

Что делает: Удаляет все настройки текущей интеграции. Действие необратимо.

Параметры: Нет.

Возвращает: 204 No Content.

Ошибки: 403 — ошибка авторизации.

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

bash

curl -X DELETE https://localhost:8080/api/partners/integrations/credentials/ \
  -H "Authorization: Bearer your_access_token"

POST /api/partners/stream/

🔒 Только OAuth

Кратко: Поставить сообщение в потоковую очередь отправки клиенту.

Что делает: Добавляет сообщение в приоритетную (priority_message) или общую (regular_message) очередь. Приоритетная используется для триггерных коммуникаций, общая — для рассылочных. Пропускная способность метода — 20 запросов в секунду.

Тело запроса:

type (string, обязательный) — priority_message или regular_message
payload (object, обязательный) — тело сообщения (чат/профиль, контент, кампания — аналогично структуре Push-сообщения)

Возвращает: 201 Created:

uuid (uuid) — идентификатор задачи в очереди

Ошибки: 429 — превышено кол-во запросов в секунду; 403 — ошибка авторизации.

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

bash

# Приоритетная отправка узла в Telegram (триггерная коммуникация)
curl -X POST https://dashboard.fstrk.io/api/partners/stream/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "type": "priority_message",
    "payload": {
      "chat": {
        "telegram_id": 123456789
      },
      "content": {
        "type": "NODE",
        "node": {
          "name": "Приветственный узел"
        },
        "get_params": {
          "foo": "bar"
        }
      },
      "campaign": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "Триггерная кампания"
      }
    }
  }'

PreviousОбщая информация NextИнформация о настройках

Last updated 25 days ago