Principal API e integrações | Chaves, endpoints e webhooks
🔗

API e integrações | Chaves, endpoints e webhooks

Chave de API, endpoints, webhooks e integrações com outros sistemas.
Tech
Por Matheus and 8 outros
• 35 artigos

Como enviar mensagem proativa pelo WhatsApp via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 FAQ — Integração com WhatsApp: perguntas frequentes - 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 | Sim, se o template tiver variáveis | Um campo para cada variável, com o nome exato dela, na raiz do JSON (ver abaixo) | Sobre as variáveis dinâmicas Cada variável do template vira um campo na raiz do JSON, ao lado de inbox_id, phone_number e template_name, com o nome exato da variável: - Template com variáveis nomeadas, como Olá {{cliente}}, seu boleto de {{valor}} vence amanhã: envie os campos "cliente" e "valor". - Template com variáveis numeradas, como Olá {{1}}, seu boleto de {{2}} vence amanhã: envie os campos "1" e "2". Se faltar alguma variável, a API recusa a requisição com o erro missing params. Campos que não correspondem a nenhuma variável são ignorados. Nomes de variável com ponto ou acento (como {{contact.name}} ou {{horário}}) não são aceitos pela Meta como variável. 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": "lembrete_pagamento", "labels": ["campanha-x", "vip"], "header_attachment": "ATTACHMENT_URL", "button_param_0": "BUTTON PARAMETER", "button_param_1": "ANOTHER BUTTON PARAMETER", "cliente": "João", "valor": "R$ 120,00" }' Onde encontrar os parâmetros - account_id — no painel administrativo da conta - inbox_id — ID da caixa de entrada configurada (https://{SEU_DOMINIO}/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 ou CX Engineer. 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 Sep 23, 2026

Como importar contatos em massa via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 - Criar, atualizar ou deletar um contato por vez: Como criar, atualizar e deletar contatos via API - 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 Sep 23, 2026

Como enviar mensagem proativa pelo WhatsApp via HubSpot

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 FAQ — Integração com WhatsApp: perguntas frequentes 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 1. Clique em Criar fluxo de trabalho e selecione Do zero 1. Escolha as opções que disparam o gatilho Etapa 2 — Configurar o envio do Webhook 1. Adicione uma ação clicando em + 1. No painel esquerdo, clique em Operações de dados e selecione Envie um webhook 1. Escolha o método POST 1. Preencha a URL do webhook: https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation 1. 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 Sep 23, 2026

API - Enviar Mensagem Proativa pelo WhatsApp

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Este artigo é a referência rápida do endpoint de WhatsApp. O guia completo, com Widget Web e tags, está em Disparar mensagem proativa por API (WhatsApp e Widget Web). Descrição Esse endpoint permite criar uma conversa proativa pelo WhatsApp utilizando um template previamente configurado. Os parâmetros do template são dinâmicos e podem variar dependendo da configuração do template utilizado. Endpoint URL: POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation Headers: - content-type: application/json - api_access_token: Chave de acesso da API. Parâmetros Path Parameter account_id - Tipo: String - Obrigatório: Sim - Descrição: ID da conta no sistema. Body Parameters 1. inbox_id - Tipo: String - Obrigatório: Sim - Descrição: ID da inbox para onde a mensagem será enviada. 2. phone_number - Tipo: String - Obrigatório: Sim - Descrição: Número de telefone do destinatário, incluindo o código do país. 3. template_name - Tipo: String - Obrigatório: Sim - Descrição: Nome do template configurado no sistema. 4. Parâmetros Dinâmicos do Template - Tipo: Vários - Obrigatório: Sim, se o template tiver variáveis (todas são obrigatórias) - Descrição: Um campo para cada variável do template, com o nome exato dela (veja abaixo). 5. labels - Tipo: Array de strings - Obrigatório: Não - Descrição: Títulos de tags a aplicar na conversa criada. Detalhes no guia completo. Sobre os Parâmetros Dinâmicos Cada variável do template vira um campo na raiz do JSON, ao lado de inbox_id, phone_number e template_name, com o nome exato da variável: - Template com variáveis nomeadas, como Olá {{cliente}}, seu boleto de {{valor}} vence amanhã: envie os campos "cliente" e "valor". - Template com variáveis numeradas, como Olá {{1}}, seu boleto de {{2}} vence amanhã: envie os campos "1" e "2". Se faltar alguma variável, a API recusa a requisição com o erro missing params. Campos que não correspondem a nenhuma variável são ignorados. Nomes de variável com ponto ou acento (como {{contact.name}} ou {{horário}}) não são aceitos pela Meta como variável. 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": "lembrete_pagamento", "cliente": "João", "valor": "R$ 120,00" }' Notas 1. account_id: O account_id pode ser encontrado no painel administrativo da conta. 2. inbox_id: O inbox_id corresponde ao id da caixa de entrada configurada para receber mensagens. 3. api_access_token: Gere o token no painel de configuração de API. 4. Parâmetros Dinâmicos do Template: Consulte a configuração do seu template no painel administrativo para identificar as variáveis disponíveis e obrigatórias. Esses parâmetros devem ser enviados diretamente na raiz do payload. Importante: Certifique-se de que o número de telefone esteja no formato internacional (E.164), incluindo o código do país. Limite de requisições Este endpoint aceita até 200 requisições por minuto por chave de API. Acima disso, a resposta é 429 com o cabeçalho Retry-After (segundos até liberar). Aguarde esse tempo antes de reenviar e, em lotes grandes, distribua os disparos ao longo dos minutos. Uma requisição que recebeu 429 não foi processada, então reenviá-la não duplica a mensagem. Corpo da resposta, demais cabeçalhos e como o limite é contado estão em Quais são os limites de requisição (rate limits) das rotas da API do Cloud Chat?. Campanhas via API Para disparar para uma lista de contatos, use a criação de campanha da API pública (api.cloudhumans.com), disponível também no MCP da Cloud Humans: - A audiência é definida por tag: a campanha vai para os contatos com a tag. - Antes de criar, a API pede a confirmação de quantos contatos vão receber. - O envio sai pelo agendador de campanhas, em alguns minutos ou no horário agendado. - A autenticação é por login de usuário (token Bearer), não pela api_access_token deste endpoint. Referência: Criar uma campanha. O endpoint desta página continua sendo o caminho para o envio um a um; para enviar em volume por ele, respeite o limite de 200 requisições por minuto.

Última atualização em Sep 23, 2026

Como importar contatos via HubSpot

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 Sep 23, 2026

Como importar um contato individual via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 - Criar, atualizar ou deletar um contato por vez: Como criar, atualizar e deletar contatos via API - 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 Sep 23, 2026

Como remover tags de contatos em massa via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 excluir o contato (não apenas remover tags): Como criar, atualizar e deletar contatos via API - 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 Sep 23, 2026

Como atualizar atributos customizados em conversas via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 Sep 23, 2026

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

