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

​

Что это такое

​

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

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

​

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

​

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

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "welcome-10001",
    "template": {
      "name": "welcome_message",
      "language": { "code": "en_US" }
    }
  }'

​

Выбор шаблона или сессионного сообщения

​

Прямая отправка (Direct Send) для сервисного контента

​

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

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

​

Запрос

​

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

​

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

{
  "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": "👍"
  }
}

​

Добавление переменных шаблона

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Alex" },
          { "type": "text", "text": "ORDER-10001" }
        ]
      }
    ]
  }
}

​

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

{
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "text",
  "text": { "body": "Your order is ready for collection." },
  "context": { "message_id": "wamid.EXAMPLE" }
}

​

Применение фильтров отписки и блокировки

​

Ответ

​

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

{
  "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"
}

​

Поля ответа

​

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

​

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

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

​

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