Principal APIs
🔗

APIs

Aqui estão os artigos relacionados a APIs disponíveis para enviar e puxar informações do Cloud Chat.
Por Matheus and 7 outros
• 18 artigos

Como enviar mensagem proativa pelo WhatsApp via API

Quando usar - Você quer iniciar uma conversa de WhatsApp por API a partir de um sistema externo - Você precisa disparar templates aprovados pela Meta com variáveis dinâmicas - Você precisa entender o comportamento esperado do ticket criado por essa API Pré-requisitos - WhatsApp já conectado ao Cloud Chat com inbox_id válido — ver Guia Mestre — Como conectar seu número de WhatsApp ao Cloud Chat - Template aprovado pela Meta cadastrado no Cloud Chat — ver Como criar, editar e excluir templates de WhatsApp no Cloud Chat - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - Número de telefone do destinatário no formato E.164 (ex: +5511999998888) Sobre este artigo Este endpoint cria uma conversa proativa pelo WhatsApp usando um template previamente configurado. Os parâmetros do template são dinâmicos e variam conforme a configuração do template. Comportamento de criação do ticket :::info Como o sistema não sabe qual agente deve receber, a mensagem não nasce assignada. Por isso o balão aparece verde (mensagens automáticas), em vez de laranja. ::: - Gera um novo ticket — exceto se a inbox estiver configurada com conversa única (lock to single conversation), caso em que a mensagem é adicionada à conversa existente do contato - O ticket nasce com status em aberto :::warning Se o cliente tiver dois tickets em aberto, novas mensagens enviadas pelo cliente serão sempre direcionadas ao ticket mais recente. ::: Endpoint POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Chave de acesso da API | Parâmetros do body | Parâmetro | Obrigatório | Descrição | | --- | --- | --- | | inbox_id | Sim | ID da inbox por onde a mensagem será enviada | | phone_number | Sim | Número do destinatário em formato E.164 | | template_name | Sim | Nome exato do template aprovado | | labels | Não | Array de strings com tags a aplicar na conversa criada — ver seção Aplicando tags (labels) abaixo | | header_attachment | Não | URL do anexo, se o template suportar mídia no cabeçalho | | button_param_# | Não | Variáveis de botões — substituir # pelo índice (0 a N) | | Variáveis do template | Não | Variáveis específicas do template (chave-valor na raiz do JSON) | Sobre as variáveis dinâmicas Templates podem conter variáveis como {{contact.name}}, {{contact.email}} ou estáticas como "Fulaninho". Envie essas variáveis diretamente na raiz do JSON, ao lado de inbox_id, phone_number e template_name. Exemplo de requisição curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \ --header 'content-type: application/json' \ --header 'api_access_token: ACCESS_TOKEN' \ --data '{ "inbox_id": "INBOX_ID", "phone_number": "+5511999998888", "template_name": "test_template", "labels": ["campanha-x", "vip"], "header_attachment": "ATTACHMENT_URL", "button_param_0": "BUTTON PARAMETER", "button_param_1": "ANOTHER BUTTON PARAMETER", "name": "John Doe", "email": "[email protected]", "custom_code": "12345" }' Onde encontrar os parâmetros - account_id — no painel administrativo da conta - inbox_id — ID da caixa de entrada configurada (https://cloudchat.cloudhumans.com/app/accounts/{account_id}/settings/inboxes/{inbox_id}) - api_access_token — gere no painel de configuração de API - Variáveis dinâmicas — consulte a configuração do template no painel administrativo. Esses parâmetros vão na raiz do payload. :::warning Certifique-se de que o número de telefone esteja no formato E.164, com o código do país. ::: Aplicando tags (labels) na conversa criada O parâmetro opcional labels recebe um array de strings com os títulos das tags a aplicar na conversa criada pelo disparo — sem precisar de uma segunda chamada à API de labels. "labels": ["campanha-x", "vip"] Comportamento: - Os títulos são normalizados: espaços nas pontas removidos, convertidos para minúsculas e deduplicados. - As tags são adicionadas à conversa (nunca substituem tags existentes) — em inboxes com conversa única, as tags de disparos anteriores e as aplicadas por agentes são preservadas. - Se a tag ainda não existir na conta, ela é criada automaticamente (e passa a aparecer nos filtros do painel) — desde que o token utilizado seja de um administrador. Com token de agente (não-admin), apenas tags já existentes na conta são aplicadas; títulos novos são ignorados silenciosamente. - Omitir o parâmetro (ou enviar um array vazio) mantém o comportamento anterior — nenhuma tag é aplicada. Limite de requisições (rate limit) Este endpoint aceita no máximo 200 requisições por minuto. Acima desse limite, a API responde HTTP 429 e a requisição não é processada (a mensagem não é enviada). A resposta inclui os headers: | Header | Descrição | | --- | --- | | Retry-After | Segundos até a janela liberar novas requisições | | X-RateLimit-Limit | Limite de requisições da janela (200) | | X-RateLimit-Remaining | Requisições restantes na janela atual | Exemplo de resposta ao exceder o limite: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } :::warning Se a sua integração dispara mensagens em lote, trate o retorno 429 reenviando a requisição após o tempo indicado em Retry-After. Sem esse tratamento, os disparos que excederem o limite serão perdidos. ::: Observações - Para integrar este endpoint a workflows do HubSpot: Como enviar mensagem proativa pelo WhatsApp via HubSpot - Para entender quais APIs estão disponíveis no Cloud Chat: Guia Mestre — Como acessar e operar dados do Cloud Chat via API - Para evitar bloqueios e cuidar da reputação do número: Como evitar bloqueios e banimentos no WhatsApp

Última atualização em Jul 22, 2026

Como importar contatos em massa via API

Quando usar - Você precisa importar ou atualizar vários contatos no Cloud Chat de uma vez via API - Você quer fazer upsert (criar novos + atualizar existentes) na mesma chamada - Você precisa de funcionalidades avançadas como tags granulares, lookup de variantes de telefone ou merge de JSONB Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID - Cada contato deve ter ao menos um identificador entre phone_number, email ou identifier :::info Quer importar apenas um contato? Use o endpoint de Como importar um contato individual via API. Os dois endpoints têm formatos de body diferentes — não misture. ::: Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição O body usa um array data contendo os contatos a serem importados: { "upsert": true, "data": [ { "name": "Contato 1", "email": "[email protected]", "phone_number": "+5511999998888", "identifier": "EXT-001", "additional_attributes": { "company": "Acme", "city": "São Paulo" }, "custom_attributes": { "plano": "premium", "origem": "campanha-março" } }, { "name": "Contato 2", "phone_number": "+5511888887777" } ] } Campos por contato | Campo | Obrigatório | Descrição | | --- | --- | --- | | phone_number | Pelo menos 1 dos 3* | Telefone em E.164 com + | | email | Pelo menos 1 dos 3* | E-mail do contato | | identifier | Pelo menos 1 dos 3* | Identificador externo único | | name | Não | Nome do contato | | additional_attributes | Não | Objeto chave-valor. Sobrescrito por completo a cada update | | custom_attributes | Não | Atributos personalizados criados pela conta. Sobrescrito por completo a cada update | *Cada contato deve ter pelo menos um entre phone_number, email ou identifier. Flag upsert | Valor | Comportamento | | --- | --- | | false ou ausente | Apenas cria contatos novos. Se uma chave já existir, a linha falha com 422 | | true | Cria novos e atualiza existentes | Exemplo de requisição curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "upsert": true, "data": [ { "name": "Contato 1", "email": "[email protected]", "phone_number": "+5511999998888" }, { "name": "Contato 2", "phone_number": "+5511888887777" } ] }' Resposta Sucesso (HTTP 201) { "success": true } Erro de validação ou conflito (HTTP 422) { "success": false, "errors": [ { "index": 0, "attributes": { "name": "Contato 1", "email": "[email protected]" }, "errors": ["Email is invalid"] }, { "index": 1, "attributes": { "name": "Contato 2" }, "errors": "Duplicate: Contact with this phone number already exists" } ] } - index indica a posição (0-based) da linha no array data - errors por linha pode ser array de validação ou string única para conflitos de chave (duplicidade) Body vazio (HTTP 400) Retornado quando data é nulo ou array vazio. Cuidados com upsert :::error Risco de perda de dados com upsert: true. Ao atualizar um contato existente via bulk_create com upsert: true, qualquer campo que você não enviar é sobrescrito com null. Exemplo: se um contato tem email e phone_number, e você envia update apenas com phone_number, o campo email é apagado. Se você precisa atualizar apenas alguns campos sem apagar os demais, use o endpoint de update individual: PUT /api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}} ::: Comportamento avançado (opcional) A partir de 30/04/2026, o endpoint aceita parâmetros opcionais no body para customizar o processamento. Todos têm default conservador (paridade com o comportamento anterior) — só envie se quiser habilitar novas funcionalidades. | Parâmetro | Tipo | Default | Efeito | | --- | --- | --- | --- | | api_version | string | "v1" | "v1": paridade com comportamento anterior. "v2": habilita tudo (tags, __DELETE__, lookup de variantes, merge raso JSONB). "v2-safe": subset conservador | | apply_tags | boolean | false | Habilita tags_add e tags_remove por linha | | respect_sentinel | boolean | false | Habilita o valor especial __DELETE__ em campos JSONB e escalares | | merge_jsonb | string | "overwrite" | "overwrite": substitui colunas JSONB inteiras. "shallow": faz merge por chave | | coalesce_nulls | boolean | false | Trata null no payload como "preservar valor existente" | | coerce_blank_jsonb | boolean | false | Trata string vazia ("") em chaves JSONB como remoção da chave | | normalize_lookup | boolean | false | Lookup por variantes ao identificar contatos (especialmente telefones BR mobile-9) | | orphan_guard | boolean | false | Rejeita payloads que orfanizariam um contato existente | :::info Atalho: api_version: "v2" habilita tudo de uma vez — equivale a apply_tags: true + respect_sentinel: true + merge_jsonb: "shallow" + normalize_lookup: true. ::: Combinações que exigem atenção :::warning - merge_jsonb: "shallow" sem respect_sentinel: true — o merge raso preserva chaves não enviadas, mas não tem semântica de remoção. Se seu cliente assumiu que enviar uma chave vazia significa "apagar", a chave fica com o valor antigo. Use respect_sentinel: true em conjunto e envie __DELETE__ para remover explicitamente. - coerce_blank_jsonb: true em payloads com strings vazias intencionais — qualquer string vazia ("") em chaves JSONB será tratada como remoção. Não use se a sua conta tem campos legitimamente vazios. - orphan_guard: true em contas com contatos identifier-only — contatos sem email e sem telefone (apenas identifier) serão rejeitados. ::: tags_add e tags_remove no body Para adicionar e remover tags de forma granular por contato. Ignorados silenciosamente se você não enviar apply_tags: true (ou api_version: "v2"). { "api_version": "v2", "data": [ { "email": "[email protected]", "tags_add": ["vip", "premium"], "tags_remove": ["pending"] } ] } A ordem é determinística: primeiro adiciona, depois remove. Se uma mesma tag aparecer nos dois arrays, a remoção ganha. Removendo chaves JSONB com __DELETE__ Para remover uma chave específica de additional_attributes ou custom_attributes sem mexer nas demais, envie o valor literal "__DELETE__". Requer respect_sentinel: true (ou api_version: "v2"). { "api_version": "v2", "data": [ { "email": "[email protected]", "custom_attributes": { "favorite_color": "__DELETE__" } } ] } Funciona apenas em chaves de primeiro nível dos objetos JSONB. Combine com merge_jsonb: "shallow" (já incluso em api_version: "v2") para preservar as outras chaves. Lookup de variantes de telefone (BR mobile-9) Com normalize_lookup: true (ou api_version: "v2"), o sistema busca contatos existentes por variantes do telefone enviado. { "api_version": "v2", "data": [ { "phone_number": "+5511933334444", "name": "Maria" } ] } Se já existe um contato com +551133334444 (sem o 9), ele é encontrado e atualizado — em vez de criar duplicado. Coalesce de null (preservar campos existentes) Com coalesce_nulls: true, valores null no payload são tratados como "preservar valor existente". Útil quando você gera o payload programaticamente. { "coalesce_nulls": true, "data": [ { "email": "[email protected]", "name": null, "phone_number": "+5511999998888" } ] } Sem coalesce_nulls, o name seria apagado. Com coalesce_nulls: true, o name existente é preservado. Detecção de ambiguidade (AMBIGUOUS_MATCH) Se uma linha contiver dois ou mais campos chave (email, telefone, identifier) que apontem para contatos diferentes já existentes, a linha é rejeitada com erro AMBIGUOUS_MATCH. :::warning Mudança a partir de 30/04/2026: antes, o sistema usava o primeiro match encontrado (precedência email > identifier > telefone) e silenciosamente sobrescrevia dados do outro contato. Agora a linha é rejeitada explicitamente. ::: Diferença entre este endpoint e o Import individual | | Este endpoint (bulk_create) | Import individual (external_import) | | --- | --- | --- | | Quando usar | Importar/atualizar vários contatos | Importar/atualizar 1 contato por chamada | | Formato do body | {"upsert": true, "data": [{...}]} | Objeto JSON simples (flat) | | Upsert | Precisa do flag "upsert": true | Sempre ativo | | Cuidado com null | Campos omitidos são sobrescritos com null | Campos omitidos são preservados | :::error Não misture os formatos. Se enviar um objeto flat (sem data: [...]) para este endpoint, não vai funcionar. ::: Onde encontrar os parâmetros - CLOUDCHAT_DOMAIN — domínio visível na URL do navegador - ACCOUNT_ID — em Configurações da conta - API_TOKEN — em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings Observações - Para importar apenas 1 contato: Como importar um contato individual via API - Para importar via HubSpot workflows: Como importar contatos via HubSpot - Para remover tags em massa: Como remover tags de contatos em massa via API - Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Como enviar mensagem proativa pelo WhatsApp via HubSpot