:::warning Aviso importante: esta API não vai continuar sendo evoluída. A forma recomendada, hoje, para extração massiva de dados é a nova documentação: CloudHumans Data Export. ::: 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 (em Configurações do perfil, no seu próprio ambiente — use o domínio da sua conta, ex.: https://SEU-DOMINIO.cloudhumans.com/app/accounts/{ACCOUNT_ID}/profile/settings. O domínio varia por instância: cloudchat, cloudchat2, cloudchat3…) 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 um resumo 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 | Resumo da conversa entre cliente e atendente — pode vir truncado em conversas longas | Sim | [ { "ticketId": 1111, "displayTicketId": 1111, "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111", "summary": "CONTATO: Oi\nUSUÁRIO: Olá!" } ] :::warning O campo summary não garante a transcrição integral da conversa: ele consolida trechos e, em conversas longas, o conteúdo pode vir cortado. Se você precisa do histórico completo, use o envio da transcrição por e-mail a partir da própria conversa, em vez da API. ::: 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" } ] Passo a passo prático 1. Gere sua API Key num perfil administrador ou supervisor (Configurações do perfil → veja "Como pegar a sua API Key"). 2. Escolha onde rodar: é uma chamada HTTP GET — use um cliente de API (Postman, Insomnia) ou o terminal com curl. Não precisa programar. 3. Monte a URL trocando os campos entre {}: https://{SEU_DOMINIO}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T00:00:00&endDate=2025-03-27T23:59:59&type=TICKET_METRICS_WITH_AGENT_INFORMATION 4. Adicione o cabeçalho de autenticação (obrigatório — sem ele retorna 401): api_access_token: {SUA_API_KEY} 5. Envie a requisição (botão Send no Postman, ou rode o curl). 6. Leia o resultado: vem um JSON com a lista de tickets; cada campo está descrito nas tabelas de tipos deste artigo. 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 Sep 13, 2026

Cloud Chat: Import de histórico de tickets

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Cloudchat: Import em massa de contatos via API Para importar contatos via API no Cloud Chat, basta enviar uma POST request para https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create enviando a chave de acesso e os campos solicitados abaixo. 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: API_TOKEN' \ --data '{ "data": [ { "name": "CONTACT_NAME", "email": "CONTACT_EMAIL", "phone_number": "CONTACT_PHONE", "identifier": "CONTACT_ID", "custom_attributes": { <CUSTOM_PAIRS> } } ] }' Corpo da requisição O corpo da requisição deve conter: - data: (obrigatório) Lista de objetos com os dados dos contatos. - upsert: (opcional) Quando definido como true, o endpoint realizará upsert (criação ou atualização). Se um contato com o mesmo identifier, email ou phone_number já existir, ele será atualizado com os novos valores enviados. Caso contrário, será criado. Exemplo { "upsert": true, "data": [ { "name": "contact 1", "identifier": "contact-1-id", "email": "[email protected]", "phone_number": "+912345678", "custom_attributes": { "hello": "hello", "test": "test" } }, { "name": "contact 2", "identifier": "contact-2-id", "email": "[email protected]", "phone_number": "+987654321", "custom_attributes": { "hello": "hello", "test": "test" } } ] } Regras importantes - Identificadores obrigatórios: Cada contato no payload deve conter pelo menos um identificador único: identifier, email ou phone_number. - Criação padrão: Caso a flag upsert não seja enviada, o endpoint realizará apenas criação. - Upsert: Para criar novos contatos e atualizar os existentes no mesmo payload, defina "upsert": true no corpo da requisição. ⚠️ Atenção ao usar Ao usar o upsert no import em massa, qualquer dado existente que não for explicitamente informado será substituído por null. Por exemplo, se um contato existente possui email e phone_number, mas no payload de upsert for enviado apenas o phone_number, o campo email será apagado. Esse comportamento ocorre porque o endpoint de bulk_create é voltado para importação completa de contatos, e não para atualizações parciais. Para atualizar individualmente apenas certos campos de um contato existente, recomenda-se o uso do endpoint específico de atualização de contato: API: Import de Contato Parâmetros CLOUDCHAT_DOMAIN: Você pode obter seu domínio ao fazer login na sua conta no CloudChat. É a parte que aparece na URL do navegador: ACCOUNT_ID: Obtido na seção de configurações da conta: API_TOKEN: Obtido nas configurações do perfil (https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings) CONTACT_NAME, CONTACT_EMAIL, CONTACT_PHONE e CONTACT_ID(opcionais): Atributos que serão adicionados ao nome, email, número de telefone e identificador externo respectivamente. CUSTOM_PAIRS(opcional): Os atributos personalizados devem ser enviados no formato key: value, onde key é a chave do atributo no Cloud Chat e value é o valor desejado para o atributo.

Última atualização em Sep 23, 2026

Migração de histórico de tickets para o Cloud Chat

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Ao migrar de outro helpdesk, as conversas antigas não vêm automaticamente — ficam na ferramenta anterior. Se quiser preservá-las no Cloud Chat, veja abaixo o que entregar pra gente. O que você precisa nos entregar 1. Caixa de entrada pronta. Garanta que a migração do seu canal está concluída e a inbox está criada e ativa no Cloud Chat — só importamos o histórico depois disso (sem inbox, não há para onde importar). 2. O histórico no formato JSON. Exporte suas conversas antigas em um arquivo JSON com a chave conversations_data — uma lista de tickets. Cada ticket tem: - Datas do ticket: created_at (abertura) e updated_at (última atualização), em ISO 8601 (ex.: 2024-01-15T10:30:00Z). - contact: identifier (obrigatório, único e estável por cliente) e, opcionais, name, email, phone_number (E.164). - messages: cada mensagem com content (texto), message_type (incoming = cliente, outgoing = agente, activity = nota interna), created_at (ISO 8601) e private (true para nota interna). - custom_attributes (recomendado): as informações que você quer preservar como referência. Guarde o ID do ticket antigo em external_helpdesk_id (rastreabilidade), e inclua as tags e atributos do ticket que quiser manter (ex.: priority, source_queue, tags). Essas tags entram como informação/etiqueta de referência na conversa importada — não como a tag nativa que filtra na plataforma. Nos diga quais quer preservar. Exemplo: { "conversations_data": [ { "contact": { "identifier": "user_6782902", "name": "John Doe", "email": "[email protected]", "phone_number": "+5511988887777" }, "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "Meu pedido não chegou.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false }, { "content": "Oi! Já verifiquei, sai hoje.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false }, { "content": "Cliente VIP, priorizar.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true } ] } ] } 3. Combine o escopo com seu contato. Alinhe com a gente o período (todo o histórico ou um recorte, ex.: últimos 12 meses), quais tags/atributos quer preservar, e se quer separar por canal (WhatsApp, Instagram, e-mail…). 4. Envie o arquivo. Suba o(s) arquivo(s) .json na pasta do Google Drive que a gente compartilha com você — ou, se preferir, mande um link do arquivo (Google Drive, OneDrive, o que for). Se você quer manter os canais separados, envie um arquivo por canal (ex.: historico_whatsapp.json). 5. Comece por uma amostra. Antes do arquivo completo, mande 20–50 tickets no formato — a gente importa num ambiente de validação, você confere, e só então processamos tudo. :::info Não é importado: imagens e anexos. A migração é de texto (mensagens, notas internas e metadados). Se um anexo era essencial, inclua o link dele no texto da mensagem. Regras: datas sempre em ISO 8601 (se não conseguir em UTC, nos avise o fuso); identifier único de verdade (dois clientes com o mesmo valor viram um só); arquivo em UTF-8. ::: A Cloud Humans faz a importação pra você Com o arquivo enviado, o time da Cloud Humans executa a importação — importamos em lotes, respeitando os limites da plataforma, e confirmamos o resultado com você. Você não precisa mexer em API nem nos dar acesso à sua ferramenta antiga. Prefere fazer por conta própria? Segue o passo a passo Se seu time tem desenvolvedor e prefere rodar a importação, use a API. Além do arquivo no formato acima, você vai precisar de: API Key (ver Como pegar a sua API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID. Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import | Header | Valor | | ------------------ | ------------------ | | content-type | application/json | | api_access_token | Seu token de API | O corpo é o mesmo conversations_data descrito acima. Limites — cada requisição aceita no máximo 10.000 tickets ou 15 MB. Para volumes maiores, particione em múltiplas requisições. O identifier do contato é único (dedup). Para os custom_attributes aparecerem formatados no painel, defina-os antes em Settings → Custom Attributes (escopo: Conversation). Onde encontrar os IDs 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 Sep 23, 2026

📨 Como criar tickets no CloudChat via API com status em aberto (a partir de canais externos)

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 🔍 O que essa funcionalidade permite? Você pode usar a API de importação de tickets do CloudChat para: - Criar novos tickets com status “em aberto” - Atribuir dados do contato automaticamente (e-mail, telefone, nome) - Incluir a primeira mensagem (ex: mensagem de um formulário, transcrição de uma ligação) - Continuar o atendimento por e-mail, WhatsApp ou outro canal após a criação - Atribuir campos personalizados e históricos com precisão Essa funcionalidade é ideal para casos em que o atendimento começa fora do CloudChat, como: - 🧾 Formulários no site - ☎️ Sistemas de telefonia ou URA - 📥 Integrações com ferramentas de terceiros 🎯 Exemplos de uso prático 📞 Integração com sistemas de ligação (voz) Seu sistema de voz detecta uma nova ligação e deseja: - Criar um novo ticket no CloudChat com dados da ligação (número, duração, gravação, resumo) - Aguardar um atendente responder por e-mail ou WhatsApp 📋 Formulário web (site ou app) Você tem um formulário como: - Nome - E-mail - Mensagem - Assunto E quer transformar esse envio em um ticket aberto, que aparece para o time com status em aberto e pronto para ser respondido por e-mail. 🧱 Como usar a API Você deve enviar uma requisição POST para: https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import 🔐 Headers obrigatórios: { "content-type": "application/json", "api_access_token": "SUA_CHAVE_DE_ACESSO" } 📦 Exemplo de corpo da requisição { "conversations_data": [ { "contact": { "email": "[email protected]", "name": "Maria Silva", "phone_number": "+5511999999999", "identifier": "cliente_999" }, "created_at": "2025-10-23T14:30:00Z", "updated_at": "2025-10-23T14:30:00Z", "messages": [ { "content": "Olá, acabei de falar com vocês por telefone e gostaria de confirmar meu protocolo.", "message_type": "incoming", "created_at": "2025-10-23T14:30:00Z", "private": false } ] } ] } 🔄 Como garantir que o ticket fique com status “Em aberto” - Sempre inclua pelo menos uma mensagem do tipo "incoming", com private: false - O ticket será automaticamente criado com status em aberto e aparecerá na Inbox - Ele poderá ser respondido normalmente pelo canal configurado (como e-mail) 🧠 Dicas e melhores práticas - O campo identifier é obrigatório e deve ser único por contato (mesmo se mudar o nome ou e-mail, o match será feito por esse campo) - Use phone_number, email ou ambos para facilitar futuras comunicações - Para campos customizados, use a API de atualização de atributos após o ticket ser criado, com um PUT: /api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/custom_attributes ⚠️ Limites por requisição - Máximo de 10.000 tickets por chamada - Máximo de 15MB por payload - Se for importar em lote, particione os dados e envie em blocos separados ✅ Verificações finais para sucesso 📚 Links úteis - Atualizar atributos customizados da conversa - Remoção em massa de tags de contatos - Como gerar seu token de API

Última atualização em Sep 23, 2026

Como criar tickets via API no Cloud Chat

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 "Permitir criação de conversas via API" habilitado (em Configurações → Caixas de entrada → aba Ciclo da conversa) - 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 Sep 23, 2026

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

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 criar, atualizar e deletar contatos via API - Como mesclar (merge) contatos 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 Sep 23, 2026

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

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 — 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 ::: Tags (labels) da conversa e como achar o contact_id Tags aplicadas à conversa têm endpoint próprio (no Chatwoot, base do Cloud Chat, elas se chamam labels): GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/labels Para descobrir o contact_id a partir do CONVERSATION_ID não é preciso um endpoint separado — o próprio detalhe da conversa já devolve: GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID} Na resposta, meta.sender.id é o contact_id do contato dono da conversa. O mesmo objeto meta.sender traz nome, e-mail, telefone e outros identificadores. Os dois endpoints exigem um api_access_token de um usuário com permissão adequada. 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 Sep 23, 2026

Como atualizar e agir em tickets via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 Sep 23, 2026

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

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 O ARTICLE_ID que a API espera não é o número que aparece na URL pública do artigo. Esse número é apenas um timestamp gerado no momento da criação e faz parte do slug — usá-lo no PUT ou no DELETE retorna 404. Para descobrir o ID real, liste os artigos filtrando pelo título e case pelo slug: curl --location --get 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles' \ --data-urlencode 'query=palavras do título do artigo' \ --header 'Content-Type: application/json' \ --header 'api_access_token: YOUR_TOKEN_HERE' A resposta traz a lista em payload; o campo id de cada item é o ARTICLE_ID que os endpoints de atualização e deleção esperam. Exemplo: o artigo de URL pública .../hc/cloud-chat/articles/1766069782-criar-um-artigo-na-central-de-ajuda-via-api tem ARTICLE_ID = 1869. :::info O parâmetro query faz busca por texto no título, na descrição e no conteúdo. A listagem também aceita locale, category_slug, author_id e status para restringir o resultado. ::: 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 Sep 23, 2026

Como encontrar sua API Key no Cloud Chat

