Send Message

The response object confirms that your message request has been accepted and added to the processing queue for asynchronous delivery.

What you receive:

• queue_id — A unique identifier for your enqueued message task. Save this value to track your message's progress, correlate it with webhook events, or reference it in support requests.
• queue_position — Your message's position in the processing queue at the moment it was enqueued. This is zero-based (0 = first in queue, 1 = second, etc.). Note that this position reflects the queue state at enqueue time and may change as other messages are processed.
• status — The initial status of the message, always queued at this point.
• unique_id — A provisional identifier (when available) that helps correlate the queued request with downstream message objects or WhatsApp provider references.
• track_by — A convenience object with ready-to-use tracking URLs. Use track_by.unique_id to poll delivery status via GET /message/{unique_id}/status, or track_by.queue_id to look up the job via the queue API.

Understanding the queue system:

• Messages are NOT sent immediately upon receiving this response. Instead, they are queued and processed asynchronously in the background.
• Processing typically begins within seconds, but actual timing depends on:
  • Current queue depth and system throughput
  • Message type and size (text messages are faster than media)
  • Media file size and processing requirements
  • Rate limits applied to your phone number or organization
  • WhatsApp provider connectivity and response times
• The system automatically retries failed messages for transient errors (network issues, temporary provider unavailability, etc.). Messages will be retried up to 3 times with exponential backoff delays between attempts. After 3 failed attempts, the message will be marked as failed and no further retries will occur.

How the queue_id maps to your message:

• When you receive the queue_id, your message is in a "queued" state
• Once processing begins, the queue_id becomes associated with a provisional sent_message_id in the message object
• After successful delivery to WhatsApp, the queue_id maps to the final provider message ID
• You can use the queue_id to track the message through its entire lifecycle: queued → processing → sent → delivered → read (or failed)

Tracking your message status: You have two primary methods to monitor your message:

1. Message Status API — Use GET /message/{unique_id}/status to check the delivery status of your message. The unique_id is returned in this response. The status field can be one of:

   • queued — Waiting to be processed
   • sending — Currently being sent to WhatsApp
   • sent — Successfully sent to WhatsApp servers
   • delivered — Delivered to the recipient's device
   • read — Read by the recipient
   • failed — Delivery failed after all retry attempts (check status_description for reason)

2. Webhook notifications — If you have webhooks configured, you'll automatically receive real-time events as your message progresses:

   • message.sent — Fired when the message is successfully sent to WhatsApp
   • message.delivered — Fired when the message is delivered to the recipient
   • message.read — Fired when the message is read (requires read receipts to be enabled)
   • message.failed — Fired if the message fails to send or deliver after all retry attempts
   • Each webhook event includes the queue_id so you can correlate it with your original request

Error handling and retries:

• If a message fails due to transient errors (network issues, temporary provider unavailability, timeouts), the system will automatically retry the message
• Messages are retried up to 3 times with exponential backoff delays (the delay increases with each retry attempt)
• Permanent failures (invalid chat_id, blocked numbers, etc.) will not be retried
• After 3 failed retry attempts, the message status will be set to failed and you'll receive a message.failed webhook event if configured

Best practices:

• Always save the queue_id immediately after receiving the response
• Don't poll the queue status too frequently (recommended: every 1-2 seconds for active monitoring, or use webhooks for real-time updates)
• Implement proper error handling for failed messages
• Use webhooks when possible for more efficient, event-driven tracking
• Monitor your message status and handle failed messages appropriately in your application

Related documentation:

• Message Status API — Track delivery status by unique_id
• List Queue Jobs API — Query job status by queue_id or broadcast_id
• Queue Health API — Check the overall status of the message queue
• Webhooks Documentation — Guide to setting up and handling webhook events