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

Esta API é destinada exclusivamente para extração histórica em lote. Para consultas em tempo real ou ações em tickets, use as outras APIs do Guia Mestre.

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.

Valor	Comportamento
`CREATED_AT` (padrão)	Filtra pela data de criação
`UPDATED_AT`	Filtra pela data da última atualização

Intervalo de datas

Para garantir estabilidade e performance, o intervalo máximo permitido por requisição é de 5 dias.

Para exportar períodos maiores (ex: 30 dias), divida em múltiplas requisições — 6 chamadas consecutivas com janelas de 5 dias cobrem um mês inteiro.

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

Respeite o cabeçalho Retry-After antes de tentar novamente. Loops de retry sem backoff amplificam o bloqueio
Para extrações grandes (ex: 30 dias), combine janelas de 5 dias com espaçamento entre requisições — 20/min é folgado para o volume típico
Se sua integração precisa de throughput maior de forma sustentada, acione o suporte

1. BASE_TICKET_METRICS

Retorna dados básicos dos tickets. Campos retornados:

ticketId, displayTicketId, inboxId, accountId, accountName
ticketStatus, teamName, ticketPriorityName, ticketType (primeira tag), inboxName
ticketTitle, channel, tags
createdAt, firstReplyAt, firstReplyTime (minutos), resolvedAt, totalResolutionTimeMin
agentId, ticketOwner, ticketOwnerEmail
contactId, contactName, contactEmail, contactPhone
campaignId, proactivelyInitiated

Ao configurar fuso horário da conta (ex: GMT-3), os campos timestamp (createdAt, firstAgentAssignmentTime, firstReplyAt, firstAgentFirstReplyTime, resolvedAt, firstReplyTime, firstReplierAgentAssignmentTime, firstReplierAgentFirstReplyTime, repliedAt, readAt, receivedAt, sentAt) são retornados no fuso configurado. Sem fuso configurado, os horários vêm em UTC.

Configuração: Configuração de fuso horário.

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:

ticketLink — link direto do ticket
agentOnResolutionId, agentOnResolutionName, agentOnResolutionEmail — agente humano que resolveu
firstAgentReplyId, firstAgentReplyName, firstAgentReplyEmail — primeiro agente humano que respondeu
firstAgentAssignmentTime, firstAgentFirstReplyTime
firstReplierAgentAssignmentTime, firstReplierAgentFirstReplyTime
firstAgentReplyTimeMin, firstAgentResolutionTimeMin
csatScore, csatFeedback
contactCustomFields, conversationCustomFields, conversationAdditionalFields (JSON)

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

firstAgentReplyTimeMin — tempo entre firstAgentAssignmentTime e firstAgentFirstReplyTime
firstAgentResolutionTimeMin — tempo entre firstAgentAssignmentTime e resolvedAt

3. TICKET_SUMMARY

Retorna a transcrição completa da conversa do ticket. Inclui ticketId, displayTicketId, ticketLink e summary.

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

id, campaignId, campaignTitle, audience
contactId, contactName, contactEmail, contactPhoneNumber
ticketId, displayTicketId
messageSent, sentAt — envio para a API do WhatsApp (Meta)
messageReceived, receivedAt — entrega ao dispositivo do contato
messageRead, readAt — leitura confirmada (depende do status de leitura habilitado nas configurações de privacidade do contato)
messageReplied, repliedAt — primeira resposta
error — mensagem de erro (número inválido, sem WhatsApp, bloqueio, etc.)
createdAt, updatedAt

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). Mesma estrutura de campos do CAMPAIGN_DELIVERY_EVENTS, sem os campos de campanha.

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

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

Quando usar

Pré-requisitos

Sobre este artigo

Requisição base

Onde encontrar os parâmetros

Parâmetros obrigatórios

Tipos disponíveis

Parâmetro opcional: rangeFilterProperty

Intervalo de datas

Limite de requisições (rate limit)

O que acontece ao ultrapassar o limite

Recomendações

1. BASE_TICKET_METRICS

Exemplo de resposta

2. TICKET_METRICS_WITH_AGENT_INFORMATION

Exemplo de resposta

3. TICKET_SUMMARY

4. CAMPAIGN_DELIVERY_EVENTS

Exemplo de resposta

5. SINGLE_CONTACT_DELIVERY_EVENTS

Exemplo de resposta

Observações

Parâmetro opcional: `rangeFilterProperty`