Quando usar - Você está configurando uma integração e precisa do api_access_token para autenticar as requisições - Você quer reutilizar a mesma chave em outro fluxo (HubSpot, Postman, script) - Você precisa rotacionar a chave por segurança Pré-requisitos - Estar logado no Cloud Chat com a sua conta — a chave é gerada por usuário, não por conta Sobre este artigo A chave de API ficava no fim da tela de Configurações do Perfil, junto com foto, assinatura e notificações. Agora ela tem uma página própria, MCP / API, no mesmo menu do seu avatar. É lá que ficam os dois assuntos de integração do seu usuário: o Servidor MCP, para ligar a Cloud Humans a assistentes de IA, e a Chave de API, para autenticar chamadas à API do Cloud Chat. :::info Se você abrir o menu e ainda não vir MCP / API, mas encontrar Token de acesso no fim das Configurações do Perfil, a sua instância ainda não recebeu essa atualização. O valor da chave é exatamente o mesmo nos dois lugares — copie de onde ela estiver. ::: Passo a passo Etapa 1 — Abrir a página MCP / API 1. No canto inferior esquerdo, clique no seu avatar para abrir o menu 2. Clique em MCP / API Etapa 2 — Copiar a chave 1. Vá até a seção Chave de API, a segunda da página 2. A chave aparece mascarada. Clique no ícone de olho para revelá-la, ou use direto o botão de copiar para levar o valor para a área de transferência :::success Use esse valor no header api_access_token das suas requisições à API do Cloud Chat. ::: Etapa 3 — Gerar uma chave nova (opcional) Faça isso só quando precisar rotacionar a chave — por exemplo, se desconfiar de vazamento. 1. Na seção Chave de API, clique no botão de setas circulares, à esquerda do botão de copiar 2. Confirme na janela que abrir :::warning A chave antiga é invalidada na hora. Qualquer integração que ainda use o valor anterior para de funcionar até ser atualizada com a chave nova. ::: Observações :::warning A chave de API é pessoal e por usuário: ela dá acesso aos dados da sua conta, com as suas permissões. Trate como senha — não compartilhe publicamente e não faça commit dela em repositórios. ::: - Não encontrou a seção Chave de API? Em contas que usam apenas o painel da ClaudIA, essa seção não aparece — só a do Servidor MCP. Fale com o seu time de atendimento da Cloud Humans. - Servidor MCP é outra coisa. Ele fica na mesma página, mas não usa chave nenhuma: a autorização acontece no login da sua própria conta Cloud Humans. O passo a passo está no guia de conexão do MCP. - Para usar a chave numa extração de dados em lote: Como extrair dados em lote via API (Data Extract API)

Última atualização em Sep 17, 2026

Payload do Webhook do CloudChat

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Payload enviado pelo Webhook do CloudChat Quando uma automação dispara um webhook, ela faz um POST HTTP para a URL configurada, enviando um JSON com as seguintes informações principais: Estrutura do payload (JSON) CampoDescriçãoeventO tipo de evento que disparou o webhook (ex: message_created, conversation_created, etc.)contentO conteúdo da mensagemmessage_typeTipo da mensagem (incoming, outgoing, etc.)conversationObjeto com dados da conversa, incluindo id, status, etc.senderObjeto com dados do remetente (contato), incluindo id, name, email, phone_number, etc.accountObjeto com dados da conta, incluindo idinboxObjeto com dados da inbox/canalcontactDados do contato associado Exemplo prático (baseado no código) Como visto no exemplo de integração com Rasa: chatwoot / implementation-examples / rasa-agent-bot-demo / rasa_flask_router.py @app.route('/rasa', methods=['POST']) def rasa(): data = request.get_json() message_type = data['message_type'] message = data['content'] conversation = data['conversation']['id'] Eventos suportados para webhooks Conforme definido no modelo: chatwoot / chatwoot / app / models / webhook.rb ALLOWED_WEBHOOK_EVENTS = %w[conversation_status_changed conversation_updated conversation_created contact_created contact_updated message_created message_updated webwidget_triggered inbox_created inbox_updated conversation_typing_on conversation_typing_off].freeze Resumo do JSON típico que chega no seu endpoint: webhook_payload_example.json { "event": "message_created", "message_type": "incoming", "content": "Olá, preciso de ajuda!", "id": 12345, "conversation": { Em resumo: O webhook envia um POST com JSON contendo os dados do evento, da conversa, do contato/remetente, da conta e da inbox, junto com o conteúdo da mensagem e o tipo de mensagem. Isso permite que o sistema externo (que recebe o webhook) saiba exatamente o que aconteceu e tome a ação adequada.

Última atualização em Sep 23, 2026

Como criar artigos na Central de Ajuda via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 Sep 23, 2026

Disparar mensagem proativa por API (WhatsApp e Widget Web)

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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). - O endereço da sua instância do Cloud Chat, que é o domínio que aparece no navegador quando você acessa a plataforma (ex.: cloudchat5.cloudhumans.com). As chamadas devem ir para esse endereço. Um endereço de outra instância responde 401. - O token vale só para a instância em que foi gerado. Se gerar um novo, o anterior deixa de funcionar na hora, então atualize em todos os sistemas que o usam. - 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 :::warning Envie o token somente no cabeçalho api_access_token, só o valor, sem aspas nem o prefixo Bearer. Não adicione um cabeçalho Authorization, porque ele faz a chamada ser recusada com 401. ::: 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://{SEU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation {SEU_DOMINIO} é o endereço da sua instância (ex.: cloudchat5.cloudhumans.com). { "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". Se o template usa variáveis numeradas ({{1}}, {{2}}), os campos são "1" e "2". Não coloque esses campos dentro de um objeto template_params. - 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 ou CX Engineer; com token de agente, títulos inexistentes são ignorados. Detalhes em Como enviar mensagem proativa pelo WhatsApp via API. WhatsApp: limite de requisições O endpoint de WhatsApp aceita até 200 requisições por minuto por chave de API. Acima disso, a resposta é 429 com o cabeçalho Retry-After (segundos até liberar). Aguarde esse tempo antes de reenviar e, em lotes grandes, distribua os disparos ao longo dos minutos. Uma requisição que recebeu 429 não foi processada, então reenviá-la não duplica a mensagem. Corpo da resposta, demais cabeçalhos e como o limite é contado estão em Quais são os limites de requisição (rate limits) das rotas da API do Cloud Chat?. 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://{SEU_DOMINIO}/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 Oct 21, 2026

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

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: 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 ou supervisor do Cloud Chat. Para pegar o seu: clique no seu avatar (canto inferior esquerdo) → Configurações de Perfil e role até a seção "Token de acesso" — o campo vem mascarado, use os botões ao lado para revelar ou copiar. Com token de agente o endpoint retorna 401/403. Usuários com acesso somente à ClaudIA não veem essa seção. Seção "Token de acesso" nas Configurações de Perfil - O account_id da sua conta — é o número logo após /accounts/ na URL do Cloud Chat. Exemplo: em https://cloudchat.cloudhumans.com/app/accounts/1/dashboard, o account_id é 1. - Uma campanha de WhatsApp já disparada, cujo template tenha botões de Quick Reply. - O display_id da campanha — veja a seção abaixo "Como descobrir o ID da campanha". Como descobrir o ID da campanha (display_id) A interface do Cloud Chat não exibe o ID da campanha (ele não aparece na listagem nem na URL). Para descobrir, use o endpoint de listagem de campanhas com o mesmo token: curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?query=TITULO_DA_CAMPANHA&campaign_type=one_off' \ -H 'api_access_token: SEU_API_ACCESS_TOKEN' - query busca pelo título da campanha (o mesmo que aparece na listagem da interface) e campaign_type=one_off restringe às campanhas únicas — juntos, normalmente devolvem direto a campanha desejada. - Para listar todas as campanhas (extração em massa), chame sem query, paginando: curl -s 'https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/campaigns?page=1&per_page=100' \ -H 'api_access_token: SEU_API_ACCESS_TOKEN' - A resposta vem paginada no formato { "data": [...], "meta": {...} } — default 20 por página, per_page máximo 100; itere page de 1 até meta.total_pages. - O campo id de cada campanha retornada já é o display_id que você usa no endpoint de respostas — não confunda com nenhum id interno. { "id": 22081, "title": "Minha campanha", "campaign_status": "completed", "campaign_type": "one_off" } 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' Dica: esse curl pode ser importado direto no Postman (File → Import → Raw text) — basta trocar o token e os ids. 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 (created_at é um timestamp Unix, em segundos). - 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". O summary sempre considera a campanha inteira, independente da página. - meta — paginação: current_page, total_count (total de respostas da campanha), total_pages. Atenção: total_pages depende do per_page usado. Para exportar todas as respostas, use per_page=500 e itere page de 1 até total_pages. Erros comuns - 401 Unauthorized — token inválido, expirado/regenerado, ou o header api_access_token não foi enviado. - 401/403 — o token é de um usuário agente (o endpoint exige administrador ou supervisor na conta). - 404 Not Found — campanha não encontrada: ou o número usado não é o display_id (veja "Como descobrir o ID da campanha"), ou a campanha pertence a outra conta que não a do {ACCOUNT_ID} da URL. - responses vazio com a campanha certa — o template não tinha botões Quick Reply, ninguém tocou em botão ainda, ou a campanha foi disparada antes do lançamento do recurso (sem dados retroativos). 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). - As contagens são por toque, não por contato único. Se o mesmo contato tocar em mais de um botão (ou no mesmo botão mais de uma vez), cada toque vira uma resposta e entra no summary. Para métricas por contato único, deduplique por sender.id no seu lado. - 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 Sep 23, 2026

Como criar, atualizar e deletar contatos via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você precisa criar, consultar, atualizar ou excluir um contato específico no Cloud Chat via API - Você quer alterar apenas alguns campos de um contato sem apagar os demais - Você está integrando o Cloud Chat a outro sistema que gerencia contatos individualmente Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID :::info Este artigo cobre operações em um contato por vez pelo endpoint REST padrão. Para importar ou atualizar vários contatos de uma vez, use Como importar contatos em massa via API. Para apenas ler dados, veja Como consultar contatos, tickets e mensagens em tempo real via API. ::: Permissões por operação | Operação | Permissão mínima | | --- | --- | | Criar, consultar, atualizar | Qualquer perfil de agente | | Deletar contato | Administrador | | Consultar por e-mail (/contacts/email) | Administrador | :::warning Se você consegue criar e atualizar mas recebe 403 Forbidden ao deletar, seu token é de agente. Use um token de usuário administrador para excluir contatos. ::: Criar contato POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts O body é um objeto JSON simples — pelo menos um entre email, phone_number ou identifier: { "name": "Maria Silva", "email": "[email protected]", "phone_number": "+5511999998888", "identifier": "CRM-123", "additional_attributes": { "company_name": "Acme" }, "custom_attributes": { "plano": "premium" } } - Opcional: envie inbox_id (e source_id) para já vincular o contato a uma caixa de entrada. - Resposta 200 com o contato criado, incluindo o id. Consultar contato Por id: GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} Por e-mail exato (requer administrador): GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/[email protected] :::info Para buscar por texto livre (nome, telefone, empresa, parcial), use o endpoint de busca — ver Como consultar contatos, tickets e mensagens em tempo real via API, seção "Buscar contatos por texto livre". ::: Atualizar contato PUT https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} Envie apenas os campos que quer alterar: { "name": "Maria S. Silva", "custom_attributes": { "plano": "enterprise" } } :::success Diferente do import em massa com upsert: true, o update individual não apaga os campos que você não enviar. ::: - custom_attributes são mesclados com os já existentes (não zeram os demais). - Para remover um atributo customizado específico: POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/destroy_custom_attributes { "custom_attributes": ["plano"] } - Resposta 200 com o contato atualizado. Deletar contato DELETE https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID} - Requer usuário administrador. - Resposta 200 em caso de sucesso. :::warning Se o contato estiver online no momento da chamada, a exclusão é bloqueada e retorna 422. Tente novamente quando ele não estiver ativo. ::: :::info Para remover apenas tags de contatos (sem excluir o contato), veja Como remover tags de contatos em massa via API. ::: Exemplo de requisição (atualizar) 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 '{ "name": "Maria S. Silva" }' Erros comuns | Status | Significado | | --- | --- | | 403 Forbidden | Token sem permissão (deletar exige administrador) | | 422 Unprocessable Entity | Dados inválidos, ou tentativa de deletar contato online | | 404 Not Found | Contato não encontrado na conta | 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 - Importar vários contatos de uma vez: Como importar contatos em massa via API - Importar 1 contato de sistema externo (upsert, preserva campos): Como importar um contato individual via API - Juntar contatos duplicados: Como mesclar (merge) contatos 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 Sep 23, 2026

