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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fstrk.io/knowledge_base/api/obshaya-informaciya/metody-dlya-integracii.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.