Cómo extraer datos por lotes vía API (Data Extract API)

Cuándo usarla

• Necesitas exportar datos históricos de tickets para BI, auditoría o un dashboard externo
• Quieres alimentar informes personalizados con datos completos de Cloud Chat
• Necesitas rastrear eventos de entrega de campañas y envíos proactivos

Requisitos previos

• API Key generada por un usuario administrador o supervisor — ver Cómo obtener tu API Key en Cloud Chat

• CLOUDCHAT_DOMAIN y ACCOUNT_ID

• Período de extracción de máximo 5 días (120 horas) por solicitud

Sobre este artículo

La Data Extract API permite exportar datos completos de tus tickets directamente desde tu cuenta en Cloud Chat — fechas, estados, responsables, tiempos de respuesta y mucho más. Ideal para informes personalizados e integraciones externas.

Solicitud base

curl --location 'https://{CLOUDCHAT_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T01:58:59&endDate=2025-03-28T01:59:00&type=BASE_TICKET_METRICS' \
  --header 'Accept: application/json' \
  --header 'api_access_token: {API_TOKEN}'

Dónde encontrar los parámetros

• CLOUDCHAT_DOMAIN — parte de la URL al iniciar sesión en tu cuenta

  

• ACCOUNT_ID — después de iniciar sesión, el ID aparece en la URL como app/accounts/{id}/dashboard. Ej.: en cloudhumans.com/app/accounts/1/conversations/6341 el account_id es 1

