Отправка сообщения WhatsApp

Что это такое

WhatsApp Messages API отправляет шаблонные, текстовые, графические, видео-, аудиосообщения, документы, стикеры, геолокации, интерактивные сообщения, контакты и реакции с подключенного бизнес-номера WhatsApp.

Перед началом работы

Сохраните свой API-ключ YCloud в YCLOUD_API_KEY.
Подключите WhatsApp Business Account и номер телефона к YCloud.
Получите номер телефона отправителя в формате E.164, а также номер телефона получателя, BSUID или родительский BSUID.
Используйте шаблон APPROVED для стандартных шаблонных отправок.
Сначала загрузите медиафайл, если сообщение ссылается на медиа-ID YCloud.

Как это работает

Выберите эндпоинт в зависимости от того, когда YCloud должен передать сообщение в WhatsApp Business API.

Эндпоинт	Поведение	Для чего используется
`POST /whatsapp/messages`	Ставит сообщение в очередь и отправляет его асинхронно.	Большинство исходящих сценариев обмена сообщениями.
`POST /whatsapp/messages/sendDirectly`	Синхронно передает сообщение в WhatsApp Business API.	OTP и другие срочные сообщения.

Оба эндпоинта возвращают объект сообщения YCloud. Первоначальный ответ не подтверждает окончательную доставку. Последующие изменения статуса поступают через whatsapp.message.updated Webhooks.

Direct Send для сервисного контента

Direct Send позволяет отправлять подходящий сервисный контент или конвертировать существующий сервисный шаблон. Он работает с любым из эндпоинтов отправки. Эндпоинт sendDirectly управляет синхронной отправкой; сам по себе он не включает Direct Send. Ознакомьтесь с рекомендациями по Direct Send относительно критериев соответствия, запросов, конвертации шаблонов, лимитов и событий аккаунта.

Выбор оптимального времени отправки

Сопоставляйте время отправки с целью сообщения и местным временем получателя.

Отправляйте OTP и другие срочные сообщения немедленно. Используйте POST /whatsapp/messages/sendDirectly, если вашему рабочему процессу требуется результат отправки перед продолжением.
Отправляйте транзакционные уведомления сразу при наступлении соответствующего события, например оплаты, доставки или переноса встречи.
Планируйте маркетинговые сообщения на разумные часы в часовом поясе получателя. Используйте собственные данные о доставке, прочтении и конверсиях для тестирования различных временных интервалов для каждой аудитории вместо предположения об одном универсальном времени.
Запускайте запланированную кампанию с небольшой группы получателей. Проверьте показатели доставки, откликов и отписок перед отправкой остальной части аудитории.
Избегайте повторных отправок при задержке сообщения. Сохраняйте externalId и обрабатывайте whatsapp.message.updated Webhooks перед принятием решения о повторной попытке.

Запрос

Выберите один из приведенных выше эндпоинтов, затем используйте тело запроса, соответствующее типу сообщения. Значение from — это ваш подключенный бизнес-номер WhatsApp. Укажите получателя с помощью to в формате E.164 или с помощью recipient, задав BSUID или родительский BSUID.

Общие поля запроса

Поле	Обязательно	Описание
`from`	Да	Подключенный бизнес-номер WhatsApp в формате E.164.
`to`	При условии	Номер телефона получателя в формате E.164. Обязательно, если отсутствует `recipient`.
`recipient`	При условии	BSUID или родительский BSUID получателя. Обязательно, если отсутствует `to`.
`type`	Да	Тип сообщения. Включите поле контента, соответствующее этому значению.
`template`, `text`, `image` и другие поля типов	При условии	Объект контента, требуемый выбранным `type`.
`context`	Нет	Контекст сообщения, используемый при ответе на более раннее сообщение.
`externalId`	Нет	Ваш уникальный идентификатор для сопоставления сообщения с внутренней записью.
`filterUnsubscribed`	Нет	Только для постановки в очередь. По умолчанию `false`; при значении `true` отфильтровывает получателей из списка отписавшихся.
`filterBlocked`	Нет	Только для постановки в очередь. По умолчанию `false`; при значении `true` отфильтровывает заблокированных получателей.

filterUnsubscribed и filterBlocked применяются только к POST /whatsapp/messages; они не применяются к sendDirectly. Отфильтрованное сообщение из очереди завершается ошибкой с RECIPIENT_UNSUBSCRIBED или RECIPIENT_IN_BLOCK_LIST в вебхуке статуса. Для синхронных отправок проверяйте согласие, отписку и блокировку на стороне вашего приложения.

Укажите как минимум одно из полей: to или recipient. Если указаны оба, YCloud использует to и игнорирует recipient.

Шаблоны аутентификации one-tap, zero-tap и copy-code требуют наличия номера телефона. Используйте to для таких типов шаблонов.

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

Шаблонное сообщение

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "template",
  "template": {
    "name": "sample_whatsapp_template",
    "language": {
      "code": "en",
      "policy": "deterministic"
    }
  }
}

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

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "text",
  "text": {
    "body": "Hello from YCloud!"
  }
}

Графическое сообщение

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "image",
  "image": {
    "id": "MEDIA_ID",
    "caption": "Product image"
  }
}

