VOvoiso
Messaging

Create conversations in bulk

Changed on

Initiate conversations with a WhatsApp template message for up to 500 recipients.

Processing is asynchronous: the endpoint returns a job that can be polled for per-recipient results. Request-level errors, such as an unknown template or a duplicate recipient, reject the whole request. Per-recipient failures, such as an invalid phone number, do not block other recipients and are reported in the job result.

post/api/v4/messaging/conversations/bulk

Request

Headers

Idempotency-Keystring
Example:spring-promo-2026-chunk-07

A unique client-generated key that makes the request safe to retry. Repeating a request with the same key returns the previously created job instead of creating a new one. Reusing the key with a different request body is rejected.

Request body

referencestring

Client-assigned reference for grouping related requests, such as all chunks of one campaign. Does not have to be unique.

channel_profile_idinteger required

The unique identifier of the channel profile.

Example request

{
  "reference": "spring-promo-2026",
  "channel_profile_id": 1,
  "message": {
    "content_type": "whatsapp_template",
    "content_data": {
      "whatsapp_template_id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
      "placeholders": {
        "1": "Acme"
      }
    }
  },
  "recipients": [
    {
      "contact_channel_identifier": "15551234567",
      "placeholders": {
        "2": "John"
      },
      "source": {
        "system": "salesforce",
        "account_id": "0031t00000AbCdEf"
      }
    }
  ]
}

Response

Accepted

Example response

{
  "job": {
    "id": "7d8f1c2e-3b4a-4f5d-9e6c-1a2b3c4d5e6f",
    "type": "bulk_conversation",
    "status": "completed",
    "reference": "spring-promo-2026",
    "created_at": "2026-01-15T10:30:00.123000Z",
    "updated_at": "2026-01-15T10:31:00.123000Z",
    "completed_at": "2026-01-15T10:31:00.123000Z",
    "result": {
      "cost": "14.40",
      "recipients": {
        "sent": [
          {
            "contact_channel_identifier": "15551234567",
            "conversation_id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
            "cost": "0.03",
            "errors": {
              "contact_channel_identifier": [
                "must be a valid phone number"
              ]
            }
          }
        ],
        "failed": [
          {
            "contact_channel_identifier": "15551234567",
            "conversation_id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
            "cost": "0.03",
            "errors": {
              "contact_channel_identifier": [
                "must be a valid phone number"
              ]
            }
          }
        ],
        "invalid": [
          {
            "contact_channel_identifier": "15551234567",
            "conversation_id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
            "cost": "0.03",
            "errors": {
              "contact_channel_identifier": [
                "must be a valid phone number"
              ]
            }
          }
        ]
      }
    }
  }
}

Changes