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 (integer).
source
Information about the external system that provided the contact.
- source.system
  The name of an external application, such as a CRM.
- source.account_id
  An identifier assigned to the contact in an external application, such as a CRM.

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": 1,
    "source": {
      "system": "zoho",
      "account_id": "123321"
    },
    "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": 1,
      "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).
source is optional. If you provide source, include both source.system and source.account_id.

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 IDs, or invalid template payload).

429 Too many requests

Returned if requests are rate limited.

201Created

401Unauthorized

403Forbidden

422Unprocessable Entity

429Too many requests