A Data Extract API permite exportar dados completos dos seus tickets direto da sua conta no CloudChat, com 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}'

O que você precisa substituir:

{CLOUDCHAT_DOMAIN}: seu domínio CloudChat (ex: app.cloudchat.cloudhumans.com)
{ACCOUNT_ID}: ID da conta
{API_TOKEN}: token de acesso gerado no perfil de um administrador ou supervisor

Como obter essas informações?

{CLOUDCHAT_DOMAIN} - Você pode obter seu domínio ao fazer login na sua conta no CloudChat. É a parte que aparece na URL do navegador, por exemplo:

{ACCOUNT_ID} - Após o login, verifique a URL da sua dashboard inicial. O ID da conta aparece na URL como: app/accounts/1/dashboard. Encontrado na URL do seu Cloud Chat, após "accounts"; ex.: https://cloudchat.cloudhumans.com/app/accounts/**1**/conversations/6341 (nesse caso, o account_id é 1)

{API_TOKEN} - O token de API deve ser gerado a partir do perfil de um usuário com permissão de administrador ou supervisor (na configuração de perfil):

Quais parâmetros são obrigatórios?

Ao fazer a requisição para a API, você deve informar os seguintes parâmetros:

startDate:
Data e hora de início da extração.
Formato esperado: yyyy-MM-ddTHH:mm:ss
Exemplo: 2025-03-27T01:58:59
endDate:
Data e hora de término da extração.
Deve ser posterior ao startDate e o intervalo entre as duas datas não pode ultrapassar 5 dias (120 horas).
Exemplo: 2025-03-28T01:59:00
type:
O tipo de dados que deseja exportar.
Tipos disponíveis:

BASE_TICKET_METRICS, TICKET_METRICS_WITH_AGENT_INFORMATION, TICKET_SUMMARY, CAMPAIGN_DELIVERY_EVENTS
account_id:
ID da sua conta no CloudChat.
Esse valor é informado no caminho da URL (ex: /accounts/1/data_extracts, onde o ID da conta é 1).

Observação sobre o intervalo de datas

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

Se você deseja exportar dados de um período maior (por exemplo, 30 dias), é possível dividir a consulta em múltiplas requisições.

Exemplo: Para extrair dados de um mês completo, você pode fazer 6 requisições consecutivas com intervalos de até 5 dias cada, variando o startDate e endDate de acordo com o período desejado.

Tipos de extração disponíveis via API

A Data Extract API agora suporta os seguintes valores para o parâmetro type:

BASE_TICKET_METRICS
TICKET_METRICS_WITH_AGENT_INFORMATION
TICKET_SUMMARY
CAMPAIGN_DELIVERY_EVENTS (novo)

1. BASE_TICKET_METRICS

Retorna dados básicos dos tickets, como:

ticketId: identificador interno e único do ticket
displayTicketId: ID visível na interface (o número do ticket que aparece na URL)
inboxId: ID da caixa de entrada usada
accountId e accountName: ID e nome da sua conta no Cloud Chat
ticketStatus: status do ticket (ex: resolved, open, pendente)
teamName: Nome do time atribuído ao ticket
ticketPriorityName: Prioridade atribuída ao ticket (ex: low, mediu, high, urgent)
ticketType: é a primeira tag colocada no ticket
inboxName: nome da Inbox usada
ticketTitle: título do ticket: uma concatenação do título do ticket (quando existir, pra email, por exemplo), telefone do contato e nome do contato
channel: canal usado (ex: WhatsApp, e-mail)
createdAt: timestamp de criação do ticket
firstReplyAt: timestamp da primeira resposta
firstReplyTime: tempo até a primeira resposta (em minutos)
resolvedAt: timestamp de resolução (se o ticket foi reaberto e, portanto, contém mais de uma resolução, é considerado a última data de resolução)
totalResolutionTimeMin: tempo total de resolução (em minutos)
tags: tags associadas ao ticket
agentId, ticketOwner e ticketOwnerEmail: ID, nome e email do agente responsável
contactId, contactName, contactEmail, contactPhone ID, nome do contato, email do contato e telefone do contato (cliente que abriu o ticket)

⚠️ IMPORTANTE: o timestamp é o que você definiu na configuração da conta (link da FAQ de como definir o timestamp / fuso horário aqui). Caso não tenha feito, o timestamp será em UTC

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

2. TICKET_METRICS_WITH_AGENT_INFORMATION

Inclui os dados com detalhes sobre o agente que respondeu e resolveu, como:

