> 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/personalnye-soobsheniya.md).

# Персональные сообщения

#### POST /api/partners/push-messages/

🔒 *bot-key или OAuth*

**Кратко:** Создать и отправить персональное сообщение конкретному подписчику или клиенту.

**Что делает:** Отправляет сообщение в чат подписчика. Получателя можно указать через UUID чата, Telegram ID, VK ID, username или через UUID/телефон/external\_id профиля клиента. Поддерживает текст, узлы сценария, WhatsApp-шаблоны и инициацию чатов в Telegram Personal и Max Personal. Сообщение можно запланировать через `launch_at`.

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

* `content` (object, обязательный):
  * `type` (string, обязательный) — тип контента: `TEXT`, `NODE`, `WHATSAPP_TEMPLATE`, `WHATSAPP_TEXT`, `TELEGRAM_PERSONAL_TEXT`, `TELEGRAM_PERSONAL_NODE`, `MAX_PERSONAL_TEXT`, `MAX_PERSONAL_NODE`
  * `text` (string) — текст сообщения (при `type: TEXT`, `WHATSAPP_TEXT`, `TELEGRAM_PERSONAL_TEXT`, `MAX_PERSONAL_TEXT`)
  * `node` (object) — узел сценария: `name` (string) — при `type: NODE`, `TELEGRAM_PERSONAL_NODE`, `MAX_PERSONAL_NODE`
  * `get_params` (object) — параметры для передачи в узел
  * `whatsapp_template` (object) — шаблон: `pid` (string) — при `type: WHATSAPP_TEMPLATE`
  * `whatsapp_template_variables` (object) — переменные для шаблона
* `chat` (object, опциональный) — идентификатор чата-получателя (одно из полей):
  * `uuid` (uuid) — UUID чата
  * `telegram_id` (integer) — Telegram ID подписчика
  * `telegram_username` (string) — username в Telegram
  * `vkontakte_id` (integer) — ID во ВКонтакте
  * `max_id` (integer) — Max ID подписчика
* `profile` (object, опциональный) — идентификатор профиля клиента (одно из полей):
  * `uuid` (uuid) — UUID профиля
  * `phone_number` (string) — номер телефона в формате E.164
  * `external_id` (string) — внешний идентификатор
* `campaign` (object, опциональный) — привязка к кампании:
  * `uuid` (uuid) — UUID кампании
  * `name` (string) — название кампании
* `launch_at` (string, date-time, опциональный) — дата запланированной отправки (с точностью до минуты)
* `is_force` (boolean, опциональный) — пробивать ли открытую чат-сессию
* `tag` (string, опциональный) — тег сообщения (максимум 64 символа)

{% hint style="info" %}
Теги и атрибуты в `profile` задаются только если они уже существуют в системе. Новые теги и атрибуты через этот метод не создаются.
{% endhint %}

**Возвращает:** `201 Created` — объект `PushMessage`.

<details>

<summary>Пример ответа:</summary>

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "chat": {
    "uuid": "7ab1c234-5678-4def-a012-3456789bcdef",
    "platform": "Telegram"
  },
  "state": {
    "code": "PENDING",
    "detail": ""
  },
  "content": {
    "type": "TEXT",
    "text": "Привет!"
  },
  "launch_at": null,
  "created_at": "2024-06-01T10:00:00Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null
}
```

</details>

**Статусы сообщения (`state.code`):** `PENDING`, `IN_PROCESS`, `SENT`, `DELIVERED`, `READ`, `UNDELIVERED`, `CANCELLED`, `ERROR`.

**Ошибки:** 400 — некорректные данные; 401 — ошибка авторизации; 404 — чат или профиль не найден.

**Примеры запросов:**

```bash
# Отправить текст по UUID чата
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "chat": { "uuid": "00000000-0000-0000-0000-000000000000" },
    "content": { "type": "TEXT", "text": "Привет! Как дела?" }
  }'

# Отправить узел по UUID чата с привязкой к кампании
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "chat": { "uuid": "00000000-0000-0000-0000-000000000000" },
    "content": {
      "type": "NODE",
      "node": { "name": "Приветственный узел" },
      "get_params": { "promo": "SUMMER2024" }
    },
    "campaign": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "name": "Летняя акция"
    }
  }'

# Запланировать отправку
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "chat": { "uuid": "00000000-0000-0000-0000-000000000000" },
    "content": { "type": "TEXT", "text": "Напоминаем о вашей записи!" },
    "launch_at": "2024-09-16T09:00:00+03:00"
  }'

# Отправить WhatsApp-шаблон по номеру телефона
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "profile": { "phone_number": "+79001234567" },
    "content": {
      "type": "WHATSAPP_TEMPLATE",
      "whatsapp_template": { "pid": "order_confirmation" },
      "whatsapp_template_variables": { "v1": "Иван", "v2": "12345" }
    }
  }'

# Инициировать чат в Telegram Personal
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "profile": { "phone_number": "+79001234567" },
    "content": {
      "type": "TELEGRAM_PERSONAL_TEXT",
      "text": "Здравствуйте! Хотим сообщить об акции."
    }
  }'
```

***

#### GET /api/partners/push-messages/{uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Получить информацию о персональном сообщении по UUID.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID сообщения

**Возвращает:** `200 OK` — объект `PushMessage`.

**Ошибки:** 401 — ошибка авторизации; 404 — сообщение не найдено.

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

```bash
curl -X GET https://dashboard.fstrk.io/api/partners/push-messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/ \
  -H "bot-key: your_bot_key"
```

***

#### POST /api/partners/push-messages/{uuid}/cancel/

🔒 *bot-key или OAuth*

**Кратко:** Отменить запланированную отправку персонального сообщения.

**Что делает:** Отменяет отправку сообщения со статусом `PENDING`. Сообщения, уже находящиеся в процессе отправки или отправленные, отменить нельзя.

**Параметры пути:**

* `uuid` (string, обязательный) — UUID сообщения

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

**Возвращает:** `204 No Content` — в случае успешной отмены.

**Ошибки:** 401 — ошибка авторизации; 404 — сообщение не найдено; 400 — сообщение уже отправлено или в процессе.

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

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/push-messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel/ \
  -H "bot-key: your_bot_key"
```