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 6 outros
• 17 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. ::: - Sempre gera um novo ticket - 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 | | 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", "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. ::: 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 May 21, 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: - ticketId, displayTicketId, inboxId, accountId, accountName - ticketStatus, teamName, ticketPriorityName, ticketType (primeira tag), inboxName - ticketTitle, channel, tags - createdAt, firstReplyAt, firstReplyTime (minutos), resolvedAt, totalResolutionTimeMin - agentId, ticketOwner, ticketOwnerEmail - contactId, contactName, contactEmail, contactPhone - campaignId, proactivelyInitiated :::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: - ticketLink — link direto do ticket - agentOnResolutionId, agentOnResolutionName, agentOnResolutionEmail — agente humano que resolveu - firstAgentReplyId, firstAgentReplyName, firstAgentReplyEmail — primeiro agente humano que respondeu - firstAgentAssignmentTime, firstAgentFirstReplyTime - firstReplierAgentAssignmentTime, firstReplierAgentFirstReplyTime - firstAgentReplyTimeMin, firstAgentResolutionTimeMin - csatScore, csatFeedback - contactCustomFields, conversationCustomFields, conversationAdditionalFields (JSON) Exemplo de resposta [ { "ticketId": 11111, "displayTicketId": 11111, "accountName": "account name", "inboxName": "WhatsApp", "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/11111", "ticketStatus": "resolved", "createdAt": "2025-03-27T13:00:40.897954", "resolvedAt": "2025-03-27T15:38:02.743726", "agentOnResolutionId": 225, "agentOnResolutionName": "ClaudIA", "agentOnResolutionEmail": "[email protected]", "firstAgentReplyId": 111, "firstAgentReplyName": "ClaudIA", "firstAgentReplyEmail": "[email protected]", "firstAgentAssignmentTime": "2025-03-27T13:16:13.001269", "firstAgentFirstReplyTime": "2025-03-27T13:17:01.344971", "firstAgentReplyTimeMin": 0.81, "firstAgentResolutionTimeMin": 141.83, "csatScore": null, "csatFeedback": "", "contactCustomFields": "{}", "conversationCustomFields": "{}", "conversationAdditionalFields": "{}" } ] :::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. Inclui ticketId, displayTicketId, ticketLink e summary. [ { "ticketId": 1111, "displayTicketId": 1111, "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111", "summary": "CONTATO: Oi\nUSUÁRIO: Olá!" } ] 4. CAMPAIGN_DELIVERY_EVENTS Retorna eventos de entrega de campanhas do WhatsApp, rastreando por contato e campanha o status das mensagens. Campos retornados: - id, campaignId, campaignTitle, audience - contactId, contactName, contactEmail, contactPhoneNumber - ticketId, displayTicketId - messageSent, sentAt — envio para a API do WhatsApp (Meta) - messageReceived, receivedAt — entrega ao dispositivo do contato - messageRead, readAt — leitura confirmada (depende do status de leitura habilitado nas configurações de privacidade do contato) - messageReplied, repliedAt — primeira resposta - error — mensagem de erro (número inválido, sem WhatsApp, bloqueio, etc.) - createdAt, updatedAt Exemplo de resposta [ { "id": 103, "campaignId": 5502, "campaignTitle": "Natal 2025 - Promoção Especial", "audience": "lista_fidelidade_natal", "contactId": 9003, "contactName": "Carla Souza", "contactEmail": "[email protected]", "contactPhoneNumber": "+55 31 99999-99999", "ticketId": 78414, "displayTicketId": "2027", "messageSent": false, "sentAt": null, "messageReceived": false, "receivedAt": null, "messageRead": false, "readAt": null, "messageReplied": false, "repliedAt": null, "error": "Número de telefone inválido ou não registrado no WhatsApp", "createdAt": "2025-12-10T09:00:00.000Z", "updatedAt": "2025-12-10T09:00:00.000Z" } ] 5. SINGLE_CONTACT_DELIVERY_EVENTS Retorna eventos de entrega de mensagens proativas de disparo único (não campanhas). Mesma estrutura de campos do CAMPAIGN_DELIVERY_EVENTS, sem os campos de campanha. Exemplo de resposta [ { "id": 321, "contactId": 555777, "contactName": "Maria Silva", "contactEmail": "[email protected]", "contactPhoneNumber": "+55 11 98888-7777", "ticketId": 78414, "displayTicketId": "2027", "messageSent": true, "sentAt": "2025-08-01T12:00:05.000Z", "messageReceived": true, "receivedAt": "2025-08-01T12:00:08.000Z", "messageRead": true, "readAt": "2025-08-01T12:01:30.000Z", "messageReplied": false, "repliedAt": null, "error": null, "createdAt": "2025-08-01T11:59:59.000Z", "updatedAt": "2025-08-01T12:01:30.000Z" } ] Observações - Para consultas em tempo real (não histórico): Como consultar contatos, tickets e mensagens em tempo real via API - Para alterar dados de tickets via API: Como atualizar e agir em tickets via API - Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API

Última atualização em May 21, 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 — token de administrador ou supervisor 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 May 21, 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. ::: 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. 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 May 21, 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