ticketId: identificador interno e único do ticket
displayTicketId: ID visível na interface (o número do ticket que aparece na URL)
accountName: ID e nome da sua conta no Cloud Chat
inboxName: nome da Inbox usada
ticketLink: link do ticket para abrir diretamente ele no Cloud Chat
agentOnResolutionId, agentOnResolutionName e agentOnResolutionEmail: ID, nome e email do agente humano que resolveu o ticket
firstAgentReplyId, firstAgentReplyName, firstAgentReplyEmail: ID, nome e email do agente humano que respondeu primeiro
firstAgentAssignmentTime: timestamp da atribuição ao primeiro agente humano a entrar no ticket
firstAgentFirstReplyTime: timestamp da primeira resposta do primeiro agente humano a entrar no ticket
firstReplierAgentAssignmentTime : timestamp da atribuição do agente humano que primeiro respondeu o ticket
firstReplierAgentFirstReplyTime : tempo de primeira resposta humana ao ticket(caso o primeiro agente humano atribuído não responda o ticket, esse dado será diferente ao firstAgentFirstReplyTime)
firstAgentReplyTimeMin: tempo até a primeira resposta do primeiro agente humano a entrar no ticket desde sua atribuição (minutos)
firstAgentResolutionTimeMin: tempo entre a abertura do ticket até a última resolução do ticket (minutos)
csatScore e csatFeedback: avaliação (nota) de satisfação do cliente (CSAT) e comentário do CSAT (se houver)
contactCustomFields: campos personalizados do contato (JSON)
conversationCustomFields: campos personalizados da conversa (JSON)
conversationAdditionalFields: outros campos complementares que podem ou não vir no canal que o cliente entrou (JSON). Esse campo vêm preenchido se:
- O canal é passível de passar essa informação
- O cliente habilitou para passar essa informação no canal

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

⚠️ Importante:

firstAgentReplyTimeMin — Calculado como o tempo entre o momento de atribuição do primeiro agente do ticket (firstAgentAssignmentTime) até sua primeira resposta (firstAgentFirstReplyTime).
firstAgentResolutionTimeMin — Calculado como o tempo entre a atribuição do primeiro agente do ticket (firstAgentAssignmentTime) até o momento em que o ticket foi resolvido (resolvedAt).

3. TICKET_SUMMARY

Retorna um resumo textual (é a conversa inteira) da conversa dentro do ticket. Inclui ticketId, displayTicketId, ticketLink e summary.

Exemplo de resposta:

[
  {
    "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 no CloudChat, centralizando e rastreando, por contato e campanha, o status de mensagens enviadas.

O objetivo é consolidar em um único ponto dados de eventos de campanha como envio, recebimento, leitura, resposta e erros.

Campos retornados:

id: Identificador único do evento de entrega da campanha
campaignId: ID da campanha
campaignTitle: Título da campanha
audience: Nome do público da campanha
contactId: ID do contato
contactName: Nome do contato
contactEmail: E-mail do contato
contactPhoneNumber: Número de telefone do contato
ticketId: ID interno do ticket vinculado
displayTicketId: ID visível do ticket (exibido na URL da conversa / ticket)
messageSent: Indica se a mensagem foi enviada com sucesso para a API do WhatsApp (Meta)
sentAt: Data/hora em que a mensagem foi efetivamente enviada para a API do WhatsApp
messageReceived: Indica se o WhatsApp confirmou que a mensagem foi entregue ao dispositivo do contato
receivedAt: Data/hora em que a confirmação de entrega foi recebida
messageRead: Indica se o WhatsApp confirmou que a mensagem foi lida pelo contato.
⚠ Esse evento só será registrado se o contato tiver o status de leitura habilitado nas configurações de privacidade do WhatsApp
readAt: Data/hora em que a confirmação de leitura foi recebida (ou null caso não tenha ocorrido)
messageReplied: Indica se o contato enviou alguma resposta após receber a mensagem da campanha
repliedAt: Data/hora em que a primeira resposta foi registrada
error: Mensagem de erro retornada, caso o envio não tenha sido realizado ou tenha falhado em alguma etapa (por exemplo: número inválido, contato sem WhatsApp, bloqueio, etc.)
createdAt: Data/hora de criação do registro na base de dados do CloudChat
updatedAt: Data/hora da última atualização do registro (por exemplo, quando novos eventos de entrega ou leitura foram recebidos)

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

API de Extração de Dados (Data Extract API)

Requisição base:

O que você precisa substituir:

Como obter essas informações?

Quais parâmetros são obrigatórios?

Observação sobre o intervalo de datas

Tipos de extração disponíveis via API

1. BASE_TICKET_METRICS

2. TICKET_METRICS_WITH_AGENT_INFORMATION

3. TICKET_SUMMARY

Exemplo de resposta:

4. CAMPAIGN_DELIVERY_EVENTS