Quando usar - Você quer disparar mensagens proativas de WhatsApp a partir de ações no HubSpot (mudança de etapa, formulário enviado, propriedade alterada) - Você quer personalizar a mensagem com propriedades do contato no HubSpot (nome, número do pedido, status) - Você está montando fluxos de follow-up, cobrança, onboarding ou atualização de status Pré-requisitos - WhatsApp conectado ao Cloud Chat com inbox_id da caixa correspondente — ver Guia Mestre — Como conectar seu número de WhatsApp ao Cloud Chat O inbox_id é encontrado em https://cloudchat.cloudhumans.com/app/accounts/{{account_id}}/settings/inboxes/{{inbox_id}} - Template aprovado pela Meta cadastrado no Cloud Chat — ver Como criar, editar e excluir templates de WhatsApp no Cloud Chat - API Key do Cloud Chat — ver Como encontrar sua API Key no Cloud Chat - Acesso ao HubSpot para criar workflows com webhook Sobre este tutorial Usando o endpoint de envios proativos do Cloud Chat, é possível iniciar conversas de WhatsApp via webhooks integrados ao HubSpot. Esses webhooks são alimentados com dados do HubSpot, tornando a mensagem contextualmente dinâmica. Para a referência completa do endpoint, consulte: Como enviar mensagem proativa pelo WhatsApp via API. Passo a passo Etapa 1 — Criar o Workflow no HubSpot 1. Na sidebar principal do HubSpot, passe o mouse sobre o ícone de Automações e clique em Fluxos de trabalho 2. Clique em Criar fluxo de trabalho e selecione Do zero 3. Escolha as opções que disparam o gatilho Etapa 2 — Configurar o envio do Webhook 1. Adicione uma ação clicando em + 2. No painel esquerdo, clique em Operações de dados e selecione Envie um webhook 3. Escolha o método POST 4. Preencha a URL do webhook: https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation 5. Configure a Chave de API: clique em Adicionar segredo, preencha Nome do segredo com api_access_token e o Valor do segredo com a API Key do Cloud Chat Etapa 3 — Estruturar o payload Preencha o body da requisição incluindo: - template_name (obrigatório) — valor estático com o nome exato do template aprovado - inbox_id (obrigatório) — valor estático que identifica a inbox - phone_number (obrigatório) — campo dinâmico usando a variável do HubSpot {{contact.phone}} - Variáveis do template — devem ter exatamente o mesmo nome das propriedades enviadas pelo HubSpot :::warning O nome da variável no template precisa ser idêntico ao nome do campo no payload (grafia, maiúsculas/minúsculas e underscores). Caso contrário, a substituição de valores não acontece. ::: Exemplo de payload: Observações - Referência completa do endpoint (parâmetros, comportamento de criação do ticket): Como enviar mensagem proativa pelo WhatsApp via API - Para importar contatos do HubSpot ao Cloud Chat: Como importar contatos via HubSpot - Para evitar bloqueios e cuidar da reputação: Como evitar bloqueios e banimentos no WhatsApp - Documentação oficial do HubSpot sobre webhooks: HubSpot — Workflows with webhooks

Última atualização em May 21, 2026

Como importar contatos via HubSpot

Quando usar - Você quer criar ou atualizar contatos no Cloud Chat automaticamente quando algo acontece no HubSpot - Sua base de contatos é mantida no HubSpot e você quer mantê-la sincronizada com o Cloud Chat - Você está montando workflows que precisam disparar com contatos atualizados no helpdesk Pré-requisitos - API Key do Cloud Chat em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID - Acesso ao HubSpot para criar workflows com webhook Sobre este tutorial Usando o endpoint de importação do Cloud Chat, é possível criar ou atualizar contatos via webhooks integrados ao HubSpot. Para a referência completa do endpoint (campos aceitos, comportamento de upsert e limitações), veja Como importar um contato individual via API. Endpoint usado O webhook do HubSpot deve apontar para: POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import Passo a passo Etapa 1 — Criar o Workflow 1. Na sidebar principal do HubSpot, passe o mouse sobre Automações e clique em Fluxos de trabalho 2. Clique em Criar fluxo de trabalho e selecione Do zero 3. Selecione Baseado em Contato e clique em Próximo Etapa 2 — Configurar a requisição do Webhook 1. Adicione uma ação clicando em + 2. No painel esquerdo, clique em Operações de dados e selecione Envie um webhook 3. Escolha POST 4. Preencha a URL e a chave de API :::info A chave de API deve ser configurada em Gerenciar Segredos do HubSpot. ::: Etapa 3 — Configurar campos do contato Preencha os campos do contato para o disparo: name, phone_number, email, identifier (identificador único) e quaisquer atributos customizados disponíveis. :::warning Pelo menos um entre phone_number, email e identifier é obrigatório para a criação do contato. ::: :::success Se o contato já existir na sua base, ele é atualizado com os campos enviados. Caso contrário, um novo contato é adicionado. ::: Observações - Referência completa do endpoint usado (external_import): Como importar um contato individual via API - Para volumes maiores, use o endpoint em massa: Como importar contatos em massa via API - Para enviar mensagens proativas via HubSpot: Como enviar mensagem proativa pelo WhatsApp via HubSpot - Documentação HubSpot sobre webhooks em workflows: HubSpot — Webhooks com Workflows

Última atualização em May 21, 2026

Como importar um contato individual via API

