The Get list of conversations endpoint returns the messaging conversations you can access.

Requirements: Base URL, Authentication, Error codes

Scope: messaging.conversations.read

What this does

When you send a Get list of conversations request, Voiso returns a paginated list of conversation objects, including routing context (flow and queue), assigned user (if any), and the contact’s channel account.

When to use it

List conversations in an external system, such as a CRM
Retrieve conversation IDs before requesting messages for a conversation
Audit conversation status and routing context

Endpoint


GET /api/v4/messaging/conversations

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" \
  -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?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 conversation objects and pagination metadata.

{
  "conversations": [
    {
      "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": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
        "name": "Jane Doe",
        "email": "jane.doe@contactcenter.com"
      },
      "flow": {
        "id": "0b62763c-40d6-4ec8-8380-3cb94e442a75",
        "name": "Lead Qualification"
      },
      "queue": {
        "id": 1,
        "name": "Technical Support"
      },
      "status": "active"
    }
  ],
  "metadata": {
    "total": 100
  }
}

Notes

Use the conversation id with the conversation messages endpoint to retrieve the message history for a conversation.

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 conversations in this contact center.

429 Too many requests

What to do:

Reduce request frequency and retry with backoff.