Como extrair dados em lote via API (Data Extract API)

Quando usar

• Você precisa exportar dados históricos de tickets para BI, auditoria ou dashboard externo
• Você quer alimentar relatórios customizados com dados completos do Cloud Chat
• Você precisa rastrear eventos de entrega de campanhas e disparos proativos

Pré-requisitos

• API Key gerada por usuário administrador ou supervisor — ver Como encontrar sua API Key no Cloud Chat

• CLOUDCHAT_DOMAIN e ACCOUNT_ID

• Período de extração de no máximo 5 dias (120 horas) por requisição

Sobre este artigo

A Data Extract API permite exportar dados completos dos seus tickets diretamente da sua conta no Cloud Chat — datas, status, responsáveis, tempos de resposta e muito mais. Ideal para relatórios personalizados e integrações externas.

Requisição 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}'

Onde encontrar os parâmetros

• CLOUDCHAT_DOMAIN — parte da URL ao fazer login na sua conta

  

• ACCOUNT_ID — após o login, o ID aparece na URL como app/accounts/{id}/dashboard. Ex: em cloudhumans.com/app/accounts/1/conversations/6341 o account_id é 1

• API_TOKEN — gere a partir de um perfil administrador ou supervisor (na configuração do perfil)

  

Parâmetros obrigatórios

• startDate — Data e hora de início (UTC) no formato yyyy-MM-ddTHH:mm:ss. Ex: 2025-03-27T01:58:59

• endDate — Data e hora de término (UTC). Deve ser posterior a startDate e o intervalo não pode ultrapassar 5 dias (120 horas). Ex: 2025-03-28T01:59:00

• type — Tipo de dados a exportar (ver lista abaixo)

• account_id — ID da conta, informado no caminho da URL

Tipos disponíveis

• BASE_TICKET_METRICS

• TICKET_METRICS_WITH_AGENT_INFORMATION

• TICKET_SUMMARY

• CAMPAIGN_DELIVERY_EVENTS

• SINGLE_CONTACT_DELIVERY_EVENTS

Parâmetro opcional: rangeFilterProperty

Define qual campo de data é usado para aplicar os filtros de período.

Intervalo de datas

Limite de requisições (rate limit)

A Data Extract API aplica um limite de 20 requisições por minuto por token. Tokens distintos da mesma conta têm orçamentos independentes.

O que acontece ao ultrapassar o limite

Requisições além do limite recebem HTTP 429 Too Many Requests:

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

Recomendações

1. BASE_TICKET_METRICS

Retorna dados básicos dos tickets. Campos retornados:

Exemplo de resposta

[
  {
    "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

Inclui detalhes sobre o agente que respondeu e resolveu. Campos adicionais:

Exemplo de resposta

[
  {
    "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

Retorna a transcrição completa da conversa do ticket. Campos retornados:

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

4. CAMPAIGN_DELIVERY_EVENTS

Retorna eventos de entrega de campanhas do WhatsApp, rastreando por contato e campanha o status das mensagens.

Campos retornados:

Exemplo de resposta

[
  {
    "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

Retorna eventos de entrega de mensagens proativas de disparo único (não campanhas). Campos retornados:

Exemplo de resposta

[
  {
    "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"
  }
]

Observações

• Para consultas em tempo real (não histórico): Como consultar contatos, tickets e mensagens em tempo real via API

• Para alterar dados de tickets via API: Como atualizar e agir em tickets via API

• Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API