Quando usar - Você precisa criar ou atualizar um contato por vez no Cloud Chat via API - Você quer um endpoint mais simples e que preserva campos não enviados (não sobrescreve com null) - Você está integrando com um sistema externo que emite eventos individuais (ex: novo cadastro) Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID - Pelo menos um identificador entre phone_number, email ou identifier :::info Quer importar vários contatos de uma vez? Use o endpoint de Como importar contatos em massa via API. Os dois endpoints têm formatos de body diferentes — não misture. ::: Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição O body é um objeto JSON simples (flat), sem arrays. Pelo menos um dos campos phone_number, identifier ou email deve estar presente. { "phone_number": "+5599123456789", "identifier": "CUSTOM_ID", "email": "[email protected]", "name": "Nome do Contato", "company_name": "Empresa X", "tags": "tag1, tag2, tag3", "ATRIBUTO_CUSTOMIZADO": "valor" } Campos disponíveis | Campo | Obrigatório | Descrição | | --- | --- | --- | | phone_number | Pelo menos 1 dos 3* | Telefone em E.164 com + (ex: +5511999998888) | | email | Pelo menos 1 dos 3* | E-mail do contato | | identifier | Pelo menos 1 dos 3* | Identificador externo único | | name | Não | Nome do contato | | company_name | Não | Nome da empresa | | tags | Não | Tags separadas por vírgula | | Campos customizados | Não | Use a chave do atributo customizado cadastrado no Cloud Chat | *Pelo menos um entre phone_number, email ou identifier deve ser informado. Exemplo de requisição curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "phone_number": "+5599123456789", "name": "Nome do Contato", "email": "[email protected]", "company_name": "Empresa X", "tags": "tag1, tag2" }' Comportamento de criação e atualização (upsert) Este endpoint cria ou atualiza automaticamente. Para decidir se o contato já existe, o sistema busca na seguinte ordem de prioridade: 1. Primeiro busca por email 2. Se não enviou email, busca por identifier 3. Se não enviou identifier, busca por phone_number :::warning A busca usa apenas o primeiro campo disponível na ordem acima. Ela não tenta os campos seguintes se o primeiro não encontrar. ::: Lookup de variantes (BR mobile-9) :::warning Este endpoint individual faz lookup exato por phone_number. Se você precisa criar/atualizar contatos com lookup de variantes (ex.: você envia +5511933334444 e o contato existe como +551133334444), use o endpoint de Import em massa com api_version: "v2" (ou normalize_lookup: true). Mudança a partir de 30/04/2026: a busca por variantes está disponível apenas no caminho bulk. ::: O que isso significa na prática Se você quer atualizar um contato que já existe pelo telefone (ex: adicionar um e-mail), e envia: { "phone_number": "+5511999998888", "email": "[email protected]" } O sistema busca pelo email primeiro (porque o campo email está presente). Se [email protected] não existe em nenhum contato, ele não tenta buscar pelo phone_number — vai tentar criar um contato novo, que pode falhar silenciosamente por conflito de telefone. Como fazer corretamente Para atualizar um contato existente por telefone, faça o flow em duas etapas: Passo 1 — Localize o contato (se precisar do ID): curl -X GET \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/search?q=+5511999998888' \ --header 'api_access_token: SEU_TOKEN' Passo 2 — Atualize via endpoint de update individual: curl -X PUT \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"email": "[email protected]"}' Resposta | Status | Significado | | --- | --- | | 204 No Content | Requisição processada (sem corpo de resposta) | | 422 Unprocessable Entity | Erro de validação | :::info O status 204 indica que a requisição foi recebida, mas não retorna o contato criado/atualizado. Se precisar confirmar a alteração, faça uma consulta após a chamada. ::: Diferença entre este endpoint e o Import em massa | | Este endpoint (external_import) | Import em massa (bulk_create) | | --- | --- | --- | | Quando usar | Importar/atualizar 1 contato por chamada | Importar/atualizar vários contatos | | Formato do body | Objeto JSON simples (flat) | {"upsert": true, "data": [{...}]} | | Upsert | Sempre ativo (automático) | Precisa do flag "upsert": true | | Resposta | 204 No Content (sem corpo) | 201 Created com resultado | :::error Não misture os formatos. Se enviar {"upsert": true, "data": [...]} para este endpoint, não vai funcionar. Esse formato é exclusivo do endpoint de import em massa. ::: Onde encontrar os parâmetros - CLOUDCHAT_DOMAIN — domínio visível na URL do navegador - ACCOUNT_ID — em Configurações da conta - API_TOKEN — em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings Observações - Para volumes grandes (muitos contatos): Como importar contatos em massa via API - Para integração com workflows do HubSpot: Como importar contatos via HubSpot - Para visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Como remover tags de contatos em massa via API

Quando usar - Você precisa remover tags de múltiplos contatos de uma vez sem precisar abrir cada contato manualmente - Você está rodando uma rotina de limpeza ou correção de tags em base de contatos - Você quer manter a base organizada após uma campanha ou migração Pré-requisitos - API Key (API_TOKEN) em mãos — ver Como encontrar sua API Key no Cloud Chat - ACCOUNT_ID da conta - Cada contato precisa ter ao menos um identificador entre identifier, email ou phone_number Endpoint DELETE https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/contacts/delete_tags Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição O body deve conter um único campo contacts, que é um array de objetos. Cada objeto representa um contato e deve conter: | Campo | Obrigatório | Descrição | | --- | --- | --- | | identifier | Pelo menos 1 dos 3* | Identificador único do contato | | email | Pelo menos 1 dos 3* | E-mail do contato | | phone_number | Pelo menos 1 dos 3* | Telefone do contato | | tags | Sim | Array com as tags a remover (pelo nome) | *Pelo menos um identificador deve ser informado para localizar o contato. Exemplo de requisição curl --request DELETE \ --url 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/contacts/delete_tags' \ --header 'api_access_token: API_TOKEN' \ --header 'content-type: application/json' \ --data '{ "contacts": [ { "identifier": 123, "tags": ["tag-de-massa-1","tag-de-massa-2"] }, { "email": "[email protected]", "tags": ["tag-de-massa-2","tag-de-massa-3"] }, { "phone_number": 5551000000000, "tags": ["tag-de-massa-1","tag-de-massa-3"] } ] }' Como o contato é localizado O sistema busca o contato nesta ordem: 1. identifier (primeiro) 2. email (segundo) 3. phone_number (terceiro) :::info Diferente do endpoint de import de contato (que prioriza email), aqui o identifier tem prioridade. ::: Sobre phone_number :::info Se enviado sem o prefixo +, o sistema adiciona automaticamente (ex: 5511999998888 → +5511999998888). ::: Observações - Para criar ou atualizar contatos (incluindo gerenciar tags com tags_add e tags_remove granulares): Como importar contatos em massa via API - Para atualizar atributos customizados (não tags) em conversas: Como atualizar atributos customizados em conversas via API - Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Como atualizar atributos customizados em conversas via API

Quando usar - Você precisa atualizar atributos customizados (Categoria, Motivo, Tier, etc.) de uma conversa via API - Você está integrando com outro sistema que precisa enviar metadata para a conversa do Cloud Chat - Você quer remover atributos específicos sem afetar os demais Pré-requisitos - API Key (API_TOKEN) — ver Como encontrar sua API Key no Cloud Chat - ACCOUNT_ID e CONVERSATION_ID (ver nota abaixo) - Atributos customizados já cadastrados na conta (configurados pelo administrador) :::warning CONVERSATION_ID vs display_id — este endpoint usa o display_id (o número visível na interface do Cloud Chat) como identificador da conversa na URL, não o ID interno. ::: Endpoint PUT https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/custom_attributes Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição A requisição deve conter um único campo, custom_attributes, com os atributos a atualizar: { "custom_attributes": { "to_be_updated": "new_value", "to_be_removed": null } } :::info O conversation_id da conversa não vai no body — ele é passado como parâmetro na URL. ::: Exemplo de requisição curl --request PUT \ --url 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes' \ --header 'api_access_token: API_TOKEN' \ --header 'content-type: application/json' \ --data '{ "custom_attributes": { "to_be_updated": "new_value", "to_be_removed": null } }' Tipos de atributos suportados Os atributos customizados têm um tipo definido na configuração — respeite o tipo ao atualizar via API. | Tipo | Requisitos | | --- | --- | | Texto | Valor String | | Número | Apenas dígitos. Não pode conter caracteres alfabéticos ou especiais | | Link | URL válida (http/https) que termina em domínio válido (.com, .net, etc.) | | Data | Formato ISO 8601 (YYYY-MM-DDTHH:MM:SS.sssZ). Ex: "2025-01-01T12:00:00.000Z" | | Lista | String que deve estar presente na lista de opções definidas no atributo | | Multi-list | Array de strings. Cada valor deve existir nas opções pré-definidas. Ex: ["opção1","opção2"] | | Checkbox | "true"/"false" (string) ou true/false (booleano) | Como remover um atributo :::info Para remover um valor atribuído a um atributo customizado, envie null ou string vazia (""). O sistema remove o atributo do objeto custom_attributes. ::: Tratamento de erros | Erro | Código | Significado | | --- | --- | --- | | Conversation not found | 404 | A conversa não foi encontrada | | Invalid attributes | 422 | Body incorreto | | Atributo inexistente | — | O atributo não está cadastrado na conta | | Tipo errado | — | Mensagens como "number_attr must contain only numeric digits" ou "date_attr must be in ISO8601 format" | Cuidado: PUT (merge) vs POST (replace) Existem dois endpoints para alterar custom attributes — escolha o correto: | Método | Comportamento | Quando usar | | --- | --- | --- | | PUT .../custom_attributes (este) | Merge: atualiza os campos enviados e preserva os demais | Recomendado para a maioria dos casos | | POST .../conversations/{ID}/custom_attributes | Replace: substitui todos os custom attributes pelo objeto enviado | Use com cuidado — campos não enviados são apagados | :::error Sempre prefira PUT para evitar perda de dados acidental. ::: Observações - Para criar atributos customizados (administrador): Gestão de conversas no Cloud Chat: ferramentas e funcionalidades - Para criar macros que preenchem atributos automaticamente (sem precisar da API): Como usar macros com atributos customizados no Cloud Chat - Para outras ações em tickets via API (status, prioridade, time): 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

