The Create message endpoint sends a message in an existing conversation.

Requirements: Base URL, Authentication, Error codes

Scope: messaging.conversations.manage

What this does

When you send a Create message request,

Endpoint

POST /api/v4/messaging/conversations/{conversation_id}/messages

Path parameters

• conversation_id
  The unique identifier of the conversation (UUID).

Request body

Required fields:

• content_type
  The message content type. Supported values include audio, document, image, text, video, whatsapp_template.
• content_data
  Content payload. Structure varies by content_type.

content_data by content_type

The YAML defines content_data using a oneOf structure.

• Text message
  • body (string, required)
• Media message (audio, document, image, video)
  • url (string, required)
  • filename (string, optional)
• WhatsApp template message
  • whatsapp_template_id (uuid, required)
  • placeholders (object, optional)

Related endpoints

• Get conversation IDs: Get list of conversations
• Get message IDs: Get list of conversation messages
• Get a WhatsApp template ID: Get list of WhatsApp templates

Example requests

Send a text message

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/conversations/0b62763c-40d6-4ec8-8380-3cb94e442a75/messages" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "text",
    "content_data": {
      "body": "Hello, how can we assist you?"
    }
  }'

Send a media message

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/conversations/0b62763c-40d6-4ec8-8380-3cb94e442a75/messages" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "video",
    "content_data": {
      "url": "https://example.com/file.mp4",
      "filename": "file.mp4"
    }
  }'

Send a WhatsApp template message

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/conversations/0b62763c-40d6-4ec8-8380-3cb94e442a75/messages" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "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 message object.

Example response:

{
  "message": {
    "id": "1f839685-9b8f-4d01-8a7a-c5a91532e2f7",
    "conversation": {
      "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75"
    },
    "direction": "outbound",
    "user": {
      "id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "target_user": null,
    "content_type": "text",
    "content_data": {
      "text": "Hello, how can we assist you?"
    },
    "status": "delivered",
    "status_reason": null,
    "created_at": "2025-11-11T12:00:00.216Z",
    "updated_at": "2025-11-11T12:05:00.216Z"
  }
}

Message response fields (direction, content_type, content_data, status, timestamps) are defined in the Message schema.

Notes

• The request uses content_data.body for text messages, but the message object uses content_data.text when returned.
• status_reason is returned only when the message has a failed status.

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.

404 Not found

Returned if the conversation ID does not exist or is not accessible.

422 Unprocessable Entity

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

429 Too many requests

Returned if requests are rate limited.