Como mesclar (merge) contatos via API

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você tem o mesmo cliente duplicado em dois contatos (ex.: entrou por canais diferentes) e quer juntar em um só - Você está deduplicando a base de contatos via integração - Você quer consolidar histórico (conversas, mensagens, notas) de dois contatos em um único registro Pré-requisitos - API Key em mãos — ver Como encontrar sua API Key no Cloud Chat - CLOUDCHAT_DOMAIN e ACCOUNT_ID - Os dois ids de contato que serão mesclados — para localizá-los, use a busca em Como consultar contatos, tickets e mensagens em tempo real via API Endpoint POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge Headers | Header | Valor | | --- | --- | | content-type | application/json | | api_access_token | Seu token de API | Corpo da requisição { "base_contact_id": 100, "mergee_contact_id": 250 } | Campo | Descrição | | --- | --- | | base_contact_id | Contato que permanece (vencedor da mesclagem) | | mergee_contact_id | Contato que será absorvido e excluído | Como funciona Ao mesclar: - Todas as conversas, mensagens, notas, caixas de entrada (contact_inboxes), respostas de CSAT e eventos de campanha do contato absorvido passam para o contato-base. - Nos campos de perfil (name, email, phone_number, identifier, additional_attributes, custom_attributes), o contato-base vence. Onde o base estiver vazio, o valor do contato absorvido é aproveitado. - O contato absorvido (mergee_contact_id) é excluído ao final. - Resposta 200 com o contato-base resultante. :::error A mesclagem é irreversível. Fica registrada uma auditoria interna, mas não existe "desfazer". Confirme qual id é o base_contact_id (o que permanece) antes de chamar — inverter os dois exclui o contato errado. ::: Exemplo de requisição curl -X POST \ 'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge' \ --header 'content-type: application/json' \ --header 'api_access_token: SEU_TOKEN' \ --data '{ "base_contact_id": 100, "mergee_contact_id": 250 }' Erros comuns | Status | Significado | | --- | --- | | 404 Not Found | Um dos contatos (base_contact_id ou mergee_contact_id) não existe na conta | | 422 Unprocessable Entity | Payload inválido (falta base_contact_id ou mergee_contact_id) | Observações - Criar, atualizar e deletar contatos individualmente: Como criar, atualizar e deletar contatos via API - Localizar os ids dos contatos: Como consultar contatos, tickets e mensagens em tempo real 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 Sep 23, 2026

Quais são os limites de requisição (rate limits) das rotas da API do Cloud Chat?

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você integra sistemas externos com a API do Cloud Chat e precisa planejar o volume de chamadas sem ser bloqueado. - Você recebeu um erro 429 (Too Many Requests) e quer entender o motivo. - Você está importando contatos em massa, disparando conversas proativas de WhatsApp, gerando relatórios ou extrações de dados via API e precisa saber o ritmo seguro de chamadas. Sobre este artigo Algumas rotas da API do Cloud Chat têm um limite de requisições por minuto (rate limit). Esse limite existe pra proteger a estabilidade da plataforma em operações mais pesadas, como importação em massa de contatos, geração de relatórios e disparo de mensagens proativas. A maior parte das rotas da API não tem limite específico configurado — os limites abaixo se aplicam apenas às rotas listadas na tabela. Se você ainda não tem sua chave de API em mãos, veja Como encontrar sua API Key no Cloud Chat. Limites por rota A tabela abaixo mostra o limite de requisições por minuto de cada rota: | Rota | Limite / minuto | | --- | --- | | contacts/external_import | 500 | | conversations/create_proactive_whatsapp_conversation | 200 | | contacts/bulk_create | 100 | | contacts/search e contacts/search/count | 40 | | v2/reports | 20 | | v2/data_extracts | 20 | | integrations/hooks/{id}/process_event (eventos do Copilot) | 20 | | conversations/{id}/transcript | 10 | | messages/{id}/transcription | 10 | :::info O limite de integrations/hooks/{id}/process_event vale apenas para os eventos do Copilot (reformular, corrigir ortografia, resumir tom, expandir, entre outros). Eventos legados de sugestão de resposta, resumo ou label não passam por esse limite. ::: Como o limite é aplicado - Janela fixa de 1 minuto. O contador reinicia a cada minuto corrido — não é uma janela deslizante. - Chave de contagem. Na maioria das rotas, o limite é contado por chave de API (api_access_token). Em rotas que também podem ser chamadas pelo painel do Cloud Chat (create_proactive_whatsapp_conversation, process_event, contacts/search/contacts/search/count e messages/{id}/transcription), o limite conta tanto pela chave de API quanto pela sessão logada no painel — ou seja, cada agente ou token tem seu próprio contador. - Não é por IP. O limite não depende do endereço de IP de origem, apenas da chave de API (ou da sessão) usada na chamada. O que acontece ao exceder o limite Ao ultrapassar o limite de uma rota, a API responde com o status 429 e o corpo: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } A resposta também inclui estes headers: | Header | Descrição | | --- | --- | | X-RateLimit-Limit | Limite configurado pra essa rota. | | X-RateLimit-Remaining | Sempre 0 numa resposta 429. | | X-RateLimit-Reset | Timestamp (epoch) de quando a janela reinicia. | | Retry-After | Segundos até poder tentar novamente. | :::warning Sempre respeite o Retry-After antes de tentar de novo. Fazer uma nova tentativa imediata numa rota já limitada só prolonga o bloqueio e não adianta a entrega. ::: Observações - A maioria das rotas da API não tem rate limit específico — os limites acima cobrem só as rotas listadas nesta tabela. - Se você precisa de um limite maior pra alguma dessas rotas em um caso de uso legítimo (por exemplo, uma migração pontual de grande volume de contatos), fale com o time de suporte da Cloud Humans antes de rodar a operação. - Pra importação em massa de contatos, veja também Como importar contatos em massa via API. - Pra uma visão geral de autenticação e operação de dados via API, veja o Guia Mestre — Como acessar e operar dados do Cloud Chat via API.

Última atualização em Sep 23, 2026

