List conversations

Returns a paginated conversation summary. To download a thread's history, use Get conversation with its id.

GET https://api.platica.mx/v1/conversations

Query parameters

Parameter	Type	Description	Required
`limit`	integer	Maximum number of conversations to return. Default: `50`	—
`pageToken`	string	`nextPageToken` cursor from the previous response. Preferred over `offset`. Cannot be combined with `offset`, and is invalidated if you change the filters or the sort	—
`offset`	integer	Number of conversations to skip. Legacy alternative to `pageToken`; capped at `100000`	—
`channelId`	string	Filter by channel identifier	—
`clientId`	string	Filter by the client attributed to the conversation	—
`agentId`	string	Filter by the conversation's principal agent	—
`sortBy`	string	Sort field: `lastUpdate` or `creationDate`	—
`sortDirection`	string	Sort direction: `asc` or `desc`	—
`tags`	array	List of tags to filter by. May be sent as a CSV value in the query string	—
`dateFilter`	object	Filter by specific date or range	—

Nota

clientId and agentId run in Firestore before pagination. To keep queries predictable, they cannot be combined with each other or with channelId or tags; sorting and dateFilter remain available.

Specific date:

GET /v1/conversations?dateFilter={"type":"specific","date":"2024-01-15"}

Date range:

GET /v1/conversations?dateFilter={"type":"range","startDate":"2024-01-01","endDate":"2024-01-31"}

Response

{
  "workspaces": [
    {
      "id": "ws_001",
      "name": "Soporte Técnico",
      "conversations": [
        {
          "id": "conv_001",
          "conversationId": "conv-id-19229",
          "clientId": "client_123",
          "agentId": "agent_001",
          "source": null,
          "canSendDirectMessage": true,
          "workspaceId": "ws_001",
          "channelId": "channel_001",
          "contactName": "Juan Pérez",
          "phoneNumber": "1234567890",
          "topic": "Problemas técnicos",
          "platform": "whatsapp",
          "status": "active",
          "operation": "automatic",
          "messageCount": 12,
          "owners": [
            "soporte@empresa.com"
          ],
          "tags": [
            "vip",
            "soporte"
          ],
          "creationDate": "2025-03-15T10:00:00Z",
          "lastUpdate": "2025-03-15T10:15:00Z"
        }
      ],
      "conversationsCount": 1,
      "pagination": {
        "limit": 50,
        "offset": 0,
        "hasMore": true
      }
    }
  ],
  "nextPageToken": "eyJ2IjoxLCJxIjoiYTFi..."
}

Field	Description
`id`	Unique, canonical document ID of the conversation. Use it in `GET` and `PATCH /v1/conversations/{id}`
`conversationId`	Chat thread ID. It uses the `chat_*` format in the Chat API and does not identify the client
`clientId`	ID of the client attributed to the conversation
`agentId`	Principal agent ID; temporary delegation to a subagent does not change it
`source`	Internal origin when available (for example `api_chat`); may be `null` for legacy conversations
`canSendDirectMessage`	Can only be `false` on WhatsApp, Instagram, and Messenger/Facebook; calculated from the latest user message. Always `true` for internal Platica chats
`workspaceId`	ID of the workspace the conversation belongs to
`channelId`	Communication channel ID
`contactName`	Contact/customer name
`phoneNumber`	Customer phone number
`topic`	Conversation topic or subject
`platform`	Messaging platform (`whatsapp`, `telegram`, etc.)
`status`	Operational stage: `initiated`, `active`, `finished`, `spam`, or `expired`
`operation`	Conversation operation mode
`messageCount`	Total number of messages
`owners`	List of responsible-user emails
`tags`	Tags associated with the conversation
`creationDate`	Conversation creation date
`lastUpdate`	Last update date

Field	Description
`limit`	Maximum number of results per page
`offset`	Number of results skipped
`hasMore`	Indicates whether more results are available in that workspace
`nextPageToken`	Cursor to request the next page; `null` when no results are left. A single token covers every workspace the key can read, which is why it sits at the root instead of inside each one

Consejo

Use canSendDirectMessage to check the service window on WhatsApp, Instagram, and Messenger/Facebook. It is always true on every other platform, including internal chats.

Previous Search conversations Next Get conversation