POST /v1/messages/send

Отправка текстового или медиа-сообщения через подключённый канал (линию связи).

ℹ️ Асинхронная отправка: Сообщения ставятся в очередь и отправляются в течение нескольких секунд. Успешный ответ (202) означает, что сообщение принято в обработку, а не что оно уже доставлено.

URL

POST https://api.wazzabee.com/api-gateway/v1/messages/send

Заголовки

Authorization: Bearer ВАШ_API_КЛЮЧ
Content-Type: application/json

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

Параметр	Тип	Обязательный	Описание
`channelId`	string (UUID)	✅ Да	ID канала (линии связи). Получить через GET /v1/channels
`chatId`	string	✅ Да	Идентификатор получателя: номер телефона (для WhatsApp) или chat_id (для Telegram)
`text`	string	✅*	Текст сообщения. Обязателен, если не указан `mediaUrl`
`mediaUrl`	string (URL)	✅*	Прямая ссылка на медиафайл (изображение, видео, документ). Обязателен, если не указан `text`
`mediaType`	string	Условно	Тип медиа: `photo`, `video`, `document`, `audio`. Обязателен при указании `mediaUrl`
`caption`	string	Нет	Подпись к медиафайлу. Работает только вместе с `mediaUrl`
`senderName`	string	Нет	Имя автора — кто отправил сообщение. Видно вашим операторам в чате WazzaBee и приходит в вебхуке. Клиенту в мессенджер не передаётся
`userId`	string	Нет	Идентификатор сотрудника в вашей CRM. Возвращаем его как есть — заводить этого сотрудника в WazzaBee не нужно
`automated`	boolean	Нет	`true` — сообщение отправил робот, автоответ или напоминание. В чате такое сообщение помечается как автоматическое

* Нужно указать либо text, либо mediaUrl — хотя бы один из двух.

Кто отправил сообщение

По умолчанию сообщение, отправленное через API, подписывается в чате коротко — «по API», без имени. Если ваша CRM знает автора, передайте его: под сообщением будет видно «по API · Назерке А.», а имя вернётся вам в вебхуке messages_outgoing. Так по ленте чата понятно, кто из менеджеров ответил клиенту.

curl -X POST "https://api.wazzabee.com/api-gateway/v1/messages/send" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "chatId": "77001234567",
    "text": "Здравствуйте! Ваши документы готовы.",
    "senderName": "Назерке Ахметова",
    "userId": "manager-42"
  }'

Вместо senderName и userId можно передать объект author — результат тот же:

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "chatId": "77001234567",
  "text": "Здравствуйте!",
  "author": { "id": "manager-42", "name": "Назерке Ахметова" }
}

Сообщения, которые отправляет не человек (роботы, автоответы, напоминания), помечайте "automated": true — в чате они будут видны отдельно от ответов менеджеров.

ℹ️ Подпись видна только вам. Имя автора показывается вашим операторам в чате WazzaBee и приходит в вебхуках. Клиенту в WhatsApp или Telegram оно не передаётся — он видит только текст сообщения.

Формат chatId

Тип канала	Формат chatId	Пример
WhatsApp (QR)	Номер телефона с кодом страны, без `+`	`77001234567`
WhatsApp (WABA)	Номер телефона с кодом страны, без `+`	`77001234567`
Telegram Bot	Числовой chat_id пользователя	`123456789`
Telegram Personal	Числовой chat_id или username	`123456789`

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

Текстовое сообщение

curl -X POST "https://api.wazzabee.com/api-gateway/v1/messages/send" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "chatId": "77001234567",
    "text": "Здравствуйте! Ваш заказ #1234 готов к выдаче."
  }'

Изображение с подписью

curl -X POST "https://api.wazzabee.com/api-gateway/v1/messages/send" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "chatId": "77001234567",
    "mediaUrl": "https://example.com/photo.jpg",
    "mediaType": "photo",
    "caption": "Фото вашего заказа"
  }'

Документ

curl -X POST "https://api.wazzabee.com/api-gateway/v1/messages/send" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "chatId": "77001234567",
    "mediaUrl": "https://example.com/invoice.pdf",
    "mediaType": "document"
  }'

Успешный ответ (202 Accepted)

{
  "success": true,
  "queued": true,
  "queueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Сообщение поставлено в очередь на отправку"
}

Поле	Тип	Описание
`success`	boolean	Всегда `true` при успехе
`queued`	boolean	Сообщение принято в очередь
`queueId`	string (UUID)	Уникальный ID в очереди отправки
`message`	string	Текстовое описание результата

Возможные ошибки

Код	Ошибка	Причина
`400`	Невалидный JSON в теле запроса	Тело запроса не является корректным JSON
`400`	Поле channelId обязательно	Не передан параметр `channelId`
`400`	Поле chatId обязательно	Не передан параметр `chatId`
`400`	Нужно указать text или mediaUrl	Не передан ни текст, ни медиафайл
`400`	Канал неактивен	Канал отключён или не настроен
`400`	Неподдерживаемый тип канала	Тип канала не поддерживается API
`403`	Канал не привязан к данной интеграции	Канал не входит в разрешённые для этого API-ключа
`404`	Канал не найден или нет доступа	Канал не существует или принадлежит другому пользователю

Как это работает внутри

API проверяет авторизацию и доступ к каналу
Ищет контакт по chatId (телефон или external_id). Если не найден — создаёт нового
Ищет существующий диалог (conversation). Если не найден — создаёт новый
Определяет способ доставки по типу канала
Ставит сообщение в очередь message_queue
Фоновый процесс забирает сообщение из очереди и отправляет через провайдер