Отправка сообщений через WhatsApp API: код OTP, шаблон и текст

Обновлено: 11 октября 2026 · 9 мин чтения

Шаги

1. 1

   Найдите шаблон

   GET /v1/accounts/{account_id}/whatsapp/templates возвращает только шаблоны APPROVED. channel_id обязателен, name необязателен.

   У каждого шаблона есть name, language, category, parameter_format, components и example_parameters. example_parameters это готовый каркас параметров, которые ждёт шаблон: скопируйте его и замените значения своими данными. Если передать не все переменные, Meta отклонит сообщение.

   synced_at показывает, когда шаблоны последний раз загружались из Meta. Чтобы API увидел новый шаблон, нажмите в панели «Sync Templates».

2. 2

   Поля запроса

   • channel_id (обязательно): id канала WhatsApp Cloud API
   • phone_number (обязательно): номер получателя в международном формате
   • text: свободный текст, уходит только при открытом окне
   • template: отправка шаблоном, обязательно, если нет text. Обязательны template.name (точное название шаблона) и template.language (az, en, tr, ru, en_US и т. д.), template.parameters это переменные шаблона
   • fallback_template: вместе с text, используется, когда окно закрыто
   • conversation_status: resolved (по умолчанию), open или pending
   • contact.name, contact.email, contact.identifier (id клиента в Вашей системе): необязательно
   • source_reference: ключ идемпотентности
   • status_callback: чтобы получать статус сообщения на свой адрес (url, after_seconds, on_change, secret), необязательно. Подробно в статье об отслеживании статуса доставки
3. 3

   Отправьте код подтверждения (OTP)

   Отправляйте шаблоном категории AUTHENTICATION. Тело запроса:

   {
     "channel_id": 159,
     "phone_number": "+994 50 123 45 67",
     "template": {
       "name": "verification_code",
       "language": "az",
       "parameters": { "body": { "1": "483920" } }
     },
     "contact": { "name": "Кенан Рзаев", "identifier": "crm-10422" },
     "source_reference": "otp-10422-1754582400"
   }

   Делайте срок действия кода коротким, рекомендуется 5 минут. Одно сообщение OTP стоит 0.036 AZN.

4. 4

   Отправьте уведомление

   Отправляйте текст вместе с fallback_template:

   {
     "channel_id": 159,
     "phone_number": "+994 50 123 45 67",
     "text": "Ваша посылка AZ-10422 передана курьеру.",
     "fallback_template": {
       "name": "kargo_status",
       "language": "az",
       "parameters": { "body": { "1": "AZ-10422", "2": "у курьера" } }
     }
   }

   Если окно открыто, текст уходит бесплатно (sent_as: "session"), если закрыто, уходит шаблон (sent_as: "template").

5. 5

   Параметры шаблона

   Параметры группируются по частям шаблона: header, body, footer, buttons.

   Если parameter_format равен POSITIONAL, ключи body это числа по порядку {{1}}, {{2}}, если NAMED, это имена, которые Вы задали в Meta:

   "body": { "1": "Кенан", "2": "AZ-10422" }
   "body": { "customer_name": "Кенан", "order_id": "AZ-10422" }

   Если есть только body, принимается и короткая форма: "parameters": { "1": "483920" }.

   • Если заголовок это картинка, видео или документ, передайте media_url (открытый адрес https) и media_type: image (JPG, PNG), video (MP4), document (PDF и др., для имени файла media_name).
   • Кнопки: url (parameter добавляется в конец ссылки) и copy_code (копирование кода, не больше 15 символов). Кнопки со статической ссылкой и кнопки быстрого ответа параметров не требуют.
   • Для суммы тип currency (code, amount_1000, fallback_value), для даты date_time (fallback_value). amount_1000 это сумма, умноженная на 1000, целым числом: для 149.00 AZN это 149000.
6. 6

   Правильно укажите номер

   Указывайте номер с кодом страны. Все эти варианты дают одинаковый результат, пробелы, дефисы, скобки и «+» убираются сами:

   994501234567
   +994 50 123 45 67
   (+994) 50-123-45-67

   0501234567 неверно: нет кода страны, сообщение уйдёт не на тот номер. В номере должно быть от 8 до 15 цифр (E.164), иначе вернётся 422.

7. 7

   Прочитайте ответ

   Ответ приходит с кодом 201 Created: id (id сообщения), sent_as, status, external_error, whatsapp_message_id, conversation_id, conversation_status, contact_id, channel_id, content, template_name, source_reference, created_at, delivered_at, read_at, status_callback.

   status: "sent" не значит «доставлено», это значит, что Meta приняла сообщение. delivered и read приходят через несколько секунд, поэтому не пишите клиенту «доставлено» сразу после отправки.

8. 8

   Защититесь от повторной отправки

   При обрыве сети или двойном запуске очереди один и тот же запрос может повториться. Если передать source_reference, повторный запрос с тем же ключом в течение 24 часов не создаёт новое сообщение, а возвращает первое: клиент не получит второй код, и Meta не возьмёт оплату дважды. Выбирайте ключ уникальным в своей системе, например otp-{пользователь}-{время}.

9. 9

   Примеры кода

   В разделе 12 документа есть четыре примера:

   • Node.js: уведомление о доставке, переход на шаблон, когда окно закрыто
   • PHP: код подтверждения
   • Python: проверить окно и отправить
   • C# (.NET): код подтверждения

   Во всех примерах ключ хранится не в коде, а в переменной окружения (CLOMNI_TOKEN).