Última atualização em May 21, 2026

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 :::warning 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 :::info 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 :::warning - 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: | Campo | Tipo | Descrição | Dado Possivelmente Sensível | | --- | --- | --- | --- | | ticketId | Inteiro | ID interno do ticket | Não | | displayTicketId | Inteiro | ID exibido ao usuário no Cloud Chat — visível na URL e na busca por filtros | Não | | inboxId | Inteiro | ID da caixa de entrada | Não | | accountId | Inteiro | ID da conta | Não | | accountName | Texto | Nome da conta | Não | | ticketStatus | Texto | Status do ticket: open (Aberto), resolved (Resolvido), pending (Pendente), snoozed (Adiado) | Não | | teamName | Texto | Nome do time responsável | Não | | ticketPriorityName | Texto | Prioridade: low, medium, high, urgent | Não | | ticketType | Texto | Tipo do ticket (primeira tag associada) | Não | | inboxName | Texto | Nome da caixa de entrada | Não | | ticketTitle | Texto | Título do ticket — pode conter nome ou telefone do contato | Sim | | channel | Texto | Canal de comunicação (ex: Whatsapp) | Não | | tags | Texto | Tags do ticket separadas por vírgula | Não | | createdAt | Timestamp | Data e hora de criação do ticket | Não | | firstReplyAt | Timestamp | Data e hora da primeira resposta | Não | | firstReplyTime | Decimal | Tempo até a primeira resposta (em minutos) | Não | | resolvedAt | Timestamp | Data e hora de resolução | Não | | totalResolutionTimeMin | Decimal | Tempo total de resolução (em minutos) | Não | | agentId | Inteiro | ID do agente responsável | Não | | ticketOwner | Texto | Nome do agente responsável | Sim | | ticketOwnerEmail | Texto | E-mail do agente responsável | Sim | | contactId | Inteiro | ID do contato | Não | | contactName | Texto | Nome do contato | Sim | | contactEmail | Texto | E-mail do contato | Sim | | contactPhone | Texto | Telefone do contato | Sim | | campaignId | Inteiro | ID da campanha que originou o ticket, se aplicável | Não | | proactivelyInitiated | Booleano | Indica se o ticket foi iniciado proativamente | Não | :::warning 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: | Campo | Tipo | Descrição | Dado Possivelmente Sensível | | --- | --- | --- | --- | | ticketLink | Texto | URL direta para o ticket no Cloud Chat | Não | | agentOnResolutionId | Inteiro | ID do agente humano que resolveu o ticket | Não | | agentOnResolutionName | Texto | Nome do agente humano que resolveu | Sim | | agentOnResolutionEmail | Texto | E-mail do agente humano que resolveu | Sim | | firstAgentReplyId | Inteiro | ID do primeiro agente humano que respondeu | Não | | firstAgentReplyName | Texto | Nome do primeiro agente humano que respondeu | Sim | | firstAgentReplyEmail | Texto | E-mail do primeiro agente humano que respondeu | Sim | | firstAgentAssignmentTime | Timestamp | Data e hora em que o ticket foi atribuído ao primeiro agente | Não | | firstAgentFirstReplyTime | Timestamp | Data e hora da primeira resposta do agente | Não | | firstReplierAgentAssignmentTime | Timestamp | Data e hora de atribuição do agente que respondeu primeiro | Não | | firstReplierAgentFirstReplyTime | Timestamp | Timestamp da primeira resposta do agente que respondeu primeiro | Não | | firstAgentReplyTimeMin | Decimal | Tempo entre atribuição e primeira resposta do agente (min) | Não | | firstAgentResolutionTimeMin | Decimal | Tempo entre atribuição e resolução do ticket (min) | Não | | csatScore | Numérico | Nota de satisfação (CSAT) atribuída pelo cliente | Não | | csatFeedback | Texto | Comentário textual deixado pelo cliente na pesquisa CSAT | Sim | | contactCustomFields | JSON | Campos customizados do contato — podem conter dados pessoais | Sim | | conversationCustomFields | JSON | Campos customizados da conversa — podem conter dados pessoais | Sim | | conversationAdditionalFields | JSON | Metadados adicionais da conversa — podem conter dados pessoais | Sim | 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": "{}" } ] :::info - firstAgentReplyTimeMin — tempo entre firstAgentAssignmentTime e firstAgentFirstReplyTime - firstAgentResolutionTimeMin — tempo entre firstAgentAssignmentTime e resolvedAt ::: 3. TICKET_SUMMARY Retorna a transcrição completa da conversa do ticket. Campos retornados: | Campo | Tipo | Descrição | Dado Possivelmente Sensível | | --- | --- | --- | --- | | ticketId | Inteiro | ID interno do ticket | Não | | displayTicketId | Inteiro | ID exibido ao usuário no Cloud Chat — visível na URL e na busca por filtros | Não | | ticketLink | Texto | URL direta para o ticket no Cloud Chat | Não | | summary | Texto | Transcrição completa da conversa entre cliente e atendente | Sim | [ { "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: | Campo | Tipo | Descrição | Dado Possivelmente Sensível | | --- | --- | --- | --- | | id | Inteiro | ID único do evento de entrega | Não | | campaignId | Inteiro | ID da campanha | Não | | campaignTitle | Texto | Título da campanha | Não | | audience | Texto | Audiência/lista utilizada na campanha | Não | | contactId | Inteiro | ID do contato destinatário | Não | | contactName | Texto | Nome do contato destinatário | Sim | | contactEmail | Texto | E-mail do contato destinatário | Sim | | contactPhoneNumber | Texto | Telefone do contato destinatário | Sim | | ticketId | Inteiro | ID do ticket gerado pelo disparo, se houver | Não | | displayTicketId | Texto | ID exibido ao usuário no Cloud Chat — visível na URL e na busca por filtros | Não | | messageSent | Booleano | Flag que indica se a mensagem foi enviada à API do WhatsApp (Meta) | Não | | sentAt | Timestamp | Data e hora do envio | Não | | messageReceived | Booleano | Flag que indica se a mensagem foi entregue ao dispositivo do contato | Não | | receivedAt | Timestamp | Data e hora da entrega | Não | | messageRead | Booleano | Flag que indica se a mensagem foi lida (depende das configurações de privacidade do contato) | Não | | readAt | Timestamp | Data e hora da leitura | Não | | messageReplied | Booleano | Flag que indica se a mensagem foi respondida | Não | | repliedAt | Timestamp | Data e hora da primeira resposta | Não | | error | Texto | Erro de entrega: número inválido, sem WhatsApp, bloqueio, etc. | Não | | createdAt | Timestamp | Data e hora de criação do registro | Não | | updatedAt | Timestamp | Data e hora da última atualização | Não | 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: | Campo | Tipo | Descrição | Dado Possivelmente Sensível | | --- | --- | --- | --- | | id | Inteiro | ID único do evento de entrega | Não | | contactId | Inteiro | ID do contato destinatário | Não | | contactName | Texto | Nome do contato destinatário | Sim | | contactEmail | Texto | E-mail do contato destinatário | Sim | | contactPhoneNumber | Texto | Telefone do contato destinatário | Sim | | ticketId | Inteiro | ID do ticket gerado pelo disparo, se houver | Não | | displayTicketId | Texto | ID exibido ao usuário no Cloud Chat — visível na URL e na busca por filtros | Não | | messageSent | Booleano | Flag que indica se a mensagem foi enviada à API do WhatsApp (Meta) | Não | | sentAt | Timestamp | Data e hora do envio | Não | | messageReceived | Booleano | Flag que indica se a mensagem foi entregue ao dispositivo do contato | Não | | receivedAt | Timestamp | Data e hora da entrega | Não | | messageRead | Booleano | Flag que indica se a mensagem foi lida (depende das configurações de privacidade do contato) | Não | | readAt | Timestamp | Data e hora da leitura | Não | | messageReplied | Booleano | Flag que indica se a mensagem foi respondida | Não | | repliedAt | Timestamp | Data e hora da primeira resposta | Não | | error | Texto | Erro de entrega: número inválido, sem WhatsApp, bloqueio, etc. | Não | | createdAt | Timestamp | Data e hora de criação do registro | Não | | updatedAt | Timestamp | Data e hora da última atualização | Não | 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

Última atualização em Jun 25, 2026

Como importar histórico de tickets via API

