Listar Conversaciones

Devuelve un resumen paginado de las conversaciones. Para descargar el historial de un hilo, usa Obtener conversación con su id.

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

Parámetros de consulta

Parámetro	Tipo	Descripción	Requerido
`limit`	integer	Número máximo de conversaciones a retornar. Por defecto: `50`	—
`pageToken`	string	Cursor `nextPageToken` de la respuesta anterior. Recomendado sobre `offset`. No se combina con `offset` y se invalida si cambias los filtros o el ordenamiento	—
`offset`	integer	Número de conversaciones a saltar. Alternativa heredada a `pageToken`; máximo `100000`	—
`channelId`	string	Filtrar por identificador del canal	—
`clientId`	string	Filtrar por el cliente atribuido a la conversación	—
`agentId`	string	Filtrar por el agente principal de la conversación	—
`sortBy`	string	Campo de ordenamiento: `lastUpdate` o `creationDate`	—
`sortDirection`	string	Dirección del ordenamiento: `asc` o `desc`	—
`tags`	array	Lista de etiquetas para filtrar. Puede enviarse como CSV en query string	—
`dateFilter`	object	Filtro por fecha específica o rango	—

Nota

clientId y agentId se ejecutan en Firestore antes de paginar. Para mantener consultas predecibles, no pueden combinarse entre sí ni con channelId o tags; sí admiten ordenamiento y dateFilter.

Fecha específica:

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

Rango de fechas:

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

Respuesta

{
  "workspaces": [
    {
      "id": "ws_001",
      "name": "Soporte Técnico",
      "conversations": [
        {
          "id": "conv_001",
          "conversationId": "conv-id-19229",
          "clientId": "cliente_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..."
}

Campo	Descripción
`id`	ID único y canónico del documento de conversación. Úsalo en `GET` y `PATCH /v1/conversations/{id}`
`conversationId`	ID del hilo de chat. En Chat API tiene formato `chat_*`; no identifica al cliente
`clientId`	ID del cliente atribuido a la conversación
`agentId`	ID del agente principal de la conversación; no cambia durante una delegación temporal a un subagente
`source`	Origen interno cuando está disponible (por ejemplo `api_chat`); puede ser `null` en conversaciones legacy
`canSendDirectMessage`	Solo puede ser `false` en WhatsApp, Instagram y Messenger/Facebook; se calcula desde el último mensaje del usuario. En chats internos de Platica siempre es `true`
`workspaceId`	ID del workspace al que pertenece la conversación
`channelId`	ID del canal de comunicación
`contactName`	Nombre del contacto/cliente
`phoneNumber`	Número de teléfono del cliente
`topic`	Tema o asunto de la conversación
`platform`	Plataforma de mensajería (`whatsapp`, `telegram`, etc.)
`status`	Etapa operativa: `initiated`, `active`, `finished`, `spam` o `expired`
`operation`	Modo de operación de la conversación
`messageCount`	Número total de mensajes
`owners`	Lista de correos de usuarios responsables
`tags`	Etiquetas asociadas a la conversación
`creationDate`	Fecha de creación de la conversación
`lastUpdate`	Fecha de última actualización

Campo	Descripción
`limit`	Número máximo de resultados por página
`offset`	Número de resultados omitidos
`hasMore`	Indica si hay más resultados disponibles en ese workspace
`nextPageToken`	Cursor para pedir la página siguiente; `null` cuando no quedan resultados. Un solo token cubre todos los workspaces de la key, por eso va en la raíz y no dentro de cada uno

Consejo

Usa canSendDirectMessage para verificar la ventana de servicio de WhatsApp, Instagram y Messenger/Facebook. En cualquier otra plataforma, incluidos los chats internos, siempre es true.

Anterior Introducción Siguiente Obtener conversación