• API_TOKEN — genéralo desde un perfil administrador o supervisor (en "Configurações do perfil" (Configuración del perfil), en tu propio entorno — usa el dominio de tu cuenta, ej.: https://TU-DOMINIO.cloudhumans.com/app/accounts/{ACCOUNT_ID}/profile/settings. El dominio varía según la instancia: cloudchat, cloudchat2, cloudchat3…)

  

Parámetros obligatorios

• startDate — Fecha y hora de inicio (UTC) en el formato yyyy-MM-ddTHH:mm:ss. Ej.: 2025-03-27T01:58:59

• endDate — Fecha y hora de término (UTC). Debe ser posterior a startDate y el intervalo no puede superar 5 días (120 horas). Ej.: 2025-03-28T01:59:00

• type — Tipo de datos a exportar (ver la lista abajo)

• account_id — ID de la cuenta, indicado en la ruta de la URL

Tipos disponibles

• BASE_TICKET_METRICS

• TICKET_METRICS_WITH_AGENT_INFORMATION

• TICKET_SUMMARY

• CAMPAIGN_DELIVERY_EVENTS

• SINGLE_CONTACT_DELIVERY_EVENTS

Parámetro opcional: rangeFilterProperty

Define qué campo de fecha se usa para aplicar los filtros de período.

Intervalo de fechas

Límite de solicitudes (rate limit)

La Data Extract API aplica un límite de 20 solicitudes por minuto por token. Tokens distintos de la misma cuenta tienen presupuestos independientes.

Qué pasa al superar el límite

Las solicitudes que superan el límite reciben HTTP 429 Too Many Requests:

{
  "error": "Rate limit exceeded. Retry later.",
  "retry_after": 42
}

Recomendaciones

1. BASE_TICKET_METRICS

Devuelve datos básicos de los tickets. Campos devueltos:

Ejemplo de respuesta

[
  {
    "ticketId": 123456,
    "displayTicketId": 7890,
    "inboxId": 101,
    "accountId": 42,
    "accountName": "Minha Empresa",
    "ticketStatus": "resolved",
    "teamName": "Meu Time",
    "ticketPriorityName": "High",
    "ticketType": "suporte",
    "inboxName": "WhatsApp",
    "ticketTitle": "+5511999999999",
    "channel": "Whatsapp",
    "createdAt": "2025-03-27T09:53:14.791Z",
    "firstReplyAt": "2025-03-27T10:09:29.225Z",
    "firstReplyTime": 16.24,
    "resolvedAt": "2025-03-27T13:20:15.830Z",
    "totalResolutionTimeMin": 207.01,
    "tags": "suporte,prioridade_alta",
    "agentId": 42,
    "ticketOwner": "ClaudIA",
    "ticketOwnerEmail": "[email protected]",
    "contactId": 998877,
    "contactName": "Contact Name",
    "contactEmail": "[email protected]",
    "contactPhone": "+5511887774411",
    "campaignId": 123,
    "proactivelyInitiated": true
  }
]

2. TICKET_METRICS_WITH_AGENT_INFORMATION

Incluye detalles sobre el agente que respondió y resolvió. Campos adicionales:

Ejemplo de respuesta

[
  {
    "ticketId": 11111,
    "displayTicketId": 11111,
    "accountName": "account name",
    "inboxName": "WhatsApp",
    "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/11111",
    "ticketStatus": "resolved",
    "createdAt": "2025-03-27T13:00:40.897954",
    "resolvedAt": "2025-03-27T15:38:02.743726",
    "agentOnResolutionId": 225,
    "agentOnResolutionName": "ClaudIA",
    "agentOnResolutionEmail": "[email protected]",
    "firstAgentReplyId": 111,
    "firstAgentReplyName": "ClaudIA",
    "firstAgentReplyEmail": "[email protected]",
    "firstAgentAssignmentTime": "2025-03-27T13:16:13.001269",
    "firstAgentFirstReplyTime": "2025-03-27T13:17:01.344971",
    "firstAgentReplyTimeMin": 0.81,
    "firstAgentResolutionTimeMin": 141.83,
    "csatScore": null,
    "csatFeedback": "",
    "contactCustomFields": "{}",
    "conversationCustomFields": "{}",
    "conversationAdditionalFields": "{}"
  }
]

3. TICKET_SUMMARY

Devuelve un resumen de la conversación del ticket. Campos devueltos:

[
  {
    "ticketId": 1111,
    "displayTicketId": 1111,
    "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111",
    "summary": "CONTATO: Oi\nUSUÁRIO: Olá!"
  }
]

4. CAMPAIGN_DELIVERY_EVENTS

Devuelve eventos de entrega de campañas de WhatsApp, rastreando por contacto y campaña el estado de los mensajes.

Campos devueltos:

Ejemplo de respuesta

[
  {
    "id": 103,
    "campaignId": 5502,
    "campaignTitle": "Natal 2025 - Promoção Especial",
    "audience": "lista_fidelidade_natal",
    "contactId": 9003,
    "contactName": "Carla Souza",
    "contactEmail": "[email protected]",
    "contactPhoneNumber": "+55 31 99999-99999",
    "ticketId": 78414,
    "displayTicketId": "2027",
    "messageSent": false,
    "sentAt": null,
    "messageReceived": false,
    "receivedAt": null,
    "messageRead": false,
    "readAt": null,
    "messageReplied": false,
    "repliedAt": null,
    "error": "Número de telefone inválido ou não registrado no WhatsApp",
    "createdAt": "2025-12-10T09:00:00.000Z",
    "updatedAt": "2025-12-10T09:00:00.000Z"
  }
]

5. SINGLE_CONTACT_DELIVERY_EVENTS

Devuelve eventos de entrega de mensajes proactivos de envío único (no campañas). Campos devueltos:

Ejemplo de respuesta

[
  {
    "id": 321,
    "contactId": 555777,
    "contactName": "Maria Silva",
    "contactEmail": "[email protected]",
    "contactPhoneNumber": "+55 11 98888-7777",
    "ticketId": 78414,
    "displayTicketId": "2027",
    "messageSent": true,
    "sentAt": "2025-08-01T12:00:05.000Z",
    "messageReceived": true,
    "receivedAt": "2025-08-01T12:00:08.000Z",
    "messageRead": true,
    "readAt": "2025-08-01T12:01:30.000Z",
    "messageReplied": false,
    "repliedAt": null,
    "error": null,
    "createdAt": "2025-08-01T11:59:59.000Z",
    "updatedAt": "2025-08-01T12:01:30.000Z"
  }
]

Paso a paso práctico

1. Genera tu API Key en un perfil administrador o supervisor ("Configurações do perfil" (Configuración del perfil) → consulta "Cómo obtener tu API Key").
2. Elige dónde ejecutarla: es una llamada HTTP GET — usa un cliente de API (Postman, Insomnia) o la terminal con curl. No hace falta programar.
3. Arma la URL reemplazando los campos entre {}: https://{TU_DOMINIO}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T00:00:00&endDate=2025-03-27T23:59:59&type=TICKET_METRICS_WITH_AGENT_INFORMATION
4. Agrega el encabezado de autenticación (obligatorio — sin él devuelve 401): api_access_token: {TU_API_KEY}
5. Envía la solicitud (botón Send en Postman, o ejecuta el curl).
6. Lee el resultado: llega un JSON con la lista de tickets; cada campo está descrito en las tablas de tipos de este artículo.

Observaciones

• Para consultas en tiempo real (no histórico): Cómo consultar contactos, tickets y mensajes en tiempo real vía API

• Para modificar datos de tickets vía API: Cómo actualizar y actuar en tickets vía API

• Visión general de todas las APIs disponibles: Guía Maestra — Cómo acceder y operar datos de Cloud Chat vía API