Quando usar - Você concluiu a migração de outro helpdesk para o Cloud Chat e quer importar o histórico de tickets - Você precisa preservar metadados (ID externo, prioridade, fila de origem) para auditoria ou referência cruzada - Você está montando uma rotina de importação programática para grandes volumes Pré-requisitos - Migração concluída e inbox criada e ativa no Cloud Chat - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID - Desenvolvedor disponível para executar as requisições e estruturar os dados :::warning A importação de tickets via API só pode ser feita após a conclusão da migração e com a inbox já ativa no Cloud Chat. O time da Cloud Humans não realiza a importação para o cliente — apenas disponibiliza a documentação técnica e orientações para implementação. ::: Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Exemplo de requisição curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import' \ --header 'content-type: application/json' \ --header 'api_access_token: API_TOKEN' \ --data '{ "conversations_data": [ { "contact": { "email": "[email protected]", "name": "John Doe", "phone_number": "+1234567890", "identifier": "external_customer_id" }, "custom_attributes": { "external_helpdesk_id": "ZD-12345", "priority": "high" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "My printer is on fire! The smoke is very colorful and I need immediate help.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false } ] } ] }' Corpo da requisição Estrutura do conversations_data Lista de objetos com os dados dos tickets. Cada objeto tem: | Campo | Obrigatório | Descrição | | --- | --- | --- | | created_at | Sim | Data de criação do ticket. Formato ISO 8601 | | updated_at | Sim | Data da última atualização. Formato ISO 8601 | | contact | Sim | Objeto com dados do contato (ver abaixo) | | custom_attributes | Não | Pares chave-valor para metadata (ID externo, prioridade, fila) | | messages | Sim | Lista de mensagens do ticket | Objeto contact | Campo | Obrigatório | Descrição | | --- | --- | --- | | identifier | Sim | Identificador único do contato no helpdesk de origem | | email | Não | E-mail válido | | name | Não | Nome do contato | | phone_number | Não | Telefone em E.164 (ex: +5599988888888) | custom_attributes (recomendado) Pares chave-valor para preservar metadados do ticket de origem (ex: external_helpdesk_id, prioridade, fila). Aceita qualquer chave string. Os valores ficam disponíveis na conversa via API (GET /conversations/:id) e na UI no painel direito. :::info Dica: para que o atributo apareça com label/tipo formatado no painel, defina-o previamente em Settings → Custom Attributes (escopo: Conversation). Sem isso, o valor é gravado no banco e fica acessível via API, mas não é renderizado como campo nativo na UI. ::: Objetos messages | Campo | Obrigatório | Descrição | | --- | --- | --- | | content | Sim | Corpo da mensagem | | message_type | Sim | "incoming" (mensagem do contato) ou "outgoing" (mensagem do agente). Para notas internas, use "activity" com "private": true | | created_at | Sim | Data de envio. Formato ISO 8601 | | private | Sim | true para mensagem privada (interna), false para pública | Exemplo completo com múltiplas mensagens { "conversations_data": [ { "contact": { "email": "[email protected]", "name": "John Doe", "phone_number": "+1234567890", "identifier": "user_6782902" }, "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high", "source_queue": "tier-2-support" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "My printer is on fire!", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false }, { "content": "Thanks for contacting us. Let me help.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false }, { "content": "Internal note: Customer has premium support, prioritize this case.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true }, { "content": "**Status Update**: Escalated to Level 2 Support", "message_type": "activity", "created_at": "2024-01-15T12:00:00Z", "private": true } ] } ] } Regras importantes :::warning - Identificador único — identifier do contato deve ser único. Dois contatos com dados divergentes mas mesmo identificador serão tratados como um único contato - Limites por requisição — cada requisição aceita no máximo 10.000 tickets ou 15 MB. Para volumes maiores, particione e faça múltiplas requisições ::: Onde encontrar os parâmetros CLOUDCHAT_DOMAIN Parte da URL ao fazer login na sua conta: ACCOUNT_ID Em Configurações da conta: API_TOKEN Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings: INBOX_ID ID da caixa que receberá os tickets. Pode ser obtido na URL da aba de configurações da inbox: Observações - Para criar tickets novos via API (não importação histórica): Como criar tickets via API no Cloud Chat - Para importar contatos antes ou junto com a importação de tickets: Como importar contatos em massa via API - Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Como criar tickets via API no Cloud Chat

Quando usar - Você quer iniciar uma conversa no Cloud Chat sem que o cliente tenha enviado uma mensagem por canal ativo - Você precisa centralizar comunicações que vêm de outras fontes (telefonia, formulário, CRM, ERP) - Você quer associar atributos customizados ao ticket no momento da criação Pré-requisitos - API Key válido (do usuário ou agent bot) com acesso à conta — ver Como encontrar sua API Key no Cloud Chat - ACCOUNT_ID e INBOX_ID da mesma conta - Para alguns canais, a Inbox precisa ter "Criar conversa via API" habilitado - Para canal e-mail: vínculo ContactInbox entre o contato e a Inbox com source_id correto Sobre este artigo Esta API permite criar um ticket no Cloud Chat a partir de qualquer sistema externo — sistema de telefonia (ligação recebida), formulário web, integração com CRM/ERP. Você pode: - Criar ticket com status open, pending ou resolved - Associar a um contato via e-mail, telefone ou identificador - Incluir uma mensagem inicial (incoming ou outgoing) - Definir atributos customizados no momento da criação Exemplos de uso - Recebeu uma ligação fora do Cloud Chat? → Gere um ticket com o resumo da chamada - Alguém preencheu um formulário? → Crie o ticket automaticamente e inicie a tratativa por e-mail - Quer centralizar comunicações de outras fontes? → Use esta API como ponto de entrada Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição { "inbox_id": "1", "contact_identifier": "id_123", "contact_email": "[email protected]", "contact_phone_number": "+12345", "message": { "content": "Olá, acabei de preencher o formulário no site e preciso de ajuda.", "message_type": "incoming" }, "status": "open", "private": false, "custom_attributes": { "example1": "valueXPTO" }, "additional_attributes": { "mail_subject": "Protocolo de atendimento ABCD" }, "assignee_id": "1" } Como definir source_id por tipo de canal - Canal E-mail (Channel::Email) — o e-mail do contato (ex: [email protected]) - Canal Telefone (Twilio/WhatsApp) — número em E.164 (ex: +5511999998888) - Canal Website (Channel::WebWidget) — identificador gerado pelo Chatwoot (obtido via webhooks/contactable inboxes) - Canal API (Channel::Api) — qualquer string estável única (ex: SHEET-<sheetId>-ROW-<row>, TICKET-12345) Explicação dos campos inbox_id Identificador da Inbox, obtido na URL ao acessar a configuração da caixa de entrada. assignee_id (opcional) Identificador do agente que será atribuído na criação. Identificação do contato Envie um dos três abaixo: - contact_identifier — identificador único do contato - contact_email — e-mail do contato - contact_phone_number — telefone do contato message - content — conteúdo da mensagem - message_type: - "incoming" — mensagem vinda do cliente - "outgoing" — enviada pelo agente - "activity" — nota interna - private — false para visível ao cliente, true para nota interna additional_attributes.mail_subject (opcional) Para canal de e-mail, customiza o assunto enviado ao contato quando a conversa se inicia. custom_attributes (opcional) Adicione qualquer atributo customizado de conversa já existente na sua configuração. Para criar atributos: Criando campos customizados de contatos e conversas. Status do ticket criado :::info O ticket nasce com status open por padrão (a menos que status seja informado), o que o torna visível e pronto para atendimento imediato na Inbox especificada. ::: Como testar 1. Pegue seu api_access_token no painel de configurações 2. Copie o ACCOUNT_ID, INBOX_ID e CLOUDCHAT_DOMAIN (ver Como importar histórico de tickets via API seção de parâmetros) 3. Envie a requisição via Postman ou script 4. Verifique no Cloud Chat se o ticket apareceu na Inbox correta com as informações completas Erros comuns :::error Uso incorreto de identificadores únicos. Os campos identifier, phone_number e email são atributos únicos do contato. Não devem ser fixados em requisições de criação de tickets. Como a request usa upsert, fixar esses campos resulta em um único contato sendo atualizado a cada chamada — todas as conversas vinculadas a ele. ::: :::warning Criação de ticket não cria contato. A criação manual de tickets via API não gera novos contatos — o sistema usa apenas contatos já existentes. Se o contato não existir, é necessário criá-lo previamente via Como importar um contato individual via API. ::: Fluxo exemplo: criar ticket de e-mail com mensagem do usuário Etapa 1 — Garantir/obter o contato Buscar por chave (e-mail/telefone/identificador): GET /api/v1/accounts/{account_id}/contacts/search?q={chave} Criar contato caso não exista: POST /api/v1/accounts/{account_id}/contacts Etapa 2 — Vincular o contato à Inbox (ContactInbox) POST /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes Body: { "inbox_id": "INBOX_ID", "source_id": "<conforme canal>" } Etapa 3 — Criar a conversa (sem mensagem inicial) POST /api/v1/accounts/{account_id}/conversations Body mínimo: { "source_id": "<...>", "inbox_id": "INBOX_ID", "status": "open" } Etapa 4 — Postar mensagem como cliente (incoming) POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages Body: { "content": "Mensagem do cliente", "message_type": "incoming" } Etapa 5 (opcional) — Responder como agente (outgoing) Mesmo endpoint de mensagens, com message_type: "outgoing". Para canal e-mail, content_attributes aceita to_emails, cc_emails, bcc_emails conforme sua configuração. Exemplo prático: integração Google Forms via Apps Script function criarConversaEMensagemIncoming() { var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Form_Responses"); var lastRow = sheet.getLastRow(); var nome = sheet.getRange(lastRow, 3).getValue(); var email = sheet.getRange(lastRow, 4).getValue(); var descricao = sheet.getRange(lastRow, 5).getValue(); var assunto = sheet.getRange(lastRow, 2).getValue(); var accountId = ACCOUNT_ID; var inboxId = INBOX_ID; var base = "https://CLOUDCHAT_DOMAIN/api/v1/accounts/" + accountId; var token = "SEU_API_ACCESS_TOKEN"; // 1) Buscar/criar contato var resSearch = UrlFetchApp.fetch(base + "/contacts/search?q=" + encodeURIComponent(email), { method: "get", headers: { api_access_token: token, Accept: "application/json" }, muteHttpExceptions: true }); var s = JSON.parse(resSearch.getContentText()); var contactId = (s && s.payload && s.payload[0] && s.payload[0].id) ? s.payload[0].id : null; if (!contactId) { var resCreate = UrlFetchApp.fetch(base + "/contacts", { method: "post", contentType: "application/json", payload: JSON.stringify({ name: nome, email: email }), headers: { api_access_token: token, Accept: "application/json" }, muteHttpExceptions: true }); var c = JSON.parse(resCreate.getContentText()); contactId = (c && c.payload && c.payload.contact && c.payload.contact.id) ? c.payload.contact.id : null; } // 2) Vincular ContactInbox UrlFetchApp.fetch(base + "/contacts/" + contactId + "/contact_inboxes", { method: "post", contentType: "application/json", payload: JSON.stringify({ inbox_id: inboxId, source_id: String(email) }), headers: { api_access_token: token, Accept: "application/json" }, muteHttpExceptions: true }); // 3) Criar conversa var resConv = UrlFetchApp.fetch(base + "/conversations", { method: "post", contentType: "application/json", payload: JSON.stringify({ source_id: String(email), inbox_id: inboxId, status: "open", custom_attributes: { subject: assunto, requester_name: nome, requester_email: email } }), headers: { api_access_token: token, Accept: "application/json" }, muteHttpExceptions: true }); var conv = JSON.parse(resConv.getContentText()); var conversationId = conv && conv.id ? conv.id : null; // 4) Postar mensagem como cliente (incoming) UrlFetchApp.fetch(base + "/conversations/" + conversationId + "/messages", { method: "post", contentType: "application/json", payload: JSON.stringify({ content: "Assunto: " + assunto + "\n" + "Solicitante: " + nome + " <" + email + ">\n\n" + descricao, message_type: "incoming" }), headers: { api_access_token: token, Accept: "application/json" }, muteHttpExceptions: true }); sheet.getRange(lastRow, 7).setValue(conversationId); } Observações - Para importar histórico de tickets de outro helpdesk: Como importar histórico de tickets via API - Para alterar status, prioridade ou time depois da criação: Como atualizar e agir em tickets via API - Para atualizar atributos customizados depois da criação: Como atualizar atributos customizados em conversas via API - Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Quando usar - Você está prestes a usar uma API do Cloud Chat e quer escolher a categoria certa antes de copiar endpoints - Você não sabe a diferença entre extração histórica, consulta em tempo real e ação em produção - Você quer evitar usar a API errada e gerar efeitos colaterais inesperados Sobre este guia Este guia existe para responder uma única pergunta: Qual API do Cloud Chat eu devo usar para o que eu quero fazer? Antes de copiar qualquer endpoint ou escrever código, leia esta página. Ela evita confusão, uso incorreto de APIs e impactos não desejados em produção. Existem 3 categorias de APIs no Cloud Chat As APIs do Cloud Chat não são todas iguais. Elas se dividem em três categorias, cada uma com objetivo claro. Extração de dados Para análise histórica e relatórios. - Exportação em lote (batch) - Uso típico: BI, auditoria, dashboards - Não alteram dados - Ideais para jobs agendados Consulta em tempo real Para ler dados atuais do sistema. - Buscar contatos - Listar tickets - Ler mensagens - Não alteram dados - Usadas em integrações e automações em tempo real Atualização e ação :::error Estas APIs alteram dados reais em produção. ::: - Resolver tickets - Alterar status, prioridade ou time - Criar mensagens em tickets - Podem impactar operação, SLA e métricas - Algumas rotas são experimentais ou exigem flag ativa Quando usar APIs de Extração de Dados Use APIs de extração quando você quer: - Criar relatórios - Alimentar ferramentas de BI - Fazer auditorias - Analisar grandes períodos de tempo - Exportar muitos tickets de uma vez Essas APIs: - Funcionam em lote - Têm limite de intervalo por requisição - Não devem ser usadas para lógica de aplicação em tempo real Documentação específica: Como extrair dados em lote via API (Data Extract API) Quando usar APIs de Consulta em Tempo Real Use APIs de consulta quando você precisa responder perguntas agora, como: - "Esse contato já existe?" - "Quais tickets esse cliente tem?" - "Qual é o status atual desse ticket?" - "Quais mensagens foram trocadas nessa conversa?" Essas APIs: - São somente leitura (GET) - Operam diretamente na base de produção - Não substituem a API de extração Documentação específica: Como consultar contatos, tickets e mensagens em tempo real via API Quando usar APIs de Atualização e Ação :::warning Essas APIs modificam dados reais no Cloud Chat. ::: Use quando você quer: - Resolver um ticket via integração - Atualizar prioridade ou time responsável - Criar mensagens automaticamente - Sincronizar ações de outro sistema com o Cloud Chat Essas APIs: - Executam ações em produção - Podem afetar operação e métricas - Devem ser usadas com cuidado e validação Documentação específica: Como atualizar e agir em tickets via API Regra prática para escolher a API certa Pergunte sempre: - Quero analisar dados históricos? → Use Data Extract API - Quero apenas ler dados atuais? → Use APIs de Consulta em Tempo Real - Quero mudar algo no sistema? → Use APIs de Atualização e Ação :::info Se ainda estiver em dúvida, não avance. Usar a API errada pode gerar efeitos colaterais inesperados. ::: Níveis de cuidado | Categoria | Risco | | --- | --- | | Extração de dados | Baixo | | Consulta em tempo real | Médio | | Atualização / ação | Alto | Quanto mais você se aproxima de ações de escrita, mais atenção e testes são necessários. Erros comuns que este guia ajuda a evitar :::error - Usar API de extração para algo que precisa ser em tempo real - Usar API de escrita achando que é apenas consulta - Misturar lógica de aplicação com exportação de dados - Alterar tickets sem entender o impacto operacional ::: Observações Próximos passos — escolha a documentação certa para o seu caso: - Data Extract API — Extração de dados em lote - APIs de Consulta em Tempo Real (Contacts, Tickets, Messages) - APIs de Atualização e Ação em Tickets Outras APIs para ações específicas: - Como criar tickets via API - Como importar contatos em massa via API - Como importar histórico de tickets via API - Como encontrar sua API Key no Cloud Chat Este guia deve sempre ser lido antes das FAQs técnicas acima.

Última atualização em May 21, 2026

Como consultar contatos, tickets e mensagens em tempo real via API

Quando usar - Você quer ler dados atuais do Cloud Chat sem alterar nada (consultar contato, ver tickets de um cliente, ler mensagens de uma conversa) - Você está integrando o Cloud Chat a outro sistema (CRM, portal interno) que precisa exibir dados ao vivo - Você quer evitar duplicação de contatos antes de criar um ticket Pré-requisitos - API Key de administrador ou supervisor — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID :::info Se você ainda não sabe qual tipo de API usar, comece pelo Guia Mestre — Como acessar e operar dados do Cloud Chat via API. Esta página cobre apenas leitura em tempo real. ::: Sobre este artigo As APIs de Consulta em Tempo Real permitem ler dados atuais do Cloud Chat, diretamente da base de produção, sem alterar nada. São ideais para integrações, automações e telas internas que precisam responder perguntas como: - "Esse contato já existe?" - "Quais tickets esse cliente tem?" - "Qual é o status atual desse ticket?" - "Quais mensagens foram trocadas nessa conversa?" Sobre o namespace /api/client/ :::info Os endpoints desta página usam /api/client/accounts/... em vez do /api/v1/accounts/... usado em outras APIs. Ambos usam o mesmo api_access_token para autenticação. O namespace /api/client/ oferece endpoints simplificados de leitura — são mais diretos para consultas pontuais. Para operações de escrita (criar, atualizar, deletar), use o namespace /api/v1/. ::: Para que essas APIs servem Use quando você precisa: - Ler dados agora - Integrar dados do Cloud Chat a outro sistema - Exibir informações em uma aplicação - Tomar decisões baseadas no estado atual do atendimento Para que não servem :::warning Não use essas APIs para: - Gerar relatórios → use Data Extract API - Exportar grandes volumes de dados → use Data Extract API - Analisar períodos longos de tempo → use Data Extract API - Criar ou atualizar tickets → use APIs de Atualização e Ação em Tickets - Inserir mensagens → use APIs de Atualização e Ação em Tickets ::: Autenticação Todos os endpoints exigem: - {CLOUDCHAT_DOMAIN} — domínio da sua conta (ex: cloudchat.cloudhumans.com) - {ACCOUNT_ID} — ID da conta - api_access_token — para os endpoints /api/client/ (seções 1, 2 e 3), o token deve ser de administrador — tokens de supervisor ou agente recebem 403 Forbidden. A busca por texto livre (seção 1b, namespace /api/v1/) aceita token de qualquer perfil de agente 1. Buscar contato por e-mail ou telefone Quando usar - Antes de criar um ticket (descobrir se o contato já existe) - Para associar dados externos a um contato - Para evitar duplicação Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts?email=EMAIL&phone_number=PHONE Regras - Pelo menos um dos parâmetros (email ou phone_number) é obrigatório - Se ambos forem enviados, a API tenta o match mais preciso possível O que retorna - ID do contato, nome, e-mail, telefone - Campos personalizados - Datas de criação e última atividade 1b. Buscar contatos por texto livre (Search) Quando usar Para buscar um contato por qualquer campo textual (nome, e-mail, telefone, identificador, empresa) sem saber exatamente qual contém a informação. Diferente do endpoint anterior, este faz busca ILIKE (case-insensitive, parcial) em múltiplos campos simultaneamente. Endpoint GET /api/v1/accounts/{account_id}/contacts/search?q={termo} Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | q | string | Sim | Termo de busca. Mínimo de 2 caracteres quando contém apenas letras (busca somente name); mínimo de 3 caracteres quando contém qualquer dígito (busca em todos). Abaixo desses limites, retorna HTTP 422 | | page | integer | Não | Página de resultados (padrão: 1, 15 resultados por página) | Campos pesquisados - name — nome do contato (sempre pesquisado) - email — e-mail (a partir de 3 caracteres com dígito) - identifier — identificador externo (a partir de 3 caracteres com dígito) - phone_number — telefone, com e sem prefixo + (a partir de 3 caracteres com dígito) - company_name — nome da empresa (a partir de 3 caracteres com dígito) Resposta - payload[] — array de contatos encontrados - meta — contém apenas a página atual :::info meta.count e meta.total_pages foram removidos para reduzir custo de banco em consultas repetidas. Para obter o total absoluto, use o endpoint dedicado GET /api/v1/accounts/{account_id}/contacts/search/count?q={termo} (cacheado por 30s). ::: Exemplo GET /api/v1/accounts/1/contacts/search?q=maria&page=1 Retorna todos os contatos cujo nome, e-mail, telefone, identifier ou empresa contenham maria. Limite de uso (rate limit) :::warning 40 requisições por minuto por token de acesso. Excedendo o limite, a API responde HTTP 429 (Too Many Requests). O mesmo limite vale para /contacts/search/count. ::: Diferença entre os dois endpoints de busca | | Busca por e-mail/telefone | Busca por texto livre | | --- | --- | --- | | Namespace | /api/client/ | /api/v1/ | | Campos | Apenas e-mail ou telefone | name, email, identifier, phone, company | | Tipo de match | Exato | Parcial (ILIKE) | | Paginação | Não | Sim (15 por página) | | Total de resultados | — | Endpoint separado (/search/count) | 2. Listar tickets de um contato Quando usar Já tem o CONTACT_ID e quer listar os tickets desse cliente: - Mostrar histórico de atendimentos - Ver tickets abertos ou resolvidos - Integrar com CRM ou portal interno Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/conversations?page=1&limit=10 Parâmetros - page — obrigatório - limit — opcional (padrão: 10) O que retorna - IDs dos tickets - Status (open, resolved, etc.) - Prioridade - Inbox - Datas de criação - Se foi iniciado por campanha 3. Listar mensagens de um ticket Quando usar Para recuperar o histórico de mensagens de um ticket: - Auditoria em tempo real - Exibir conversa em outra interface - Debug de integrações Endpoint GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/messages?page=1&limit=10 O que retorna - Conteúdo da mensagem - Tipo (incoming / outgoing) - Pública ou privada - Data de criação - Status da mensagem - Links dos anexos (se existirem) Como essas APIs se conectam (fluxo típico) 1. Buscar contato por e-mail ou telefone 2. Obter o CONTACT_ID 3. Listar os tickets desse contato 4. Escolher um ticket 5. Listar as mensagens do ticket :::success Tudo isso sem alterar nenhum dado. ::: Nível de risco Risco médio — não alteram dados, mas consultam a base de produção em tempo real. :::info Boas práticas: - Evite loops agressivos - Use cache quando possível - Não use para exportação em massa ::: Erros comuns :::warning - Usar essas APIs para relatórios históricos - Esquecer o parâmetro page - Confundir CONTACT_ID com CONVERSATION_ID - Tentar criar ou atualizar dados com GET ::: Observações - Para alterar status, prioridade ou time: Como atualizar e agir em tickets via API - Para relatórios e BI (extração histórica): Como extrair dados em lote via API - Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em Jul 04, 2026

Como atualizar e agir em tickets via API

Quando usar - Você quer alterar status (resolver, reabrir), prioridade ou time de um ticket via integração - Você precisa enviar mensagens automaticamente em um ticket existente - Você precisa gerenciar labels (etiquetas) em tickets Pré-requisitos - API Key de administrador ou supervisor — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN, ACCOUNT_ID, CONVERSATION_ID (ID interno) e/ou DISPLAY_ID (ID visível na UI) :::error Estas APIs escrevem em produção. Alterações impactam SLAs, métricas e a operação. Valide o estado atual do ticket antes de fazer alterações e teste em ambiente controlado antes de usar em produção. ::: Sobre este artigo Estas APIs permitem modificar dados reais de tickets — alterar status, prioridade, time e enviar mensagens. Para apenas consultar dados (sem alterar), use Como consultar contatos, tickets e mensagens em tempo real via API. Autenticação Todos os endpoints exigem: | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Token de administrador ou supervisor | 1. Alterar status do ticket (resolver, reabrir, etc.) Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status Body { "status": "resolved" } Valores aceitos | Valor | Descrição | | --- | --- | | open | Reabrir ticket | | resolved | Resolver ticket | | pending | Marcar como pendente | Exemplo curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"status": "resolved"}' Retorna o objeto da conversa atualizada com status 200 OK. :::warning O endpoint PUT /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} não altera o status — ele só aceita o campo priority. Para alterar status, use sempre o toggle_status acima. ::: 2. Alterar prioridade do ticket Endpoint PUT https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}} Body { "priority": "high" } Valores aceitos | Valor | Descrição | | --- | --- | | nil / null | Sem prioridade | | low | Baixa | | medium | Média | | high | Alta | | urgent | Urgente | Exemplo curl -X PUT \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"priority": "high"}' :::warning Este endpoint (PUT .../conversations/{ID}) aceita apenas o campo priority. Campos como status, team_id ou outros são silenciosamente ignorados. ::: 3. Alterar status, prioridade e time (Client API) Para alterar status, prioridade e/ou time em uma única chamada, use a Client API: Endpoint PATCH https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}} :::warning Este endpoint usa o display_id (ID visível no Cloud Chat), não o conversation_id interno. ::: :::warning Esta Client API exige token de administrador. Tokens de supervisor ou agente recebem 403 Forbidden. Se você usa token de supervisor, altere status pelo toggle_status (seção 1) e priority pelo PUT (seção 2). ::: Body { "status": "resolved", "priority": "high", "team_id": "1" } Campos aceitos | Campo | Descrição | | --- | --- | | status | Status do ticket (open, resolved, pending) | | priority | Prioridade (low, medium, high, urgent) | | team_id | ID do time para reatribuição | Todos os campos são opcionais — envie apenas o que deseja alterar. Se o team_id informado não existir na conta, a API retorna 422 com {"error": "Team not found"}. Exemplo curl -X PATCH \ 'https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}}' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{"status": "resolved"}' 4. Criar mensagem em um ticket Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages Body { "content": "Olá! Segue atualização sobre sua solicitação.", "message_type": "outgoing" } Campos | Campo | Obrigatório | Descrição | | --- | --- | --- | | content | Sim | Conteúdo da mensagem | | message_type | Sim | incoming (mensagem do cliente) ou outgoing (mensagem do agente/sistema) | | private | Não | true para nota interna (não visível ao cliente) | Exemplo curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/messages' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "content": "Sua solicitação foi processada.", "message_type": "outgoing" }' 5. Gerenciar labels (etiquetas) de um ticket :::warning O endpoint PUT /conversations/{ID} não aceita o campo labels. Se você enviar labels no body do PUT, a API retorna 200 mas ignora silenciosamente o campo. Para gerenciar labels, use o endpoint dedicado abaixo. ::: Endpoint POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels Body { "labels": ["suporte", "prioridade-alta"], "append": true } Campos | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | labels | array de strings | Sim | Lista de labels a aplicar | | append | boolean | Não | true adiciona às labels existentes. false ou omitido substitui todas | Exemplo curl -X POST \ 'https://cloudchat.cloudhumans.com/api/v1/accounts/1/conversations/12345/labels' \ -H 'api_access_token: SEU_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"labels": ["suporte", "urgente"], "append": true}' Campos que não podem ser alterados via PUT/PATCH Alguns campos parecem editáveis mas são ignorados silenciosamente pela API (retorna 200 sem erro): | Campo | Situação | O que fazer | | --- | --- | --- | | mail_subject | Atributo dentro de additional_attributes. Só pode ser definido na criação do ticket. Tentativas de atualização via PUT são ignoradas | Não há workaround via API. Se o assunto do e-mail precisa ser diferente, crie um novo ticket | | labels | Ignorado no PUT/PATCH do ticket | Use o endpoint dedicado POST .../conversations/{ID}/labels (seção 5) | Resumo: qual endpoint usar para cada ação | Ação desejada | Endpoint | Método | | --- | --- | --- | | Alterar status (resolver, reabrir) | .../conversations/{ID}/toggle_status | POST | | Alterar prioridade | .../conversations/{ID} | PUT | | Alterar status + prioridade + time | /api/client/.../conversations/{DISPLAY_ID} | PATCH | | Criar mensagem no ticket | .../conversations/{ID}/messages | POST | | Gerenciar labels | .../conversations/{ID}/labels | POST | Fluxo seguro recomendado 1. Consulte o estado atual do ticket antes de alterar — ver Como consultar contatos, tickets e mensagens em tempo real via API 2. Valide se a ação é necessária (ex: não resolver um ticket já resolvido) 3. Execute a alteração usando o endpoint correto da tabela acima 4. Confirme o resultado verificando a resposta da API Onde encontrar os parâmetros - CLOUDCHAT_DOMAIN — domínio visível na URL do navegador - ACCOUNT_ID — em Configurações da conta - CONVERSATION_ID — ID interno da conversa (retornado nas APIs de consulta) - DISPLAY_ID — ID visível na interface do Cloud Chat (usado apenas na Client API) - API_TOKEN — em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings Observações - Para criar tickets novos via API: Como criar tickets via API no Cloud Chat - Para atualizar atributos customizados em conversas: Como atualizar atributos customizados em conversas via API - Para consulta sem alterar dados: Como consultar contatos, tickets e mensagens em tempo real via API - Visão geral das APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em Jul 04, 2026

Como criar, atualizar ou deletar artigos na Central de Ajuda via API

Quando usar - Você está automatizando a publicação de artigos na Central de Ajuda do Cloud Chat - Você precisa atualizar artigos existentes via integração ou script - Você precisa remover artigos via API Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN, ACCOUNT_ID e PORTAL_SLUG - Para criar: author_id e category_id - Para atualizar/deletar: ARTICLE_ID Endpoint base https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles Headers (todas as operações) | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | :::info Sobre PORTAL_SLUG — é o slug do portal (ex: cloud-chat, meu-portal), não um ID numérico. Você encontra o slug na URL do portal na interface. ::: Criar artigo A criação é feita em duas etapas: primeiro POST como rascunho (status=0), depois PUT para publicar (status=1). Etapa 1 — Criar como rascunho curl --location 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles' \ --header 'Content-Type: application/json' \ --header 'api_access_token: YOUR_TOKEN_HERE' \ --data '{ "content": "Conteúdo do artigo...", "status": 0, "title": "Título do artigo", "author_id": 1, "category_id": 1 }' :::warning Crie sempre como status: 0 (rascunho) primeiro. A resposta retorna o id do artigo criado — guarde esse valor para a etapa 2. ::: Etapa 2 — Publicar (PUT com status=1) curl --location --request PUT 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles/{{ARTICLE_ID}}' \ --header 'Content-Type: application/json' \ --header 'api_access_token: YOUR_TOKEN_HERE' \ --data '{ "status": 1 }' Atualizar artigo existente Use PUT com os campos que deseja alterar. curl --location --request PUT 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles/{{ARTICLE_ID}}' \ --header 'Content-Type: application/json' \ --header 'api_access_token: YOUR_TOKEN_HERE' \ --data '{ "title": "Novo título", "content": "Novo conteúdo...", "status": 1 }' :::info Campos omitidos no PUT não são alterados — envie só o que mudou. ::: Campos aceitos | Campo | Tipo | Descrição | | --- | --- | --- | | title | string | Novo título do artigo | | content | string | Novo conteúdo em Markdown | | status | integer | 0 rascunho, 1 publicado | | author_id | integer | ID do autor | | category_id | integer | ID da categoria | Deletar artigo Use DELETE com body vazio (ou opcional). curl --location --request DELETE 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles/{{ARTICLE_ID}}' \ --header 'Content-Type: application/json' \ --header 'api_access_token: YOUR_TOKEN_HERE' :::error Esta ação não pode ser desfeita. Confirme o ARTICLE_ID antes de executar. ::: Onde encontrar os parâmetros CLOUDCHAT_DOMAIN Parte da URL ao fazer login na sua conta: ACCOUNT_ID Em Configurações da conta: API_TOKEN Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings: author_id e category_id Inspecione a requisição feita pelo navegador durante uma alteração na própria tela de artigos: ARTICLE_ID a partir de um link https://cloudchat.cloudhumans.com/hc/cloud-chat/articles/1766069782-criar-um-artigo... → article_id = 1766069782 Observações - Para a versão simplificada (apenas criação): Como criar artigos na Central de Ajuda via API - Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Como criar artigos na Central de Ajuda via API

Quando usar - Você quer criar um novo artigo na Central de Ajuda do Cloud Chat via API - Você está automatizando a publicação de conteúdo a partir de outra fonte - Você precisa de uma referência rápida do endpoint de criação Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - ACCOUNT_ID e PORTAL_SLUG (slug do portal, ex: cloud-chat) - author_id e category_id cadastrados Endpoint POST /api/v1/accounts/{id}/portals/{slug}/articles Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Campos obrigatórios | Campo | Descrição | | --- | --- | | title | Título do artigo | | content | Conteúdo em Markdown | | status | 0 (rascunho) ou 1 (publicado) — recomendamos criar como 0 e publicar com PUT depois | | author_id | ID do autor | | category_id | ID da categoria | Exemplo curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/portals/{PORTAL_SLUG}/articles' \ --header 'Content-Type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "title": "Título do artigo", "content": "Conteúdo em Markdown...", "status": 0, "author_id": 1, "category_id": 1 }' :::info Após criar como rascunho (status=0), publique fazendo um PUT com status=1 no mesmo article_id. Veja o fluxo completo em Como criar, atualizar ou deletar artigos na Central de Ajuda via API. ::: Observações - Para o fluxo completo (criar + publicar + atualizar + deletar): Como criar, atualizar ou deletar artigos na Central de Ajuda via API - Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 2026

