The Get list of conversation messages endpoint returns the messages in a specific conversation.

Requirements: Base URL, Authentication, Error codes

Scope: messaging.conversations.read

What this does

When you send a Get list of conversation messages request,

When to use it

• Retrieve conversation history for display in an external system, such as a CRM
• Export messages for audits or analytics
• Review message delivery status for a conversation

Endpoint

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

Request parameters

Path parameters

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

Query parameters

All query parameters are optional.

• limit
  The number of items to return. Default is 100. Maximum is 100.
• offset
  The number of items to skip before collecting results. Default is 0.

Examples

Minimal request

curl -X GET "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"

Request the third page of results (20 per page)

curl -X GET "https://{cluster_id}.voiso.com/api/v4/messaging/conversations/0b62763c-40d6-4ec8-8380-3cb94e442a75/messages?limit=20&offset=40" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Response

If successful, the API returns an array of message objects and pagination metadata.

Example response for a text message:

{
  "messages": [
    {
      "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": "Hi, how can I help you?"
      },
      "status": "delivered",
      "status_reason": null,
      "created_at": "2025-11-11T12:00:00.216Z",
      "updated_at": "2025-11-11T12:00:00.216Z"
    }
  ],
  "metadata": {
    "total": 100
  }
}

Example response for a media message:

{
  "messages": [
    {
      "id": "1f839685-9b8f-4d01-8a7a-c5a91532e2f7",
      "conversation": {
        "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75"
      },
      "direction": "inbound",
      "user": null,
      "target_user": null,
      "content_type": "document",
      "content_data": {
        "url": "https://cdn.domain.tld/media/ext/invoice.pdf",
        "filename": "invoice.pdf",
        "size": 20480,
        "caption": "Please review the attached invoice."
      },
      "status": "sent",
      "status_reason": null,
      "created_at": "2025-11-11T12:00:00.216Z",
      "updated_at": "2025-11-11T12:00:00.216Z"
    }
  ],
  "metadata": {
    "total": 100
  }
}

Notes

• direction can be inbound, outbound, or whisper.

• content_data depends on content_type:

  • For text, content_data includes text.
  • For audio, document, image, video, or voice, content_data can include url, plus optional filename, size, and caption.

• user is the agent who sent the message. It can be null for contact messages or system generated messages.

• target_user is used for whisper messages and can be null.

Troubleshooting

401 Unauthorized

What to check:

• You are sending Authorization: Bearer <contact_center_api_key>.
• Your Base URL includes the correct {cluster_id}.

403 Forbidden

What to check:

• The API key is valid, but does not have access to this conversation or its messages.

404 Not found

This usually means the conversation ID does not exist, or you do not have access to it.

What to check:

• Confirm the conversation ID using Get list of conversations.

429 Too many requests

What to do:

• Reduce request frequency and retry with backoff.