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

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 символа)

Теги и атрибуты в profile задаются только если они уже существуют в системе. Новые теги и атрибуты через этот метод не создаются.

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

Пример ответа:

{
  "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
}

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

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

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

# Отправить текст по 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": "[phone]" },
    "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": "[phone]" },
    "content": {
      "type": "TELEGRAM_PERSONAL_TEXT",
      "text": "Здравствуйте! Хотим сообщить об акции."
    }
  }'

---

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

🔒 bot-key или OAuth

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

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

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

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

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

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

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 — сообщение уже отправлено или в процессе.

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

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