Disparar mensagem proativa por API (WhatsApp e Widget Web)

Quando usar - Quando um sistema externo (seu backend, CRM, automação de marketing) precisa iniciar uma conversa com um contato específico — sem um agente abrir manualmente. - Para avisos transacionais e proativos por contato: confirmação de pedido, lembrete de pagamento, atualização de status, retomada de carrinho. - Em dois canais, com a mesma autenticação (api_access_token): - WhatsApp — envia uma mensagem de template aprovado para o telefone do contato. - Widget Web de área autenticada (HMAC) — exibe uma mensagem que aparece quando o contato volta autenticado no chat do seu site/app. Pré-requisitos - Um Token de Acesso API do Cloud Chat (disponível no seu perfil, em Perfil → Configurações → Access Token). Ele deve estar no cabeçalho api_access_token. - O account_id da sua conta (aparece na URL do Cloud Chat). - Para WhatsApp: uma caixa de entrada de WhatsApp conectada + um template aprovado pela Meta. - Para Widget Web: uma caixa de entrada de Widget Web com HMAC obrigatório (área autenticada / identidade verificada) + um contato identificável. Como funciona Autenticação Os dois endpoints utilizam o mesmo cabeçalho. Nunca exponha o token no front-end — esses disparos são servidor-para-servidor. api_access_token: SEU_API_ACCESS_TOKEN Content-Type: application/json WhatsApp: disparo por template Envia (push) uma mensagem ativa — chega no WhatsApp do contato na hora. Como é WhatsApp, o conteúdo precisa ser um template aprovado. POST https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation { "inbox_id": 123, "phone_number": "+5511999998888", "template_name": "lembrete_pagamento", "labels": ["campanha-x", "vip"], "cliente": "João", "valor": "R$ 120,00" } - inbox_id — a caixa de WhatsApp pela qual a mensagem é enviada. - phone_number — telefone do contato no formato internacional E.164 (com + e código do país, ex.: +5511999998888). - template_name — nome do template aprovado. - Variáveis do template — cada variável deve ser enviada como um campo no nível raiz do corpo (irmão de inbox_id/phone_number/template_name), com o nome da variável do template. Ex.: um template com as variáveis cliente e valor deve receber os campos "cliente" e "valor". Não inicie esses campos dentro de um objeto template_params nem utilize chaves posicionais ("1", "2"). - labels (opcional) — array de strings com títulos de tags a aplicar na conversa criada (ex.: ["campanha-x", "vip"]). Os títulos são normalizados para minúsculas e as tags são adicionadas sem remover tags existentes. Tags novas são criadas na conta automaticamente apenas se o token for de administrador; com token de agente, títulos inexistentes são ignorados. Detalhes em Como enviar mensagem proativa pelo WhatsApp via API. Widget Web (área autenticada): disparo por contato Exibe uma mensagem que aparece de forma passiva: o widget não envia push — a mensagem surge na próxima vez que o contato abre o chat autenticado na área logada. Você pode disparar mesmo para quem ainda não abriu o chat (identificando pelo identifier). POST https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_web_widget_conversation { "inbox_id": 456, "identifier": "user-42", "content": "Oi João! Vi que seu plano vence amanhã. Posso te ajudar a renovar?", "idempotency_key": "renovacao-user-42-2026-06-28" } - inbox_id — a caixa do Web Widget (HMAC obrigatório). - Identificação do contato — envie exatamente um destes: - identifier — seu identificador estável do usuário. Cria o contato se ainda não existir. - email — usa um contato já identificável com aquele email. - contact_id — o ID do contato no Cloud Chat. - content — o texto livre da mensagem (não necessita de template). - idempotency_key (opcional) — consulte abaixo. - contact_attributes (opcional) — atributos/nome para enriquecer o contato na criação. :::info A entrega é passiva: a mensagem só fica visível após o contato autenticar a sessão no widget (HMAC). É por isso que esse disparo é exclusivo de caixas de área logada. ::: Widget Web: formato do identificador O identifier precisa ser idêntico ao valor que seu app usa para gerar o HMAC no SDK do widget para aquele usuário. Se eles divergirem (ex.: você dispara "42", mas o widget envia "user-42"), o Cloud Chat tratará como contatos diferentes e a mensagem não aparecerá para o usuário. - identifier — string estável (o mesmo do HMAC). Recomenda-se utilizar o ID do usuário no seu sistema. - email — um email válido de um contato já identificável. Widget Web: múltiplas caixas e contatos sem telefone - Múltiplas caixas de Web Widget. O identifier identifica o contato ** em toda a conta**, então o mesmo usuário pode ser alcançado em diferentes caixas (ex.: produtos ou áreas logadas distintas) usando o mesmo identifier. O disparo ocorre sempre por caixa (inbox_id): cada caixa mantém sua própria conversa/sessão com o contato. Para falar com o usuário em duas áreas, envie uma mensagem para cada inbox_id. - Quando não há número de telefone. Diferente do WhatsApp (onde o número é a identidade), no Web Widget o contato é identificado por identifier/email e não precisa ter telefone. Contatos sem número são suportados plenamente — o telefone é irrelevante para esse canal. Idempotência (Web Widget) Reenvios são seguros se você usar idempotency_key. A mesma chave, dentro de 24 horas, retorna a mesma conversa, ao invés de criar uma duplicata — útil para tentativas de reenvio. Reusar a mesma chave para um contato diferente é rejeitado (erro idempotency_key_contact_mismatch). Principais erros | Código | Significado | | --- | --- | | inbox_id_required / inbox_not_found | Caixa de entrada ausente ou não encontrada na conta. | | contact_not_identifiable | email/contact_id fornecido não corresponde a um contato identificável. | | ambiguous_contact_match | Os dados correspondem a mais de um contato — refine a identificação. | | invalid_contact_attributes | contact_attributes inválidos para criar o contato. | | idempotency_key_contact_mismatch | A idempotency_key já foi usada para outro contato. | Observações - WhatsApp = ativo (push, via template); Widget Web = passivo (texto livre, na próxima sessão autenticada). Escolha o canal de acordo com o tipo de entrega desejada. - O disparo é por contato nos dois canais (um a um), não uma campanha em massa. - A conversa criada fica fora da fila/SLA dos agentes até que o contato engaje — ela não conta como atendimento ativo enquanto ninguém responder. - Mantenha o api_access_token somente no servidor.

