Массовая отправка через WhatsApp API (bulk_messages)

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

Шаги

1. 1

   Кто может отправлять

   Только администратор. Массовая отправка уходит с номера аккаунта тысячам клиентов и влияет на рейтинг качества Вашего аккаунта в Meta, поэтому такое решение не принимается на уровне агента.

2. 2

   Соберите запрос

   POST /v1/accounts/{account_id}/whatsapp/bulk_messages. Поля:

   • channel_id (обязательно)
   • template.name и template.language (обязательно, общие для всех получателей)
   • template.parameters: общие параметры
   • conversation_status: resolved, open, pending
   • status_callback: статус каждого номера приходит на Ваш адрес отдельно, задержка считается от отправки на этот номер. Поля те же, что и в одиночной отправке
   • recipients (обязательно, не больше 1000). У каждого получателя phone_number (обязательно), parameters (свои для этого получателя, заменяют общие параметры) и contact (name, email, identifier)

   Чтобы обратиться к каждому по имени, передайте имя в поле parameters получателя:

   {
     "channel_id": 159,
     "template": { "name": "kampaniya_avqust", "language": "az" },
     "recipients": [
       {
         "phone_number": "+994 50 123 45 67",
         "parameters": { "body": { "1": "Кенан" } },
         "contact": { "name": "Кенан Рзаев" }
       },
       {
         "phone_number": "+994 55 111 22 33",
         "parameters": { "body": { "1": "Айгюн" } }
       }
     ]
   }

3. 3

   Ответ: batch_id

   Ответ приходит с кодом 202 Accepted:

   {
     "batch": {
       "batch_id": "7c1f2a3e-9b44-4c2e-8a11-5f0d9b6e2a77",
       "channel_id": 159,
       "template_name": "kampaniya_avqust",
       "total": 2,
       "status": "processing",
       "sent_count": 0,
       "failed_count": 0,
       "pending_count": 2,
       "recipients": [
         { "index": 0, "status": "pending" },
         { "index": 1, "status": "pending" }
       ]
     }
   }

4. 4

   Прочитайте результат

   GET /v1/accounts/{account_id}/whatsapp/bulk_messages/{batch_id}

   status равен processing, пока не обработаны все получатели, затем становится completed. Результат по каждому получателю отдельный: при sent есть message_id и conversation_id, при failed есть error (например, "Invalid phone number: ...").

   Результат хранится 7 дней, потом возвращается 404. Сами сообщения и диалоги остаются в Clomni навсегда.

5. 5

   Больше 1000 получателей

   Разбейте список на части по 1000 и отправляйте запросы по очереди. Каждая часть получает свой batch_id.

   • запрос с получателями больше 1000 возвращает 422: A batch can hold at most 1000 recipients
   • пустой список тоже даёт 422: recipients must be a non-empty array
6. 6

   Перед отправкой

   • Сначала проверьте новый шаблон на 5-10 номерах, прочитайте результат и только потом отправляйте на весь список: тысяча сообщений с ошибкой в параметрах это потеря и денег, и рейтинга.
   • Получите и задокументируйте согласие клиента на получение сообщений (opt-in): массовая отправка без согласия может закончиться блокировкой номера.
   • Когда клиенты выбирают «Пожаловаться» или «Заблокировать», рейтинг качества падает, а вместе с ним снижается дневной лимит.
   • Добавьте в шаблон кампании кнопку быстрого ответа: следующие 24 часа переписки с ответившим клиентом бесплатны.
7. 7

   Скорость

   Сообщения проходят через фоновую очередь. Реальную скорость определяет лимит, который Meta даёт Вашему аккаунту; обычно уходят сотни сообщений в минуту.