The Create conversation endpoint initiates a new conversation for WhatsApp channels.

Requirements: Base URL, Authentication, Error codes

Scope: messaging.conversations.manage

What this does

When you send a Create conversation request, Voiso creates a new conversation and sends an initial WhatsApp template message.

Endpoint


POST /api/v4/messaging/conversations

Request body

Required fields:

channel_profile_id
The unique identifier of the channel profile.
contact_channel_identifier
Channel specific identifier of the contact (phone number for WhatsApp).
message
The initial message for the conversation.

Optional fields:

user_id
The unique identifier of the user assigned to the conversation (UUID).

message object

content_type
Must be whatsapp_template.
content_data.whatsapp_template_id
The unique identifier of the WhatsApp template (UUID).
content_data.placeholders
Placeholder values for the WhatsApp template, indexed by position.

Related endpoints

Get a WhatsApp template ID: Get list of WhatsApp templates
Get a user ID: Get list of users
Get a channel profile ID: Get list of channel profiles

Example request

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/conversations" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_profile_id": 12,
    "contact_channel_identifier": "15551234567",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content_type": "whatsapp_template",
      "content_data": {
        "whatsapp_template_id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
        "placeholders": {
          "1": "John",
          "2": "01 Jan 2026"
        }
      }
    }
  }'

Response

If successful, the API returns a conversation object.

{
  "conversation": {
    "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
    "channel_profile": {
      "id": 12,
      "channel": "whatsapp",
      "identifier": "18885658889",
      "name": "WhatsApp Main (18885658889)"
    },
    "contact_channel_account": {
      "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
      "channel": "whatsapp",
      "identifier": "15551234567",
      "data": {
        "name": "John Smith",
        "username": "johnsmith"
      }
    },
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Doe",
      "email": "jane.doe@contactcenter.com"
    },
    "flow": null,
    "queue": null,
    "status": "active"
  }
}

conversation fields come from the Conversation schema.

Notes

This endpoint is intended for WhatsApp conversations.
The initial message must be a WhatsApp template message (content_type: whatsapp_template).

Troubleshooting

401 Unauthorized

Returned if the API key is missing or invalid.

403 Forbidden

Returned if the API key does not have access to Messaging resources.

422 Unprocessable Entity

Returned when request validation fails (for example missing required fields, invalid UUIDs, or invalid template payload).

429 Too many requests

Returned if requests are rate limited.