> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Отправка сообщения WhatsApp > Отправляйте шаблонные, сессионные и медиасообщения WhatsApp с помощью асинхронного или синхронного API. ## Что это такое 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](/ru/api-reference/guides/whatsapp-platform/best-practices/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` для таких типов шаблонов. ### Примеры запросов ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "template", "template": { "name": "sample_whatsapp_template", "language": { "code": "en", "policy": "deterministic" } } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "text", "text": { "body": "Hello from YCloud!" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "image", "image": { "id": "MEDIA_ID", "caption": "Product image" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "video", "video": { "id": "MEDIA_ID", "caption": "Product video" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "audio", "audio": { "id": "MEDIA_ID" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "document", "document": { "id": "MEDIA_ID", "filename": "invoice.pdf" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "sticker", "sticker": { "id": "MEDIA_ID" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "location", "location": { "latitude": 37.422, "longitude": -122.084, "name": "Googleplex", "address": "1600 Amphitheatre Pkwy, Mountain View, CA" } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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" } } ] } } } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "contacts", "contacts": [ { "name": { "formatted_name": "John Smith" }, "phones": [ { "phone": "+16315551111", "type": "CELL" } ] } ] } ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "+16315551111", "to": "+16315551111", "type": "reaction", "reaction": { "message_id": "wamid.BgNODYxN...", "emoji": "👍" } } ``` ## Ответ В случае успешного выполнения возвращается объект сообщения YCloud. Первоначальный статус `status: accepted` означает, что YCloud принял запрос на отправку. Это не означает, что сообщение уже отправлено компанией Meta или доставлено пользователю WhatsApp. ### Пример ответа ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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, но был отклонен ею. Сведения об ограничениях пропускной способности см. в разделе [Ограничения частоты запросов](/ru/api-reference/guides/api-fundamentals/rate-limits). Отправляйте сервисный контент, конвертируйте шаблоны и отслеживайте события категорий и ограничений. Спроектируйте синхронизацию статусов, ограниченные повторные попытки, проверку согласий, повторное использование медиа и контроль пропускной способности для интеграции в рабочей среде. Отправляйте сообщения и совершайте звонки по BSUID, запрашивайте номера телефонов, управляйте записями контактов Meta и обрабатывайте поля BSUID в webhook-событиях. ## Полные примеры интеграции Полный процесс создания шаблонов и привязки переменных описан в разделах [Примеры создания шаблонов](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples) и [Примеры отправки сообщений](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples). Используйте руководство [Обработка ошибок WhatsApp](/ru/api-reference/guides/whatsapp-platform/handle-whatsapp-errors), чтобы отличать отклонение запроса от последующих сбоев доставки, и раздел [Реализация обработчика Webhook](/ru/api-reference/guides/api-fundamentals/implement-a-webhook-receiver) для проверки подписей и надежного приема обновлений статуса. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.