Аудиторные рассылки

GET /api/partners/mailings/

🔒 bot-key или OAuth

Кратко: Получить список всех созданных рассылок.

Параметры запроса:

• limit (integer, опциональный) — кол-во элементов на странице (макс. 100)

• offset (integer, опциональный) — кол-во элементов для пропуска

Возвращает: 200 OK — постраничный список объектов Mailing.

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

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

curl -X GET "https://dashboard.fstrk.io/api/partners/mailings/?limit=50" \
  -H "bot-key: your_bot_key"

---

POST /api/partners/mailings/

🔒 bot-key или OAuth

Кратко: Создать новую аудиторную рассылку.

Что делает: Создаёт рассылку по динамическому фильтру чатов или по файлу/массиву идентификаторов клиентов. Поддерживает отправку текста, узла сценария и WhatsApp-шаблонов (WABA). Может запустить рассылку немедленно, в запланированное время или по CRON-расписанию (регулярная рассылка).

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

• name (string, обязательный) — название рассылки (1–80 символов)

• content_type (string, опциональный) — тип контента: TEXT, NODE, TEMPLATE_WHATSAPP, MIXED

• text (string, опциональный) — текст сообщения (при content_type: TEXT)

• node_name (string, опциональный) — название узла сценария (при content_type: NODE)

• node_get_params (array, опциональный) — параметры для узла: [{ "name": "key", "type": "string", "value": "val" }]

• filter_chats (object, опциональный) — динамический фильтр аудитории (структура all: [...])

• customer_filter_field (string, опциональный) — поле идентификации клиентов из файла/массива: UUID, EXTERNAL_ID, PHONE_NUMBER, CHAT_UUID

• customer_filter_file (string, uri, опциональный) — URL файла с идентификаторами клиентов

• customer_filter_array (array of string, опциональный) — массив идентификаторов клиентов

• phone_numbers_file (string, uri, опциональный) — URL XLSX-файла с номерами телефонов (для WABA)

• template_whatsapp (string, опциональный) — название согласованного WhatsApp-шаблона

• template_variables (object, опциональный) — переменные шаблона

• planned_at (string, date-time, опциональный) — дата запланированной отправки

• regular_cron (string, опциональный) — CRON-расписание для регулярной рассылки (например, 00 12 * * *)

• origin (string, опциональный) — chat_center для отправки сквозь открытую чат-сессию

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

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

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

# Отправить текст по динамическому фильтру (Telegram, московское время)
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Летняя акция",
    "filter_chats": {
      "all": [
        { "platform": "Telegram", "type": "attribute" },
        { "timezone": "Europe/Moscow", "type": "profile_attribute" }
      ]
    },
    "content_type": "TEXT",
    "text": "Привет! Специальное предложение только сегодня 🎁"
  }'

# Запланировать рассылку с узлом
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Акция сентябрь",
    "filter_chats": {
      "all": [
        { "platform": "Vkontakte", "type": "attribute" }
      ]
    },
    "content_type": "NODE",
    "node_name": "Приветственный узел",
    "node_get_params": [
      { "name": "promo", "type": "string", "value": "FALL2024" }
    ],
    "planned_at": "2024-09-01T10:00:00+03:00"
  }'

# Регулярная рассылка каждый день в 12:00 UTC
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "Ежедневная рассылка",
    "filter_chats": {
      "all": [
        { "platform": "Telegram", "type": "attribute" }
      ]
    },
    "content_type": "NODE",
    "node_name": "Дайджест",
    "regular_cron": "00 12 * * *"
  }'

# WABA рассылка по файлу с номерами телефонов
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "WABA акция",
    "phone_numbers_file": "https://example.com/phones.xlsx",
    "content_type": "TEMPLATE_WHATSAPP",
    "template_whatsapp": "order_confirmation",
    "template_variables": {
      "v1": { "type": "GLOBAL", "value": "Акция!" },
      "v2": { "type": "FILE" }
    }
  }'

# Рассылка по UUID-профилям из файла
curl -X POST https://dashboard.fstrk.io/api/partners/mailings/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "name": "VIP рассылка",
    "customer_filter_field": "UUID",
    "customer_filter_file": "https://example.com/vip_uuids.csv",
    "content_type": "NODE",
    "node_name": "VIP узел"
  }'

---

GET /api/partners/mailings/{uuid}/

🔒 bot-key или OAuth

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

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

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

Возвращает: 200 OK — объект Mailing со статистикой.

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

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Летняя акция",
  "state": "completed",
  "content_type": "TEXT",
  "text": "Привет! Специальное предложение только сегодня 🎁",
  "created_at": "2024-06-01T09:00:00Z",
  "planned_at": null,
  "completed_at": "2024-06-01T09:45:00Z",
  "duration": "00:45:00",
  "statistics": {
    "count_planned": 10000,
    "count_sent": 9850,
    "count_delivered": 9600,
    "count_undelivered": 250,
    "count_read": 7200,
    "count_clicked": 1500,
    "count_jumped_url": 1100,
    "count_replied": 430,
    "count_platforms": {
      "Telegram": 6000,
      "Vkontakte": 4000
    }
  }
}

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

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

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

---

POST /api/partners/mailings/{uuid}/calculate/

🔒 bot-key или OAuth

Кратко: Пересчитать статистику рассылки.

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

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

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

Возвращает: 200 OK — объект Mailing с обновлённой статистикой.

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

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

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

---

POST /api/partners/mailings/{uuid}/stop/

🔒 bot-key или OAuth

Кратко: Остановить запущенную рассылку.

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

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

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

Возвращает: 200 OK — объект Mailing с обновлённым статусом.

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

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

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