Видеосообщение

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "video",
  "video": {
    "id": "MEDIA_ID",
    "caption": "Product video"
  }
}

Аудиосообщение

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID"
  }
}

Документ

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}

Стикер

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID"
  }
}

Сообщение с местоположением

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "location",
  "location": {
    "latitude": 37.422,
    "longitude": -122.084,
    "name": "Googleplex",
    "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
  }
}

Интерактивное сообщение

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Do you want to continue?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "yes",
            "title": "Yes"
          }
        }
      ]
    }
  }
}

Сообщение с контактами

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Smith"
      },
      "phones": [
        {
          "phone": "+16315551111",
          "type": "CELL"
        }
      ]
    }
  ]
}

Сообщение-реакция

{
  "from": "+16315551111",
  "to": "+16315551111",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.BgNODYxN...",
    "emoji": "👍"
  }
}

Ответ

В случае успешного выполнения возвращается объект сообщения YCloud. Первоначальный статус status: accepted означает, что YCloud принял запрос на отправку. Это не означает, что сообщение уже отправлено компанией Meta или доставлено пользователю WhatsApp.

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

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "status": "accepted",
  "externalId": "order-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}

Поля ответа

Поле	Описание
`id`	Идентификатор сообщения YCloud. Сохраните его для получения информации и сопоставления с Webhook.
`wamid`	Исходный идентификатор сообщения WhatsApp. Доступен после передачи в WhatsApp.
`wabaId`	Идентификатор WhatsApp Business Account.
`from`, `to`	Номера телефонов отправителя и получателя.
`type`	Тип содержимого сообщения.
`status`	Текущее состояние, такое как `accepted`, `sent`, `failed`, `delivered` или `read`.
`errorCode`, `errorMessage`	Сведения об ошибке YCloud, если `status` имеет значение `failed`.
`whatsappApiError`	Ошибка, возвращенная WhatsApp Business API (при наличии).
`externalId`	Идентификатор reference, указанный в запросе.
`category`	Категория Direct Send, например `utility` для приведенных выше примеров сервисных сообщений.
`ttlSeconds`	Срок жизни сообщения Direct Send, если он был задан для сообщения.
`totalPrice`, `currency`	Расчетная или окончательная стоимость сообщения и валюта.
`createTime`, `sendTime`, `deliverTime`, `readTime`	Временные метки жизненного цикла в формате RFC 3339.

Статус доставки

Подпишитесь на Webhook-уведомления whatsapp.message.updated, чтобы получать последующие изменения статуса, такие как sent, failed, delivered или read. Используйте GET /whatsapp/messages/{id}, если вам требуется запросить данные о сообщении напрямую.

Для медиасообщений сначала загрузите файл с помощью POST /whatsapp/media/{phoneNumber}/upload, затем используйте полученный медиа-ID в теле сообщения.

Ограничения и устранение неполадок

Для обычной отправки шаблонов требуется шаблон со статусом APPROVED; шаблоны со статусом ARCHIVED не могут быть отправлены как обычные шаблонные сообщения.
Не повторяйте принятый запрос без стратегии идемпотентности. Повторный запрос может привести к отправке дубликата сообщения.
Используйте поля YCloud id, wamid, externalId и статус Webhook при диагностике доставки.
Проверьте whatsappApiError, если прямой запрос дошел до Meta, но был отклонен ею.

Сведения об ограничениях пропускной способности см. в разделе Ограничения частоты запросов.

Использование business-scoped user ID (BSUID)

Отправляйте сообщения и совершайте звонки по BSUID, запрашивайте номера телефонов, управляйте записями контактов Meta и обрабатывайте поля BSUID в webhook-событиях.

Полные примеры интеграции

Полный процесс создания шаблонов и привязки переменных описан в разделах Примеры создания шаблонов и Примеры отправки сообщений. Используйте руководство Обработка ошибок WhatsApp, чтобы отличать отклонение запроса от последующих сбоев доставки, и раздел Реализация обработчика Webhook для проверки подписей и надежного приема обновлений статуса.

Начало работы

Руководства

Конечные точки

Webhooks

Отправка сообщения WhatsApp

Что это такое

Перед началом работы

Как это работает

Direct Send для сервисного контента

Выбор оптимального времени отправки

Запрос

Общие поля запроса

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

Ответ

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

Поля ответа

Статус доставки

Ограничения и устранение неполадок

Рекомендации по Direct Send

Рекомендации для рабочей среды

Использование business-scoped user ID (BSUID)

Полные примеры интеграции

​Что это такое

​Перед началом работы

​Как это работает

​Direct Send для сервисного контента

​Выбор оптимального времени отправки

​Запрос

​Общие поля запроса

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

​Ответ

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

​Поля ответа

​Статус доставки

​Ограничения и устранение неполадок

Рекомендации по Direct Send

Рекомендации для рабочей среды

Использование business-scoped user ID (BSUID)

​Полные примеры интеграции

Что это такое

Перед началом работы

Как это работает

Direct Send для сервисного контента

Выбор оптимального времени отправки

Запрос

Общие поля запроса

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

Ответ

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

Поля ответа

Статус доставки

Ограничения и устранение неполадок

Полные примеры интеграции