Отправка сообщений: справочник эндпоинтов

Этот справочник дополняет сценарий «Отправка сообщений из вашей системы» деталями по каждому эндпоинту: полями запроса, форматом ответа и краевыми случаями. Все запросы выполняются с Bearer-токеном компании и в её контексте.

GET /channels

Список каналов, доступных текущему пользователю в рамках компании — используйте, чтобы узнать channel_id для /messages/send.

{
  "data": [
    {
      "id": 57,
      "name": "WhatsApp test",
      "account_name": "+77084252291",
      "status": "connected",
      "message_operations": {
        "can_create": true,
        "can_edit": true,
        "edit_window_seconds": 900,
        "revoke_window_seconds": 172800
      },
      "limits": {
        "max_text_length": 4096,
        "file_limits": { "image": { "max_size_mb": 16 }, "video": { "max_size_mb": 64 } }
      },
      "channel_type": { "id": 1, "key": "whatsapp", "name": "WhatsApp" },
      "broadcast_rate_limits": { "daily_limit": 1500, "messages_per_minute": 15 }
    }
  ]
}

Перед отправкой проверяйте status === "connected" и message_operations.can_create === true.

POST /uploads

Загружает файл в AISAR и возвращает компактный media_id, который подставляется в /messages/send. Доставка в мессенджер выполняется коннектором без повторного скачивания. Поддерживаются два режима.

Режим A — multipart-загрузка

POST /v1/uploads
Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data

file=@photo.jpg

Максимум 64 МБ. Разрешённые расширения: jpg, jpeg, png, gif, webp, bmp, svg, mp4, mov, avi, wmv, webm, mkv, mp3, ogg, wav, aac, flac, m4a, opus, amr, pdf, doc, docx, xls, xlsx, csv, txt, rtf, ppt, pptx, zip, rar, 7z, gz, json, xml.

Режим B — загрузка по URL

POST /v1/uploads
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "url": "https://cdn.example.com/photo.jpg" }

AISAR один раз скачивает файл, сохраняет в своё хранилище и возвращает media_id. URL обязательно http/https, размер ≤ 64 МБ, таймаут скачивания 20 сек.

{
  "media_id": "med_01HZABCDEFGHIJKLMNOPQRSTUV",
  "type": "image",
  "filename": "photo.jpg",
  "mime_type": "image/jpeg",
  "size": 123456,
  "width": null,
  "height": null,
  "duration": null,
  "expires_at": "2026-05-16T10:30:00.000000Z"
}

Требуется разрешение conversation.view.

POST /uploads/voice

Загружает аудиозапись и транскодирует её в OGG/Opus — формат, в котором WhatsApp и Telegram отображают голосовое сообщение (voice note), а не прикреплённый файл. Это единственный корректный способ отправить голосовое через API: обычный /uploads сохраняет файл как есть (тип audio), и получателю придёт аудиофайл, а не голосовое.

POST /v1/uploads/voice
Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data

file=@voice.m4a

Принимаются audio/webm, audio/ogg, audio/mp4, audio/mpeg, audio/wav, audio/aac, audio/x-m4a (а также video/webm — контейнер браузерной записи). Сервер сам приводит запись к OGG/Opus.

{
  "media_id": "med_01HZABCDEFGHIJKLMNOPQRSTUV",
  "type": "audio",
  "filename": "voice.ogg",
  "mime_type": "audio/ogg",
  "size": 24576,
  "duration": 7,
  "expires_at": "2026-05-16T10:30:00.000000Z"
}

POST /messages/send

Отправляет исходящее сообщение от имени канала конкретному получателю. Если диалог ещё не существует — будет создан.

{
  "channel_id": 42,
  "recipient": "+79001234567",
  "message_content": "Здравствуйте! Чем могу помочь?"
}

{
  "channel_id": 42,
  "recipient": "120363398017778174@g.us",
  "message_content": "Всем привет в группе!"
}

Где взять идентификатор группы: JID <id>@g.us приходит в вебхуках входящих сообщений и доступен в GET /v1/conversations — threads[].contact_account.external_id группового треда (threads[].is_group: true). Ограничения: группы поддерживаются только на каналах WhatsApp; аккаунт канала должен состоять в группе; противоречивый запрос (recipient оканчивается на @g.us, но is_group: false) отклоняется с 422.

{ "success": true }

Поведение. Существующий диалог с получателем на этом канале переиспользуется; иначе создаётся новый (контакт-аккаунт, тред, диалог). После создания сообщения подписанные webhook-интеграции получают message.created с direction: outbound. Эндпоинт создаёт сообщение синхронно, но доставка в мессенджер выполняется асинхронно через очередь коннекторов — итоговый статус доставки приходит событием message.status.updated. Требуется разрешение conversation.create, иначе 403 Forbidden.

GET /templates

Список шаблонов сообщений компании — используйте, чтобы найти одобренные Meta шаблоны WhatsApp Business и их id для /messages/send-template.

{
  "data": {
    "items": [
      {
        "id": 42,
        "name": "order_update",
        "meta_status": "approved",
        "language": "en",
        "body": "Здравствуйте, {{name}}! Ваш заказ {{order_id}} готов.",
        "parameters": [
          { "name": "name", "type": "text", "sample_value": "Иван", "position": 1 },
          { "name": "order_id", "type": "text", "sample_value": "A-100", "position": 2 }
        ],
        "channel_type": { "id": 1, "key": "whatsapp_business", "name": "WhatsApp Business" },
        "channel": { "id": 57, "name": "WhatsApp test", "account_name": "+77084252291" }
      }
    ],
    "pagination": { "page": 1, "perPage": 15, "total": 1, "lastPage": 1 }
  }
}

meta_status — статус одобрения Meta; отправлять можно только `approved`. body содержит плейсхолдеры ({{name}} или {{1}}), по которым вы определяете, какие params нужны в /messages/send-template. Требуется разрешение template.view.

POST /messages/send-template

Отправляет одобренный шаблон WhatsApp Business конкретному получателю — для инициации диалога вне 24-часового окна и для рассылок (по одному запросу на получателя). Если диалога с получателем ещё нет — он будет создан.

Сервер сам собирает Meta-структуру components из определения шаблона. Значения params передаются одним из двух способов: именованная карта для плейсхолдеров {{name}} ({ "name": "Иван", "order_id": "A-100" }) или по позиции для числовых {{1}}, {{2}} — карта с числовыми ключами либо обычный массив (["Иван", "A-100"], значения по порядку: заголовок → тело → кнопки).

{
  "channel_id": 57,
  "recipient": "+79001234567",
  "template_id": 42,
  "params": { "name": "Иван", "order_id": "A-100" }
}

{
  "success": true,
  "message_id": 12345
}

Поведение. Отправка разрешена только для каналов whatsapp_business и шаблонов с meta_status = approved — иначе 422. Если не хватает значения для переменной — 422 с перечислением недостающих параметров. Отправленное сообщение сохраняет отрисованную структуру шаблона в message_content.display (видна в GET /messages): header, body, footer, buttons[] — каждая кнопка { "type": "quick_reply" | "url" | "phone", "label": "...", "value": "..." }. Когда контакт нажимает quick-reply кнопку, нажатие приходит обратно как входящее сообщение type: "text" с текстом кнопки и content.interactive_reply_payload. Требуется разрешение conversation.create.

Ошибки и коды ответов

Полное описание общего цикла запрос → вебхук и рассылок с медиа — в сценарии «Отправка сообщений из вашей системы».