---
title: "Create conversations in bulk"
method: POST
path: "/api/v4/messaging/conversations/bulk"
tags: ["Messaging"]
---

# Create conversations in bulk

`POST /api/v4/messaging/conversations/bulk`

## Request

- Base URL: `https://{cluster_id}.voiso.com`
- URL: `https://{cluster_id}.voiso.com/api/v4/messaging/conversations/bulk`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/voiso/apis/voiso-api/docs/api/v4/messaging/conversations/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `reference` string: Client-assigned reference for grouping related requests, such as all chunks of one campaign. Does not have to be unique.
  - `channel_profile_id` integer, required: The unique identifier of the channel profile.
  - `message` object, required: The initial message for every conversation.
    - `content_type` 'whatsapp_template', required: The message content type ("whatsapp_template" only).
    - `content_data` object, required: WhatsApp template payload.
      - `whatsapp_template_id` string, uuid, required: The unique identifier of the WhatsApp template.
      - `placeholders` object: Placeholder values for the WhatsApp template, indexed by position. Shared by all recipients.
  - `recipients` object[], required: Recipients of the bulk send.
    - `contact_channel_identifier` string, required: Channel-specific identifier of the contact (phone number for WhatsApp).
    - `placeholders` object: Placeholder values for the WhatsApp template, indexed by position. Override the shared message placeholders at matching positions.
    - `source` object: Information about the external system that provided the contact number, such as a CRM.
      - `system` string, required: The name of an external application, such as a CRM, where contact information is managed.
      - `account_id` string, required: An identifier assigned to the contact in an external application, such as a CRM.

## Response `202`

Accepted

- object
  - `job` Job: An asynchronous job created via the API.
    - `id` string, uuid: The unique identifier of the job.
    - `type` 'bulk_conversation': The job type. Defines the structure of the result.
    - `status` 'pending' | 'processing' | 'completed': The current status of the job.
    - `reference` string, nullable: The client-assigned reference from the originating request.
    - `created_at` string, date-time: Timestamp when the job was created (ISO 8601).
    - `updated_at` string, date-time: Timestamp when the job was last updated (ISO 8601).
    - `completed_at` string, date-time, nullable: Timestamp when the job was completed (ISO 8601).
    - `result` BulkConversationResult: Result of a bulk conversation creation job.
      - `cost` string: Total amount charged for the job.
      - `recipients` object: Recipients of the bulk send, grouped by outcome.
        - `sent` BulkConversationResultRecipient[]: Recipients whose message was accepted by the gateway.
          - `contact_channel_identifier` string: Channel-specific identifier of the contact (phone number for WhatsApp).
          - `conversation_id` string, uuid, nullable: The unique identifier of the conversation, when one exists for the recipient.
          - `cost` string: Amount charged for the message sent to the recipient.
          - `errors` object, nullable: A set of error messages. Validation errors are keyed by the request property; other errors use the `base` key.
        - `failed` BulkConversationResultRecipient[]: Recipients whose message could not be sent.
          - `contact_channel_identifier` string: Channel-specific identifier of the contact (phone number for WhatsApp).
          - `conversation_id` string, uuid, nullable: The unique identifier of the conversation, when one exists for the recipient.
          - `cost` string: Amount charged for the message sent to the recipient.
          - `errors` object, nullable: A set of error messages. Validation errors are keyed by the request property; other errors use the `base` key.
        - `invalid` BulkConversationResultRecipient[]: Recipients that were rejected by validation. No message was sent.
          - `contact_channel_identifier` string: Channel-specific identifier of the contact (phone number for WhatsApp).
          - `conversation_id` string, uuid, nullable: The unique identifier of the conversation, when one exists for the recipient.
          - `cost` string: Amount charged for the message sent to the recipient.
          - `errors` object, nullable: A set of error messages. Validation errors are keyed by the request property; other errors use the `base` key.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `429`: Too many requests

## Changes

- **2026-11-03** `5a6ea146bd21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voiso/apis/voiso-api/changes/api/v4/messaging/conversations/bulk/post.md)

---

[API](https://skmtc.dev/voiso/apis/voiso-api.md) - [All operations](https://skmtc.dev/voiso/apis/voiso-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voiso/apis/voiso-api/revisions/5a6ea146bd21?raw)