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,

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": "[email protected]"
    },
    "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.