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,

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