Como conectar o MCP Server da Cloud Humans no Claude

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você quer usar o Claude conectado à Cloud Humans para gerenciar a base de conhecimento da ClaudIA, testar respostas e configurar o Cloud Chat conversando - A sua empresa usa o Claude Team ou Enterprise e o conector precisa ser aprovado pelo time de segurança antes de alguém conseguir usar :::info O MCP Server da Cloud Humans está em Beta. Se algo não funcionar como esperado, fale com o seu time de atendimento da Cloud Humans. ::: Pré-requisitos - Uma conta Cloud Humans ativa. O login do conector usa o mesmo e-mail e senha que você já usa na plataforma. Pelo MCP, o login é sempre com e-mail e senha, mesmo que a sua empresa use SSO para entrar no Cloud Chat - Um plano do Claude que aceite conectores personalizados (veja a tabela abaixo) - Nenhum token ou chave de API. Não é preciso gerar, pedir à Cloud Humans nem colar credencial em lugar nenhum: a autorização acontece na tela de login Sobre este artigo O MCP Server da Cloud Humans é o endereço que dá ao Claude acesso às ferramentas da Cloud Humans. Depois de conectado, você conversa normalmente e o Claude consegue consultar e alterar o que você já pode consultar e alterar na plataforma. O endereço do servidor é: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp :::warning Esse endereço não é uma página para abrir no navegador. Se você colar a URL na barra de endereços, vai ver a mensagem {"detail":"missing_token"}. Isso é esperado e não é erro. O endereço só funciona quando é adicionado como conector dentro do Claude, que é o que os passos abaixo explicam. ::: Este artigo trata de conectar o Claude à Cloud Humans. Se o que você procura é o caminho inverso, conectar os agentes da ClaudIA a servidores MCP externos, veja Como configurar servidores MCP para os agentes da ClaudIA. Antes de começar: qual é o seu plano do Claude? O caminho muda conforme o plano. Para descobrir o seu, abra o Claude e clique no seu nome no canto inferior esquerdo. | Plano do Claude | Quem adiciona o conector | Precisa de aprovação? | Por onde começar | |---|---|---|---| | Team ou Enterprise | O Owner da organização no Claude | Sim. Normalmente o time de segurança ou de TI aprova antes | Etapa 1 | | Pro ou Max | Você mesmo | Não | Etapa 2B | | Free | Você mesmo | Não | Etapa 2B. O plano Free aceita apenas 1 conector personalizado | :::info Como saber quem é o Owner? No Claude Team ou Enterprise, o Owner é quem administra a conta da empresa no Claude, geralmente alguém de TI ou de segurança. Se você não sabe quem é, pergunte ao time que liberou o Claude para você. ::: O caminho completo para Team e Enterprise tem quatro etapas, e só a primeira depende de outra área: 1. Aprovação: o time de segurança avalia e aprova o conector 2. Cadastro na organização: o Owner adiciona o conector uma única vez para toda a empresa 3. Conexão individual: cada pessoa conecta com a própria conta Cloud Humans 4. Teste Passo a passo Etapa 1 — Pedir a aprovação do time de segurança (Team e Enterprise) 1. Copie a mensagem abaixo, ajuste o que estiver entre colchetes e envie para o time de segurança (ou para o Owner do Claude na sua empresa) Olá! Precisamos liberar no Claude [Team/Enterprise] o conector da Cloud Humans, fornecedora da nossa operação de atendimento (ClaudIA e Cloud Chat). O que é: um conector personalizado (servidor MCP remoto) operado pela Cloud Humans. Endereço: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp Pontos para a avaliação: - Nada é instalado nas máquinas e não é preciso abrir regra de firewall do nosso lado. - Autenticação por OAuth, com login individual na Cloud Humans. Não existe chave de API nem segredo compartilhado. - Cada pessoa conecta com a própria conta e tem exatamente as mesmas permissões que já tem na plataforma da Cloud Humans. O conector não amplia acesso. - A sessão vale 30 dias a partir do login. Depois disso, é preciso fazer login de novo. - O Owner pode remover o conector da organização a qualquer momento, cortando o acesso de todos. Respostas de segurança: https://cloudchat.cloudhumans.com/hc/cloud-chat/articles/1792005888-mcp-da-cloud-humans-o-que-o-time-de-seguranca-precisa-saber-para-aprovar Passo a passo no Claude: https://cloudchat.cloudhumans.com/hc/cloud-chat/articles/1787004926-como-conectar-o-mcp-server-da-cloud-humans-no-claude Quem vai usar: [nomes ou time] Para quê: [ex.: manter a base de conhecimento da ClaudIA e testar respostas] 2. Junto com a mensagem, mande o artigo MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar. Ele responde o que costuma ser perguntado nessa avaliação 3. Com a aprovação, siga para a Etapa 2A (feita pelo Owner) :::info Se o seu time de segurança precisar de um questionário completo da Cloud Humans como fornecedora (LGPD, criptografia, continuidade, certificações), peça ao seu time de atendimento da Cloud Humans. Temos as respostas padronizadas e as evidências prontas. ::: Etapa 2A — O Owner adiciona o conector na organização (Team e Enterprise) Esta etapa é feita uma única vez, pelo Owner, e vale para toda a empresa. 1. No Claude, abra Configurações da organização (Organization settings) > Conectores (Connectors) 2. Clique em Adicionar (Add), passe o mouse em Personalizado (Custom) e selecione Web 3. Em Nome, escreva Cloud Humans 4. Em URL, cole o endereço do servidor: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp 5. Clique em Continuar (Continue) e revise a autenticação 6. Não preencha OAuth Client ID nem OAuth Client Secret. O servidor da Cloud Humans registra o Claude sozinho, então esses campos ficam em branco 7. Clique em Adicionar (Add) :::success Pronto. O conector Cloud Humans passa a aparecer para todas as pessoas da organização, com a etiqueta Personalizado (Custom). Ninguém ganha acesso à Cloud Humans só por isso: cada pessoa ainda precisa fazer o próprio login na Etapa 3. ::: :::warning Tem que ser conector personalizado. A Cloud Humans não aparece no diretório de conectores prontos do Claude. Se você procurar por ela ali, não vai encontrar. ::: Etapa 2B — Adicionar o conector você mesmo (Pro, Max e Free) 1. No Claude, abra Personalizar (Customize) > Conectores (Connectors) 2. Clique em + Adicionar e depois em Adicionar conector personalizado (Add custom connector) 3. Em Nome, escreva Cloud Humans 4. Em URL, cole o endereço do servidor: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp 5. Deixe OAuth Client ID e OAuth Client Secret em branco e clique em Adicionar (Add) Etapa 3 — Conectar com a sua conta Cloud Humans (todos os planos) Cada pessoa que vai usar faz esta etapa uma vez, com a própria conta. 1. No Claude, abra Personalizar (Customize) > Conectores (Connectors) 2. Encontre Cloud Humans na lista. Em Team e Enterprise, ele aparece com a etiqueta Personalizado (Custom) 3. Clique em Conectar (Connect) 4. Vai abrir uma tela de login da Cloud Humans. Entre com o seu e-mail e senha da Cloud Humans, os mesmos da plataforma 5. Depois do login, o navegador volta sozinho para o Claude e o conector aparece como conectado :::info Você tem cerca de 10 minutos para concluir o login depois de clicar em Conectar. Se demorar mais que isso, a tela expira: clique em Conectar de novo e recomece. ::: Etapa 4 — Testar Abra uma conversa nova e peça algo simples, como: Liste os conteúdos da minha base de conhecimento na Cloud Humans. Se o Claude responder com os seus conteúdos, está tudo certo. Para ideias do que pedir, veja Utilizando o MCP da Claudia e Como utilizar o MCP do Cloud Chat. :::info Se a sua conta tem acesso a mais de uma conta ou projeto na Cloud Humans, diga na conversa qual deles você quer usar. Sem isso, o Claude não tem como adivinhar e vai pedir que você especifique. ::: Perguntas do time de segurança As respostas sobre autenticação, permissões, alteração de dados, revogação e destino dos dados estão reunidas em MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar. É esse o link para mandar ao time de segurança. Problemas comuns | O que aparece | Causa | O que fazer | |---|---|---| | {"detail":"missing_token"} | O endereço foi aberto no navegador | Adicione como conector personalizado (Etapa 2A ou 2B) | | Não encontro a opção de adicionar conector personalizado | No Team e no Enterprise, só o Owner adiciona | Peça ao Owner (Etapa 1) | | Não vejo a Cloud Humans na lista de conectores | O Owner ainda não adicionou na organização | Confirme com o Owner se a Etapa 2A foi feita | | A tela de login expirou | Passaram mais de 10 minutos | Clique em Conectar de novo | | O Claude pediu login de novo | Passaram 30 dias desde o login | Repita a Etapa 3 | | O Claude diz que não tem permissão para algo | O seu perfil na Cloud Humans não tem essa permissão | Peça a um administrador da sua conta Cloud Humans | Observações - Usa outro assistente? Veja ChatGPT, Gemini Enterprise e Microsoft Copilot. Em clientes como Cursor, VS Code e Claude Code, o endereço e o login são os mesmos - Uma aprovação vale para todos. Em Team e Enterprise, o Owner adiciona o conector uma vez. Quem entrar depois na empresa só precisa fazer a Etapa 3

Última atualização em Oct 14, 2026

Onde cadastrar um webhook no Cloud Chat (Integrações x Automação)

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você quer registrar uma URL para receber eventos do Cloud Chat - Você cadastrou um webhook e nada chega no seu endpoint São dois caminhos diferentes Escolher o caminho errado é a causa mais comum de webhook que não dispara. 1. Webhook de integração (o cadastro padrão) :::warning Hoje o atalho para Webhooks não aparece na tela Configurações > Integrações. O cadastro continua funcionando: você acessa a tela direto pelo endereço, como abaixo. ::: 1. Entre no Cloud Chat com um usuário Administrador. 2. Na barra de endereço do navegador, mantenha tudo até o número da conta (o que vem depois de /accounts/) e troque o resto por /settings/integrations/webhook. Exemplo: .../app/accounts/123/dashboard vira .../app/accounts/123/settings/integrations/webhook. 3. Clique em Adicionar novo Webhook. Você informa: - URL do Webhook — o endpoint que vai receber o POST - Eventos — quais assinar: conversa criada, conversa atualizada, status de conversa alterado, mensagem criada, mensagem atualizada, contato criado, contato atualizado, widget de chat aberto pelo usuário Dá para cadastrar vários webhooks na mesma conta, cada um com sua URL e sua lista de eventos. Cada URL só pode ser cadastrada uma vez por conta: para assinar mais eventos no mesmo endpoint, edite o webhook que já existe. :::info Esse cadastro exige perfil Administrador. Com outro perfil, a tela de webhooks não abre. ::: 2. Automação que dispara webhook Configurações > Automação > Adicionar regra de automação Aqui você não cadastra um webhook: cria uma regra com condições e escolhe a ação Enviar Evento Webhook, colando a URL no campo da ação. Qual usar? | Você quer... | Use | | --- | --- | | Receber todos os eventos de um tipo (ex.: toda mensagem criada) | Webhook de integração (caminho 1) | | Receber só em casos específicos (ex.: só quando a conversa tem uma tag) | Automação com ação Enviar Evento Webhook | :::info Dá para distinguir os dois no seu endpoint pelo campo event do payload: o webhook de integração envia o nome do evento (ex.: message_created); a automação, com o payload padrão, envia com prefixo (ex.: automation_event.message_created). Se você preencheu um corpo customizado na ação da automação, chega exatamente o JSON que você definiu. ::: :::warning Um webhook de integração com "Mensagem criada" dispara em todas as mensagens da conta: de entrada e de saída, de todos os canais, incluindo notas privadas. Mensagens de atividade (as de sistema, como "conversa atribuída a…") não disparam. Se o volume for alto, prefira a automação com condições. ::: Observações - Conversas que o Cloud Chat apenas espelha da ClaudIA (atendidas em outro helpdesk) não disparam webhook, em nenhum dos dois caminhos de integração. - Caixas de entrada do tipo API têm um campo de URL de webhook próprio, nas configurações da caixa. Ele recebe os eventos daquela caixa, independentemente do cadastro do caminho 1. - Referência completa dos payloads: docs.cloudhumans.com/api-reference.

Última atualização em Oct 05, 2026

O que significa o aviso "Falha no envio do webhook" nas mensagens

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você viu o aviso "Falha no envio do webhook" nas mensagens de um ticket e quer saber o que significa - Você quer saber se esse aviso afeta o atendimento ou o envio de mensagens O que é esse aviso O aviso aparece quando uma regra de automação da sua conta tenta enviar dados para um endpoint externo (webhook) e esse endpoint não confirma o recebimento. É comum em contas que usam automações do tipo "Mensagem recebida" ou "Ticket resolvido" para mandar uma cópia dos dados para um sistema próprio (planilha, script, ERP, ferramenta de BI). :::info O aviso não afeta o atendimento. O envio e o recebimento das mensagens (inclusive no WhatsApp) continuam funcionando normalmente, e a ClaudIA também não é impactada. O que falha é apenas a integração paralela que deveria receber esses dados. ::: Como investigar 1. Vá em Configurações → Automação e identifique as regras que enviam dados para um endpoint externo. 2. Confira a URL de destino de cada uma. 3. Teste essa URL fora do Cloud Chat: ela precisa responder confirmando o recebimento. Se ela redireciona (resposta 302) ou passa a exigir login, o envio é considerado falha. Caso comum — Google Apps Script: a implantação precisa estar como "Qualquer pessoa tem acesso", executando como o dono do script. Quando a implantação é alterada (ou o link antigo passa a exigir login), o endpoint começa a redirecionar e todas as tentativas falham — às vezes por meses, sem ninguém notar. Observações - Quem administra o endpoint (seu time ou quem cuida do script/integração) é quem precisa corrigir a implantação — o ajuste não é no Cloud Chat. - Se a integração não é mais usada, o caminho mais limpo é desativar a regra de automação que faz o envio, e o aviso deixa de aparecer.

