> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/api/obshaya-informaciya/metody-dlya-integracii.md).

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

#### 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

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

```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
  }'
```

{% hint style="info" %}

#### Все примеры представлены в [swagger](https://dashboard.fstrk.io/api/partners/docs/#/01.%20%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B%20%D0%B4%D0%BB%D1%8F%20%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8/connector_create)

{% endhint %}

***

#### POST /api/partners/iframe/

🔒 *Только OAuth*

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

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

[Читать подробнее.](/knowledge_base/chat_center/iframe.md)

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

* `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

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

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

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

```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": "Триггерная кампания"
      }
    }
  }'
```