Bulk sending with the WhatsApp API (bulk_messages)

Last updated: 11 October 2026 · 7 min read

Steps

1. 1

   Who can send

   Administrators only. A bulk send goes out from the account's number to thousands of customers and affects your Meta account's quality rating, so it is not an agent-level decision.

2. 2

   Build the request

   POST /v1/accounts/{account_id}/whatsapp/bulk_messages. Fields:

   • channel_id (required)
   • template.name and template.language (required, shared by all recipients)
   • template.parameters: shared parameters
   • conversation_status: resolved, open, pending
   • status_callback: each number's status arrives at your URL separately, and the delay counts from that number's send. The fields are the same as for a single send
   • recipients (required, at most 1000). Each recipient has phone_number (required), parameters (specific to this recipient, replacing the shared parameters) and contact (name, email, identifier)

   To address everyone by their own name, put the name in the recipient's parameters field:

   {
     "channel_id": 159,
     "template": { "name": "kampaniya_avqust", "language": "az" },
     "recipients": [
       {
         "phone_number": "+994 50 123 45 67",
         "parameters": { "body": { "1": "Kenan" } },
         "contact": { "name": "Kenan Rzayev" }
       },
       {
         "phone_number": "+994 55 111 22 33",
         "parameters": { "body": { "1": "Aygun" } }
       }
     ]
   }

3. 3

   Response: batch_id

   The response comes back as 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

   Read the result

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

   status is processing until every recipient has been handled, then it becomes completed. Each recipient has its own result: message_id and conversation_id when it is sent, and error when it is failed (for example "Invalid phone number: ...").

   The result is kept for 7 days, after which 404 comes back. The messages themselves and the conversations stay in Clomni permanently.

5. 5

   More than 1000 recipients

   Split the list into parts of 1000 and send the requests one after another. Each part gets its own batch_id.

   • a request with more than 1000 recipients returns 422: A batch can hold at most 1000 recipients
   • an empty list is also 422: recipients must be a non-empty array
6. 6

   Before you send

   • Test a new template on 5-10 numbers first, read the result, then move to the full list: a thousand messages with a wrong parameter cost both money and rating.
   • Get the customer's consent to receive messages (opt-in) and keep a record of it: a bulk send without consent can end with the number being blocked.
   • When customers choose “Report” or “Block”, the quality rating drops, and that lowers the daily limit.
   • Put a quick reply button in the campaign template: the next 24 hours with a customer who replies are free.
7. 7

   Speed

   Messages go through a background queue. The real speed is set by the limit Meta gives your account; usually hundreds of messages go out per minute.