Última atualização em Sep 23, 2026

Como Montar Integrações entre Sistemas com Automações e Webhook

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Resumo O Cloud Chat possui uma funcionalidade de "Enviar Evento Webhook". Através dela nós conseguimos construir integrações com qualquer sistema que consiga gerar um Webhook. Quando o sistema não tem uma estrutura para criação de Webhook, somente API, é possível utilizar um intermediador (exemplos: n8n, Zapier, Make, Plugga...) para criar um Webhook e construir um fluxo de integração com o sistema alvo como por exemplo Hubspot, Jira e outros. - obs: as vezes é necessário construir um fluxo de "enriquecimento" dos dados que vieram do webhook utilizando uma API (por exemplo - IMPORTANTE: Esse tipo de integração costuma ser criado para integrações "de via única", ou seja, sem atualização de um campo específico. A complexidade de uma integração "de duas vias" é maior e geralmente vai exigir uma necessidade alta de uso de Webhook + API Cloud Chat + API/integração nativa do sistema alvo Existem outras duas maneiras de construir essas integrações, porém possuem um nível de complexidade mais alto e tem objetivos diferentes: - Utilizar nossa API para puxar todos os dados de conversas, todos os dias e alimentar um datalake ou banco de dados: Objetivo costuma ser analítico ou de registro / consolidação de informações - Lado negativo: Dado não vai ser criado real-time. Portanto pode ser ruim para Operação utilizar (exemplo: triagem em N2 / tech) - Utilizar o Fluxo Controlado ao invés do intermediador como n8n, zapier ou make: Vai funcionar de maneira muito semelhante - Lado negativo: Só vai funcionar para atendimentos que passarem pela ClaudIA Detalhamento Payload enviado pelo Webhook do Cloud Chat Quando uma automação dispara um webhook, ela faz um POST HTTP para a URL configurada, enviando um JSON com as seguintes informações principais: Estrutura do payload (JSON) - event - O tipo de evento que disparou o webhook (ex: message_created, conversation_created, etc.) - content - O conteúdo da mensagem - message_type - Tipo da mensagem (incoming, outgoing, etc.) - conversation - Objeto com dados da conversa, incluindo id, status, etc. - sender - Objeto com dados do remetente (contato), incluindo id, name, email, phone_number, etc. - account - Objeto com dados da conta, incluindo: - idinbox - Objeto com dados da inbox/canal - contact - Dados do contato associado Exemplo prático (baseado no código) Como visto no exemplo de integração com Rasa: @app.route('/rasa', methods=['POST']) def rasa(): data = request.get_json() message_type = data['message_type'] message = data['content'] conversation = data['conversation']['id'] Resumo do JSON típico que chega no seu endpoint: { "event": "message_created", "message_type": "incoming", "content": "Olá, preciso de ajuda!", "id": 12345, "conversation": { "id": 678, "status": "open", "channel": "web_widget", "contact_inbox": { ... } }, "sender": { "id": 90, "name": "João Silva", "email": "[email protected]", "phone_number": "+5511999999999" }, "account": { "id": 1 }, "inbox": { "id": 10, "name": "Website Widget" } } O que fazer caso o Webhook não contenha o dado que você precisa Nessa situação você vai precisar utilizar os "id"s gerados (ex.: inbox.id, conversation.id, sender.id) para fazer uma chamada de API no Cloud Chat e coletar essa informação para poder enviar para o outro sistema. :::info O conversation.id que chega no webhook é o número do ticket que aparece na interface (ex.: #678) — o mesmo número que você usa nas URLs das APIs de conversas. ::: Em resumo: O webhook envia um POST com JSON contendo os dados do evento, da conversa, do contato/remetente, da conta e da inbox, junto com o conteúdo da mensagem e o tipo de mensagem. Isso permite que o sistema externo (que recebe o webhook) saiba exatamente o que aconteceu e tome a ação adequada.

Última atualização em Sep 23, 2026

Como integrar o Jira ao Cloud Chat

:::info A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá. ::: Quando usar - Você quer criar issues no Jira direto de uma conversa no Cloud Chat, sem trocar de ferramenta - Você quer vincular uma conversa a um issue já existente no Jira pra ter rastreabilidade - Você precisa que o time de produto/engenharia receba contexto direto de tickets de suporte Pré-requisitos - Conta no Jira Cloud (Atlassian) - Usuário no Jira com permissão para criar issues nos projetos desejados - API Token do Jira — gerado em https://id.atlassian.com/manage-profile/security/api-tokens - Estar logado como administrador no Cloud Chat para configurar a integração :::warning A integração funciona exclusivamente com Jira Cloud. Jira Server e Jira Data Center não são suportados. ::: Sobre este artigo A integração com o Jira permite que agentes criem, vinculem e desvinculem issues do Jira diretamente de uma conversa no Cloud Chat. Elimina a necessidade de alternar entre ferramentas e garante rastreabilidade entre atendimentos e tickets de produto/engenharia. Configurar a integração Etapa 1 — Acessar Integrações 1. No menu lateral do Cloud Chat, vá em Configurações → Integrações 2. Clique em Jira e depois em Conectar Etapa 2 — Preencher os dados de conexão Preencha os campos: - URL do site Jira — ex: https://suaempresa.atlassian.net - E-mail — do usuário Jira que será usado nas chamadas à API - API Token — gerado conforme pré-requisitos Clique em Salvar. :::success A integração fica disponível para todos os agentes da conta. ::: Criar um issue a partir de uma conversa Etapa 1 — Abrir o painel do Jira 1. Abra uma conversa no Cloud Chat 2. No cabeçalho da conversa, clique no ícone do Jira 3. Clique em Criar issue Etapa 2 — Preencher campos obrigatórios Campos marcados com *: - Título — resumo do issue - Projeto — projeto do Jira onde o issue será criado - Tipo de issue — aparece após selecionar o projeto (Bug, Task, Story) Etapa 3 — Preencher campos opcionais - Descrição — detalhes adicionais - Prioridade — nível de urgência - Responsável — a quem o issue será atribuído Etapa 4 — Criar Clique em Criar. :::success O issue é criado no Jira com um link para a conversa na descrição. ::: Vincular um issue já existente 1. No painel do Jira dentro da conversa, clique em Vincular issue existente 2. Busque pelo título ou chave do issue (ex: PROJ-123) 3. Clique no issue desejado para vinculá-lo :::info Um comentário é adicionado automaticamente no issue do Jira informando que foi vinculado à conversa. ::: Desvincular um issue 1. No painel do Jira dentro da conversa, localize o issue vinculado 2. Clique no ícone de lixeira ao lado do issue :::info Um comentário é adicionado no Jira informando que o vínculo com a conversa foi removido. ::: Perguntas frequentes Um issue pode estar vinculado a mais de uma conversa? Sim. O mesmo issue do Jira pode ser vinculado a múltiplas conversas. Cada vínculo gera um comentário no Jira com o link da conversa correspondente. Quais informações aparecem no card do issue? O card exibe: - Chave do issue (ex: PROJ-123) - Título - Status atual no Jira (To Do, In Progress, Done, etc.) As informações são atualizadas automaticamente toda vez que você abre o painel. Em qual idioma os comentários são adicionados no Jira? Os comentários são adicionados no idioma configurado na conta do Cloud Chat. Quais versões do Jira são compatíveis? :::warning Apenas Jira Cloud. Jira Server e Jira Data Center não são suportados. ::: Observações - Para outros tipos de integração via API (consulta, criação de tickets, etc.): Guia Mestre — Como acessar e operar dados do Cloud Chat via API - Para integrar com HubSpot (workflows e contatos): Como importar contatos via HubSpot e Como enviar mensagem proativa pelo WhatsApp via HubSpot - Para configurar atributos customizados no contexto da conversa (que podem ser usados em integrações): Como criar campos customizados de contatos e conversas

Última atualização em Sep 23, 2026

Criar e acompanhar campanhas pela API pública

Quando usar - Você quer disparar campanhas a partir do seu próprio sistema, sem abrir a tela do Cloud Chat. - Você quer estimar quantos contatos uma audiência alcança antes de gastar envio. - Você precisa acompanhar o estado de uma campanha de forma programática. Pré-requisitos :::error Criar uma campanha dispara o envio. Não existe rascunho intermediário na API, igual à tela. Não use o endpoint de criação para "montar e revisar depois". ::: - Chave de API da conta. Veja Como pegar a sua API key. - Perfil com permissão para campanhas. O perfil de atendente não consegue disparar, na API nem na tela. Como funciona Conferir o alcance antes de enviar Existe um endpoint que resolve a audiência e devolve quantos contatos ela de fato alcança. Use-o antes de criar: é o que evita descobrir o tamanho real do disparo depois que ele já saiu. A confirmação obrigatória de destinatários Na criação, você precisa declarar quantos destinatários espera alcançar. O sistema compara esse número com o que a audiência resolve de verdade: - Se bater, a campanha é criada e entra na fila de envio. - Se divergir, a resposta é um erro de conflito e nada é criado. :::info Essa é a proteção contra o disparo não intencional. Ela existe justamente porque não há rascunho: se a sua audiência cresceu desde a última vez que você a consultou, o pedido falha em vez de enviar para mais gente do que você esperava. ::: Canais disponíveis A criação cobre os três canais que a tela também cobre: WhatsApp, e-mail e web widget. Descobrir templates e variáveis Como quem chama pela API não vê a tela, existem dois endpoints de descoberta: um lista os templates disponíveis na conta e o outro, as variáveis que você pode usar. Use-os para montar o corpo da campanha sem depender de alguém conferir no painel. Consultar o estado depois Há um endpoint de leitura para acompanhar a campanha criada. Observações - A referência completa dos endpoints está na documentação pública da API. As mesmas capacidades também estão disponíveis como ferramenta de MCP. - A campanha criada pela API nasce no mesmo estado que a criada pela tela, e é o mesmo agendador que envia. A API é a porta de entrada, não um caminho de envio diferente. - Existem tetos de destinatários, por audiência bruta e por canal. Se o pedido passar do teto, você recebe erro de validação e nada é criado.

Última atualização em Sep 22, 2026

MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar

Quando usar - Alguém da sua empresa quer conectar um assistente de IA (Claude, ChatGPT, Gemini, Copilot ou outro) à Cloud Humans e o time de segurança ou de TI precisa aprovar antes - Você é do time de segurança e quer entender o que está sendo liberado e como revogar - Você precisa encaminhar a avaliação para a área responsável e quer mandar tudo em um link só :::info O MCP Server da Cloud Humans está em Beta. Se algo não funcionar como esperado, fale com o seu time de atendimento da Cloud Humans. ::: Sobre este artigo O MCP Server da Cloud Humans é um servidor remoto, operado pela Cloud Humans, que permite que um assistente de IA consulte e altere dados da ClaudIA e do Cloud Chat em nome de uma pessoa logada. MCP (Model Context Protocol) é o padrão aberto que Claude, ChatGPT, Gemini e Copilot usam para se conectar a sistemas externos. O endereço do servidor é: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp Este artigo reúne o que costuma ser perguntado na avaliação de segurança. O passo a passo de conexão fica no artigo de cada assistente: | Assistente | Artigo | |---|---| | Claude (Anthropic) | Como conectar o MCP da Cloud Humans no Claude | | ChatGPT (OpenAI) | Como conectar o MCP da Cloud Humans no ChatGPT | | Gemini Enterprise (Google) | Como conectar o MCP da Cloud Humans no Gemini Enterprise | | Microsoft Copilot | Como conectar o MCP da Cloud Humans no Microsoft Copilot | | Outros clientes MCP (Cursor, VS Code, Claude Code etc.) | Use o endereço acima como servidor MCP remoto. O login é o mesmo descrito abaixo | Perguntas do time de segurança Precisa instalar algo ou abrir firewall? Não. Quem se conecta ao servidor é a nuvem do provedor do assistente (Anthropic, OpenAI, Google ou Microsoft), pela internet, em HTTPS. Nada é instalado nas máquinas da sua empresa e nenhuma regra de firewall de entrada é necessária do seu lado. Como é feita a autenticação? Por OAuth 2.0 com PKCE (método S256). Cada pessoa faz login na página de login da Cloud Humans, com o e-mail e a senha que já usa na plataforma. Essa página fica na AWS (Amazon Cognito), no endereço cloudhumans.auth.us-east-1.amazoncognito.com. - Não existe chave de API, token fixo nem segredo compartilhado entre as pessoas - A senha nunca é digitada dentro do assistente. O login acontece na página de login da Cloud Humans, no endereço acima - Pelo MCP, o login é sempre com e-mail e senha. A página não tem opção de SSO, mesmo que a sua empresa use SSO para entrar no Cloud Chat - Assistentes que suportam registro dinâmico de cliente, como o Claude, se registram sozinhos, sem que ninguém precise criar credencial Para quem for configurar manualmente, os endereços de OAuth são: | Item | Endereço | |---|---| | Metadados do servidor de autorização | https://mcp.cloudhumans.com/.well-known/oauth-authorization-server | | Autorização | https://mcp.cloudhumans.com/authorize | | Token | https://mcp.cloudhumans.com/token | | Registro dinâmico de cliente | https://mcp.cloudhumans.com/register | | Revogação | https://mcp.cloudhumans.com/revoke | O que o assistente consegue ver e fazer? Exatamente o que a pessoa conectada já pode ver e fazer na plataforma da Cloud Humans, nem mais, nem menos. - Cada pessoa conecta com a própria conta. O acesso não é compartilhado entre colegas - Um usuário sem perfil de administrador continua sem acesso às configurações de administrador pelo assistente - O assistente só enxerga as caixas de entrada, projetos e contas que o usuário já enxerga no painel O assistente consegue alterar dados? Sim, dentro das permissões da pessoa. Além de consultar, ele consegue, por exemplo, criar e editar conteúdos da base de conhecimento, ajustar configurações e criar campanhas. Três pontos merecem atenção: - Criar uma campanha de WhatsApp dispara o envio na hora. Não dá para cancelar depois, e cada mensagem é cobrada - Testar a ClaudIA pelo assistente consome tokens de LLM cobrados na conta - Agentes da ClaudIA criados pelo assistente ficam sempre como rascunho. A publicação só acontece no painel da ClaudIA :::info O ChatGPT Enterprise e o Microsoft Copilot Studio permitem que o administrador desligue ferramentas específicas antes de liberar o conector. Se a sua empresa quiser um uso só de consulta, essa é a forma de garantir. O artigo de cada assistente mostra onde fica essa opção. ::: Quanto tempo dura o acesso? A conexão vale 30 dias a partir do login, usando ou não. Depois disso, o assistente pede o login de novo. Dentro desse prazo, o acesso é renovado automaticamente a cada hora, sem a pessoa perceber. Como revogar o acesso? | O que fazer | Efeito | |---|---| | O administrador remove o conector no painel de administração do assistente | Corta o acesso de todas as pessoas da empresa | | Remover o usuário da conta na Cloud Humans | Bloqueia na hora o acesso daquela pessoa ao Cloud Chat | | A pessoa desconecta o conector nas configurações do assistente | Encerra a conexão daquela pessoa | :::warning Trocar a senha não encerra a conexão do assistente. Ela continua valendo até completar os 30 dias do login. Para cortar o acesso de alguém, use uma das opções da tabela. ::: Para onde vão os dados consultados? O que as ferramentas devolvem (conteúdos da base, conversas, contatos que a pessoa enxerga) entra na conversa do assistente. A partir daí, esses dados seguem as políticas do contrato da sua empresa com o provedor do assistente (Anthropic, OpenAI, Google ou Microsoft), como acontece com qualquer conector. Fica registro do que foi feito pelo assistente? Sim. As alterações de configuração da ClaudIA ficam registradas com o valor anterior e quem alterou. As decisões do Centro de Melhorias registram se vieram do assistente ou do painel. E o questionário completo de segurança da Cloud Humans? Se o seu time precisa avaliar a Cloud Humans como fornecedora (LGPD, criptografia, continuidade, certificações), peça ao seu time de atendimento da Cloud Humans. Temos as respostas padronizadas e as evidências prontas. Observações - Uma aprovação vale para toda a empresa. Em todos os assistentes corporativos, o administrador adiciona o conector uma vez. Depois disso, cada pessoa só faz o próprio login - Abrir o endereço no navegador mostra {"detail":"missing_token"}. É esperado: o endereço só funciona dentro de um assistente de IA

Última atualização em Oct 14, 2026

Como conectar o MCP da Cloud Humans no ChatGPT

Quando usar - A sua empresa usa o ChatGPT Business, Enterprise ou Edu e você quer usar a Cloud Humans de dentro dele - Você precisa saber o que o administrador do ChatGPT tem que fazer para liberar o conector :::info O MCP Server da Cloud Humans está em Beta, e o suporte completo a MCP do ChatGPT também está em beta do lado da OpenAI. Os nomes dos menus do ChatGPT mudam com frequência: se algum não bater, procure pela opção equivalente. ::: Pré-requisitos - Uma conta Cloud Humans ativa. O login do conector usa o mesmo e-mail e senha da plataforma. Pelo MCP, o login é sempre com e-mail e senha, mesmo que a sua empresa use SSO para entrar no Cloud Chat - ChatGPT Business, Enterprise ou Edu, usado no navegador. O conector não funciona no app de celular - Um administrador ou owner do workspace do ChatGPT, que é quem adiciona e publica o conector Antes de começar: qual é o seu plano do ChatGPT? | Plano | Dá para usar? | Quem adiciona | |---|---|---| | Business | Sim | Só administradores e owners do workspace | | Enterprise ou Edu | Sim | Administradores e owners. Eles podem autorizar outras pessoas a criar, mas só eles publicam | | Pro | Parcial: só ferramentas de consulta | Você mesmo | | Plus e Free | Não. A OpenAI não lista esses planos para servidor MCP personalizado | | O caminho no Business, Enterprise e Edu tem quatro etapas: 1. Aprovação: o time de segurança avalia o conector 2. Cadastro e publicação: o administrador adiciona o conector e publica para o workspace, uma única vez 3. Conexão individual: cada pessoa faz login com a própria conta Cloud Humans 4. Teste Passo a passo Etapa 1 — Pedir a aprovação do time de segurança 1. Envie ao time de segurança (ou ao administrador do ChatGPT) a mensagem abaixo, ajustando o que estiver entre colchetes: Olá! Precisamos liberar no ChatGPT [Business/Enterprise] o conector da Cloud Humans, fornecedora da nossa operação de atendimento (ClaudIA e Cloud Chat). É um servidor MCP remoto, com login individual por OAuth e as mesmas permissões que cada pessoa já tem na Cloud Humans. Nada é instalado e não há chave de API. Endereço: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp Respostas de segurança: https://cloudchat.cloudhumans.com/hc/cloud-chat/articles/1792005888-mcp-da-cloud-humans-o-que-o-time-de-seguranca-precisa-saber-para-aprovar Quem vai usar: [nomes ou time] Para quê: [ex.: manter a base de conhecimento da ClaudIA] 2. Junto com a mensagem, mande o artigo MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar Etapa 2 — O administrador adiciona e publica o conector Esta etapa é feita uma única vez, por um administrador ou owner do workspace. 1. No ChatGPT, abra Plugins 2. Clique no + e selecione Adicionar servidor MCP personalizado (Add custom MCP server) 3. Em Nome, escreva Cloud Humans 4. Em Conexão (Connection), cole o endereço do servidor: https://mcp.cloudhumans.com/openapi/cloudhumans/mcp 5. Em Autenticação, escolha OAuth. Não é preciso preencher Client ID nem Client Secret: o servidor da Cloud Humans registra o ChatGPT sozinho 6. Leia o aviso de risco, marque Entendo e quero continuar (I understand and want to continue) e conclua 7. Faça o login da Cloud Humans quando for pedido e aguarde o ChatGPT listar as ferramentas 8. Publique para o workspace em Configurações do workspace (Workspace settings) > Apps > Rascunhos (Drafts) > Publicar (Publish) :::info Enterprise e Edu: ao publicar, use Configurar ações (Configure Actions) para escolher quais ferramentas ficam ligadas e Configurar acesso (Configure Access) para escolher quais grupos podem usar. Se a empresa quiser um uso só de consulta, desligue aqui as ferramentas que criam ou alteram dados, em especial a de criar campanha. ::: :::warning O ChatGPT congela a lista de ferramentas no momento da publicação. Quando a Cloud Humans lançar ferramentas novas, elas só aparecem depois que o administrador clicar em Atualizar (Refresh) nas configurações do app. Ferramentas novas entram desligadas. ::: Etapa 3 — Conectar com a sua conta Cloud Humans Cada pessoa faz esta etapa uma vez, com a própria conta. 1. No ChatGPT, encontre Cloud Humans na sua lista de apps. Ele aparece com a etiqueta custom 2. Clique para conectar 3. Na tela de login da Cloud Humans, entre com o seu e-mail e senha da Cloud Humans 4. O navegador volta sozinho para o ChatGPT com o conector conectado Etapa 4 — Testar Abra uma conversa nova, digite @, selecione Cloud Humans e peça: Liste os conteúdos da minha base de conhecimento na Cloud Humans. :::info No ChatGPT, o app vale para a mensagem em que você o seleciona. Quando a próxima pergunta precisar buscar dados novos na Cloud Humans, selecione o app com @ de novo. ::: Problemas comuns | O que aparece | Causa | O que fazer | |---|---|---| | Não vejo a opção de adicionar servidor MCP | Só administradores e owners adicionam | Peça ao administrador (Etapa 1) | | Não encontro a Cloud Humans nos meus apps | O app ainda não foi publicado, ou o seu grupo não tem acesso (Enterprise) | Confirme com o administrador a Etapa 2 | | Uma ferramenta que existe na Cloud Humans não aparece | A lista de ferramentas foi congelada na publicação | O administrador clica em Atualizar no app | | O ChatGPT pede para confirmar uma ação | O ChatGPT pede confirmação antes de ações que alteram dados | É esperado. Confira e confirme | | O ChatGPT pediu login de novo | Passaram 30 dias desde o login | Conecte de novo (Etapa 3) | Observações - As permissões são exatamente as da sua conta Cloud Humans. O conector não amplia nem reduz o que você já podia ver e editar - Pesquisa aprofundada (deep research) usa o conector só para consulta, e o modo agente não usa conectores personalizados - Exemplos do que pedir: Utilizando o MCP da Claudia e Como utilizar o MCP do Cloud Chat

Última atualização em Oct 14, 2026

Como conectar o MCP da Cloud Humans no Gemini Enterprise

Quando usar - A sua empresa usa o Gemini Enterprise (Google) e você quer usar a Cloud Humans de dentro dele - Você precisa saber o que o administrador do Google Cloud tem que fazer para liberar o conector :::info No Google, a conexão com servidores MCP de outras empresas acontece no Gemini Enterprise, administrado pelo console do Google Cloud. Este artigo não cobre o app Gemini de uso pessoal. ::: Pré-requisitos - Uma conta Cloud Humans ativa. O login do conector usa o mesmo e-mail e senha da plataforma. Pelo MCP, o login é sempre com e-mail e senha, mesmo que a sua empresa use SSO para entrar no Cloud Chat - Gemini Enterprise nas edições Standard, Plus, Pay-as-you-go ou Frontline - Um administrador do Google Cloud com o papel Discovery Engine Editor (roles/discoveryengine.editor) - O Client ID e o Client Secret da Cloud Humans para o Gemini, que você pede ao seu time de atendimento da Cloud Humans (Etapa 1) :::warning Diferente do Claude, do ChatGPT e do Copilot, o Gemini Enterprise não se registra sozinho no servidor da Cloud Humans. Por isso ele precisa de um Client ID e de um Client Secret, gerados pela Cloud Humans para a sua empresa. ::: Passo a passo Etapa 1 — Pedir a aprovação e as credenciais 1. Envie ao time de segurança (ou ao administrador do Google Cloud) o artigo MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar, junto com o link deste artigo 2. Com a aprovação, peça ao seu time de atendimento da Cloud Humans o Client ID e o Client Secret para o Gemini Enterprise :::info O Client Secret é uma credencial da empresa, não de uma pessoa: ele identifica o Gemini da sua empresa para a Cloud Humans. Cada pessoa continua fazendo o próprio login, com as próprias permissões. Guarde o secret como qualquer outra credencial de integração. ::: Etapa 2 — O administrador cria o conector Esta etapa é feita uma única vez, por um administrador do Google Cloud. 1. No console do Google Cloud, abra o Gemini Enterprise e vá até Repositórios de dados (Data stores) 2. Clique em Criar repositório de dados (Create data store) 3. Procure e selecione Custom MCP Server 4. Em autenticação, escolha OAuth 2.0 e preencha: | Campo | Valor | |---|---| | MCP Server URL | https://mcp.cloudhumans.com/openapi/cloudhumans/mcp | | Authorization URL | https://mcp.cloudhumans.com/authorize | | Token URL | https://mcp.cloudhumans.com/token | | Client ID | O que a Cloud Humans enviou | | Client Secret | O que a Cloud Humans enviou | | Scopes | Deixe em branco | 5. Escolha a região, dê o nome Cloud Humans e clique em Criar (Create) 6. Vincule o repositório de dados ao app do Gemini Enterprise que a sua empresa usa Etapa 3 — Conectar com a sua conta Cloud Humans Cada pessoa faz esta etapa uma vez, com a própria conta. 1. No Gemini Enterprise, faça uma pergunta que envolva a Cloud Humans 2. O Gemini pede autorização. Clique para autorizar 3. Na tela de login da Cloud Humans, entre com o seu e-mail e senha da Cloud Humans 4. O navegador volta para o Gemini com a conexão feita Etapa 4 — Testar Peça ao Gemini: Liste os conteúdos da minha base de conhecimento na Cloud Humans. Problemas comuns | O que aparece | Causa | O que fazer | |---|---|---| | Erro de credencial ao autorizar | Client ID ou Client Secret errados | Confira os valores com o seu time de atendimento da Cloud Humans | | O Gemini não usa a Cloud Humans | O repositório de dados não foi vinculado ao app | Confirme a Etapa 2, item 6 | | O Gemini pediu login de novo | Passaram 30 dias desde o login | Autorize de novo (Etapa 3) | Observações - As permissões são exatamente as da sua conta Cloud Humans. O conector não amplia nem reduz o que você já podia ver e editar - Exemplos do que pedir: Utilizando o MCP da Claudia e Como utilizar o MCP do Cloud Chat

Última atualização em Oct 14, 2026

Como conectar o MCP da Cloud Humans no Microsoft Copilot

Quando usar - A sua empresa usa o Microsoft 365 Copilot ou o Copilot Studio e você quer usar a Cloud Humans de dentro dele - Você precisa saber o que o administrador da Microsoft tem que fazer para liberar o conector Pré-requisitos - Uma conta Cloud Humans ativa. O login do conector usa o mesmo e-mail e senha da plataforma. Pelo MCP, o login é sempre com e-mail e senha, mesmo que a sua empresa use SSO para entrar no Cloud Chat - Acesso ao Microsoft Copilot Studio para criar um agente - Se a sua empresa usa políticas de dados do Power Platform, um administrador que possa liberar conectores personalizados Sobre este artigo No Microsoft Copilot, ninguém conecta um servidor MCP direto na conversa. O caminho é: 1. Criar um agente no Copilot Studio 2. Adicionar a Cloud Humans como ferramenta desse agente 3. Publicar o agente no Microsoft 365 Copilot e no Teams Por isso, quem configura é normalmente o time de TI ou quem já cria agentes no Copilot Studio na sua empresa. Passo a passo Etapa 1 — Pedir a aprovação do time de segurança 1. Envie ao time de segurança (ou ao administrador do Microsoft 365) o artigo MCP da Cloud Humans: o que o time de segurança precisa saber para aprovar, junto com o link deste artigo 2. Peça que confirmem duas liberações, se a empresa usar essas políticas: - Política de dados do Power Platform: o acesso a servidores MCP no Copilot Studio segue as políticas de conectores do Power Platform. Se conectores personalizados estiverem bloqueados, o administrador precisa liberar no Power Platform admin center - Publicação de agentes: a publicação no Microsoft 365 Copilot pode exigir aprovação no Microsoft 365 admin center Etapa 2 — Adicionar a Cloud Humans como ferramenta do agente 1. No Copilot Studio, abra o agente (ou crie um novo) e vá até Ferramentas (Tools) 2. Clique em Adicionar uma ferramenta (Add a tool) > Nova ferramenta (New tool) > Model Context Protocol 3. Preencha: | Campo | Valor | |---|---| | Server name | Cloud Humans | | Server description | Consulta e gerencia a base de conhecimento da ClaudIA e o Cloud Chat da empresa | | Server URL | https://mcp.cloudhumans.com/openapi/cloudhumans/mcp | 4. Em autenticação, escolha OAuth 2.0 e, no tipo, Descoberta dinâmica (Dynamic discovery). Não é preciso preencher Client ID nem Client Secret 5. Clique em Criar (Create) e depois em Avançar (Next) 6. Em Adicionar ferramenta (Add tool), escolha Criar uma nova conexão (Create a new connection), faça o login da Cloud Humans e clique em Adicionar ao agente (Add to agent) :::info Na tela de ferramentas do agente, dá para desligar ferramentas específicas da Cloud Humans. Se a empresa quiser um uso só de consulta, desligue as que criam ou alteram dados, em especial a de criar campanha. ::: :::info A descrição do servidor é usada pelo Copilot para decidir quando chamar a Cloud Humans. Uma descrição clara faz o agente acertar mais. ::: Etapa 3 — Publicar o agente 1. No Copilot Studio, publique o agente 2. Em Canais (Channels), ative Teams e Microsoft 365 Copilot 3. Se a sua empresa exigir, aguarde a aprovação do administrador no Microsoft 365 admin center Etapa 4 — Conectar e testar Cada pessoa faz o próprio login na primeira vez que usa o agente. 1. No Microsoft 365 Copilot ou no Teams, abra o agente 2. Peça: Liste os conteúdos da minha base de conhecimento na Cloud Humans. 3. Na primeira vez, o agente mostra um cartão pedindo para conectar. Entre com o seu e-mail e senha da Cloud Humans Problemas comuns | O que aparece | Causa | O que fazer | |---|---|---| | Não consigo adicionar a ferramenta MCP | Política de dados do Power Platform bloqueando conectores personalizados | Peça ao administrador para liberar (Etapa 1) | | O agente não aparece no Microsoft 365 Copilot | O agente não foi publicado no canal, ou aguarda aprovação | Confira a Etapa 3 | | O agente responde sem usar a Cloud Humans | A descrição do servidor não deixa claro quando usar | Ajuste a Server description | | O agente pediu login de novo | Passaram 30 dias desde o login | Conecte de novo pelo cartão do agente | Observações - As permissões são exatamente as de quem está usando o agente. Cada pessoa faz o próprio login, então o agente não compartilha o acesso de quem o criou - Exemplos do que pedir: Utilizando o MCP da Claudia e Como utilizar o MCP do Cloud Chat

Última atualização em Oct 14, 2026