Última atualização em Jul 22, 2026

Como extrair respostas de botões (Quick Reply) de campanhas WhatsApp via API

Quando usar - Quando você dispara uma campanha de WhatsApp com um template que tem botões de resposta rápida (Quick Reply) e quer saber, por campanha, quem tocou em qual botão e quando. - Para montar métricas de campanha e de botões (taxa de resposta, qual opção foi mais escolhida) a partir do seu backend, sem precisar abrir conversa a conversa na interface. - É um endpoint servidor-para-servidor, somente leitura. Não há interface para isso no Cloud Chat — os dados saem pela API. Pré-requisitos - Um Token de Acesso API de administrador do Cloud Chat (em Perfil → Configurações → Access Token). Com token de agente o endpoint retorna 401/403. - O account_id da sua conta (aparece na URL do Cloud Chat). - Uma campanha de WhatsApp já disparada, cujo template tenha botões de Quick Reply. - O display_id da campanha — é o número que aparece na URL/listagem da campanha (não o id interno do banco). Como funciona Autenticação api_access_token: SEU_API_ACCESS_TOKEN Rota GET https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns/{DISPLAY_ID}/responses - {ACCOUNT_ID} — id da conta. - {DISPLAY_ID} — display_id da campanha. Parâmetros de query (opcionais) - page — página (default 1). - per_page — itens por página (default 100, máximo 500). Exemplo de chamada curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/7/campaigns/156/responses?page=1&per_page=100' \ -H 'api_access_token: SEU_API_ACCESS_TOKEN' Resposta A resposta tem três partes: responses, summary e meta. { "responses": [ { "id": 27749371, "content": "Sim, tenho interesse e desejo prosseguir", "inbox_id": 174, "conversation_id": 1777, "message_type": 0, "status": "delivered", "additional_attributes": { "campaign_id": 188, "template_button_reply": true, "template_button_payload": "Sim, tenho interesse e desejo prosseguir" }, "created_at": 1784781019, "sender": { "id": 1350835, "type": "contact", "name": "João da Silva", "phone_number": "+5511999998888" } } ], "summary": { "Sim, tenho interesse e desejo prosseguir": 1 }, "meta": { "current_page": 1, "total_count": 1, "total_pages": 1 } } - responses — cada item é a mensagem de resposta do contato (o toque no botão). Campos úteis: - content — o texto do botão tocado. - sender — o contato que respondeu (nome + telefone). - additional_attributes.template_button_payload — o payload do botão (ecoa o texto do botão). - conversation_id / created_at — onde e quando a resposta aconteceu. - summary — contagem agregada por texto do botão: { "<texto do botão>": <quantidade> }. É o atalho para a métrica "quantas pessoas escolheram cada opção". - meta — paginação: current_page, total_count (total de respostas da campanha), total_pages. Notas importantes - Sem histórico retroativo. Só aparecem respostas registradas a partir do lançamento do recurso. Campanhas antigas não são preenchidas retroativamente. - O identificador de análise é o texto do botão. Como os templates não definem um payload próprio, o payload apenas repete o texto do botão. Agrupe/analise pelo texto (é o que o summary faz). - Só contam toques de botão Quick Reply de campanha. Se o contato responder com texto livre (em vez de tocar num botão), essa resposta não entra aqui — o vínculo com a campanha só existe quando é um toque de botão de um envio de campanha.

Última atualização em Jul 23, 2026