Principal APIs
🔗

APIs

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

Como enviar mensagem proativa pelo WhatsApp via API

Neste artigo, você vai aprender a enviar mensagens proativas pelo WhatsApp via API no Cloud Chat — incluindo o endpoint, os parâmetros necessários, exemplos de requisição e o comportamento esperado do ticket criado. Comportamento de criação do ticket via API - A mensagem não nasce assignada, pois o sistema não sabe qual agente deve receber. Por esse motivo, ao invés do balão ser laranja, ele aparece verde, a cor verde representa mensagens "robóticas" de automação dentro do próprio Cloud Chat. - Sempre gera um novo ticket. - O ticket nasce com status em aberto. ⚠️ Se o cliente tiver dois tickets em aberto, novas mensagens enviadas pelo cliente serão sempre direcionadas para o ticket mais recente. 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 Body Parameters inbox_id(String/Obrigatório): ID da inbox por onde a mensagem será enviada. phone_number(String/Obrigatório): Número de telefone do destinatário. template_name(String/Obrigatório): Nome do template configurado no sistema. header_attachment(String/Opcional): URL do anexo a ser enviado, caso a template suporte um anexo em seu cabeçalho. button_param_#(String/Opcional): Variáveis de botões presentes no template. Devem ser enviados tantos quantos forem necessários (substituir # pelo índice ordenado do botão de 0 a N). Parâmetros dinâmicos do template(String/Opcional): Variáveis específicas do template que serão substituídas no envio. Sobre os Parâmetros Dinâmicos Os templates configurados podem conter variáveis dinâmicas que são substituídas no momento do envio. Essas variáveis devem ser enviadas diretamente no corpo da requisição, ao lado de outros campos obrigatórios, como inbox_id, phone_number, e template_name. - Exemplo de Variáveis no Template: Um template pode incluir variáveis como {{contact.name}}, {{contact.email}}, ou valores estáticos como "Fulaninho". - Formato no Payload: Envie essas variáveis diretamente na raiz do JSON, substituindo os valores de acordo com as informações desejadas. 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": "PHONE_NUMBER", "template_name": "test_template", "header_attachment": "ATTACHMENT_URL", "button_param_0": "BUTTON PARAMETER", "button_param_1": "ANOTHER BUTTON PARAMETER", "name": "John Doe", "email": "[email protected]", "custom_code": "12345" }' 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. Guias de integrações - Disparo integrado a fluxos de trabalho no Hubspot

Última atualização em Apr 13, 2026

Como importar contatos em massa via API

Neste artigo, você vai aprender a importar ou atualizar vários contatos de uma vez no Cloud Chat via API, usando o endpoint de criação em lote. Para importar ou atualizar vários contatos de uma vez via API no Cloud Chat, envie uma requisição POST para o endpoint abaixo. Quer importar apenas um contato? Use o endpoint de Import de Contato individual. 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", "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 no formato internacional 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 | | custom_attributes | Não | Objeto com atributos customizados (chave-valor) | *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 já existir, ignora. | | true | Cria contatos novos e atualiza contatos existentes. | Exemplo de requisição (curl) 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" } ] }' Cuidados com upsert Atenção — 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 será sobrescrito com null. Exemplo: Se um contato tem email e phone_number cadastrados, e você envia um update com apenas phone_number, o campo email será 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}} Diferença entre este endpoint e o Import individual | | Este endpoint (bulk_create) | Import individual (external_import) | | --- | --- | --- | | Quando usar | Importar/atualizar vários contatos de uma vez | Importar/atualizar 1 contato por chamada | | Formato do body | {"upsert": true, "data": [{...}, {...}]} | Objeto JSON simples (flat) | | Upsert | Precisa do flag "upsert": true | Sempre ativo (automático) | | Cuidado com null | Campos omitidos são sobrescritos com null | Campos omitidos são preservados | Não misture os formatos! Se enviar um objeto flat (sem data: [...]) para este endpoint, não vai funcionar. Para contato individual, use o endpoint de import individual. Onde encontrar os parâmetros de configuração - CLOUDCHAT_DOMAIN: O domínio visível na URL do navegador ao acessar o Cloud Chat - ACCOUNT_ID: Em configurações da conta - API_TOKEN: Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Última atualização em Apr 13, 2026

Como enviar mensagem proativa pelo WhatsApp via HubSpot

Neste artigo, você vai aprender a enviar mensagens proativas pelo WhatsApp usando webhooks do HubSpot integrados ao Cloud Chat. Utilizando nosso endpoint de envios proativos, é possível iniciar conversas de WhatsApp através de webhooks integrados ao Hubspot. Esses webhooks podem ser alimentados com a base de informações do hubspot, tornando a mensagem contextualmente dinâmica. 📌 Quando usar essa integração? Utilize esse fluxo quando quiser: - Enviar automaticamente uma mensagem no WhatsApp (utilizando um template aprovado pela Meta) pelo Cloud Chat a partir de uma ação no HubSpot - Personalizar a mensagem com propriedades do contato no HubSpot (nome, número do pedido, status, entre outros) - Criar fluxos automáticos de follow-up, cobrança, onboarding ou atualização de status ✅ Pré-requisitos Antes de configurar o endpoint, você precisa: - Ter o número de WhatsApp conectado ao Cloud Chat e possuir o inbox_id da caixa de entrada correspondente. Consulte a FAQ: Guia mestre — Como conectar seu número de WhatsApp ao Cloud Chat O inbox_id pode ser encontrado acessando a configuração da caixa de entrada no Cloud Chat. A URL seguirá o padrão abaixo: https://cloudchat.cloudhumans.com/app/accounts/{{account_id}}/settings/inboxes/{{inbox_id}} - Ter um template aprovado na Meta cadastrado no Cloud Chat. Acesse a FAQ: Como criar templates do WhatsApp no Cloud Chat (criação, edição e aprovação). - Ter sua API Key do Cloud Chat em mãos. Acesse a FAQ a seguir para obter a chave e o token: API: Enviar mensagem proativa pelo WhatsApp. Etapa 1: Criar o Workflow no HubSpot Para criar um webhook de disparo proativo em um workflow do Hubspot, siga as etapas abaixo. Na sidebar principal do Hubspot, passe o mouse sobre o símbolo de automações e em seguida clique em Fluxos de trabalho para ser redirecionado à dashboard de workflows: Ao adentrar a dashboard, clique em Criar fluxo de trabalho e em seguida selecione a opção Do zero: Escolha as opções que irão disparar esse gatilho: Etapa 2: Configurar o envio do Webhook Com a configuração inicial do workflow concluída, temos agora que construir o payload a ser enviado no webhook. Para iniciar a configuração do webhook, clique no botão de adicionar ação (+): No painel esquerdo, clique em Operações de dados e em seguida selecione Envie um webhook: No seletor de método, escolha a opção POST: Em seguida, preencha as informações de url do webhook e a chave de api: URL: https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation Para configurar a Chave de API, clique em Adicionar segredo. Em seguida, aparecerá uma janela solicitando o Nome do segredo e o Valor do segredo. Preencha o Nome do Segredo com api_access_token e, no campo Valor do Segredo, informe a API Key do Cloud Chat que foi salva anteriormente. Estrutura do Payload Por fim, preencha o body (payload) da requisição para realizar o disparo, incluindo: - template_name (obrigatório) — valor estático correspondente ao nome exato do template aprovado no Cloud Chat. - inbox_id (obrigatório) — valor estático que identifica a inbox de envio do Cloud Chat. - phone_number (obrigatório) — campo dinâmico utilizando a variável do HubSpot {{contact.phone}}. - Variáveis do template — Ao cadastrar o template no Cloud Chat, as variáveis configuradas nele devem ter exatamente o mesmo nome das propriedades que serão enviadas pelo HubSpot no payload. Isso significa que o nome da variável no template precisa ser idêntico ao nome do campo enviado no webhook (respeitando grafia, maiúsculas/minúsculas e underscores), para que a substituição dos valores aconteça corretamente no momento do disparo. Abaixo, segue um exemplo de payload: Observação: As variáveis utilizadas acima, bem como as informações sobre a url do webhook e a chave de API são discutidas na seção de envios proativos via API.

Última atualização em Apr 13, 2026

Como importar contatos via HubSpot

Neste artigo, você vai aprender a criar ou atualizar contatos no Cloud Chat automaticamente via webhooks do HubSpot. Utilizando nosso endpoint de importação, é possível criar ou atualizar seus contatos no Cloud Chat através de webhooks integrados ao Hubspot. Endpoint utilizado O webhook do HubSpot deve apontar para: POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import Para detalhes completos sobre este endpoint (campos aceitos, comportamento de upsert e limitações), veja o artigo API: Import de Contato. Exemplo de configuração de webhook utilizando workflows no Hubspot Para criar um webhook de importação de contato em um workflow do Hubspot, siga as etapas abaixo. Etapa 1: Criando o workflow Na sidebar principal do Hubspot, passe o mouse sobre o símbolo de automações e em seguida clique em Fluxos de trabalho para ser redirecionado à dashboard de workflows: Ao adentrar a dashboard, clique em Criar fluxo de trabalho e em seguida selecione a opção Do zero: Na seleção da configuração do tipo do workflow, selecione Baseado em Contato e clique em Próximo: Etapa 2: Configurando a requisição do webhook Com a configuração inicial do workflow concluída, temos agora que construir o payload a ser enviado no webhook. Para iniciar a configuração do webhook, clique no botão de adicionar ação (+): No painel esquerdo, clique em Operações de dados e em seguida selecione Envie um webhook: No seletor de método, escolha a opção POST: Em seguida, preencha as informações de url do webhook e a chave de api: Observação: A chave de api deve ser configurada em gerenciar segredos. Por fim, preencha os campos de informação do contato para efetuar o disparo: name (Nome), phone_number (Telefone), email, identifier (Identificador único do contato), bem como quaisquer outros atributos customizados disponíveis: Observação: Pelo menos um entre os campos phone_number, email e identifier é obrigatório para a criação do contato. Se o contato existir em sua base, ele será atualizado com os campos enviados acima. Caso contrário, um novo contato será adicionado.

Última atualização em Apr 13, 2026

Como importar um contato individual via API

Neste artigo, você vai aprender a importar ou atualizar um contato individual no Cloud Chat via API. Para importar ou atualizar um contato individual via API no Cloud Chat, envie uma requisição POST para o endpoint abaixo com sua chave de acesso e os campos necessários. Quer importar vários contatos de uma vez? Use o endpoint de Import em massa de contatos 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 no formato internacional 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) 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 um novo contato ou atualiza um existente 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 Importante: 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 resultado. 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 vai buscar pelo email primeiro (pois o campo email está presente). Se [email protected] não existir em nenhum contato, ele não vai tentar buscar pelo phone_number. O resultado será uma tentativa de criar um contato novo, que pode falhar silenciosamente por conflito de telefone. Como fazer corretamente Para atualizar um contato existente por telefone, envie apenas o telefone como identificador na primeira chamada, sem o campo que deseja adicionar como identificador: 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 | Atenção: O status 204 indica que a requisição foi recebida, mas não retorna o contato criado/atualizado. Se precisar confirmar que a alteração foi aplicada, faça uma consulta ao contato 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 de uma vez | | 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 | Não misture os formatos! Se enviar {"upsert": true, "data": [...]} para este endpoint (external_import), não vai funcionar. Esse formato é exclusivo do endpoint de import em massa (bulk_create). Onde encontrar os parâmetros de configuração - CLOUDCHAT_DOMAIN: O domínio visível na URL do navegador ao acessar o Cloud Chat - ACCOUNT_ID: Em configurações da conta - API_TOKEN: Em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Última atualização em Apr 13, 2026

Como remover tags de contatos em massa via API

Neste artigo, você vai aprender a remover tags de múltiplos contatos de uma só vez no Cloud Chat via API. Para remoção em massa de tags de contatos via API no Cloud Chat, basta enviar uma requisição DELETE para: https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/contacts/delete_tags Certifique-se de enviar a chave de acesso (API_TOKEN) nos headers e os campos solicitados conforme descrito abaixo. - API_TOKEN: Token de acesso obtido nas configurações do perfil. - (https://cloudchat.cloudhumans.com/app/accounts/ACCOUNT_ID/profile/settings) Requisição com campos de exemplo: 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"] } ] }' Corpo da Requisição: O corpo da requisição deve conter um único campo, contacts, que deve ser um array de objetos. Cada objeto representa um contato e deve conter os seguintes parâmetros: - identifier (opcional): Identificador único do contato. - email (opcional): E-mail do contato (no formato [email protected]). - phone_number (opcional): Número de telefone do contato (no formato +550011112222). - tags (obrigatório): Array com as tags a serem removidas (identificada pelo seu nome, como "tag-para-ser-removida"). Observação: Pelo menos um dos campos identifier, email ou phone_number deve ser informado para identificar o contato. Exemplo de requisição: { "contacts": [ { "identifier": 123, "tags": ["tag-de-massa-1","tag-de-massa-2"] } ] } Como o contato é localizado O sistema busca o contato nesta ordem: 1. identifier (primeiro) 2. email (segundo) 3. phone_number (terceiro) Diferente do endpoint de import de contato, aqui o identifier tem prioridade sobre email. Nota sobre phone_number: Se enviado sem o prefixo +, o sistema adiciona automaticamente (ex: 5511999998888 vira +5511999998888).

Última atualização em Apr 13, 2026

Como atualizar atributos customizados em conversas via API

Neste artigo, você vai aprender a atualizar atributos customizados de conversas no Cloud Chat via API. Para a atualização de atributos customizados em conversas via API no Cloud Chat, basta enviar uma requisição PUT para: https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes Importante: 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. Certifique-se de enviar a chave de acesso (API_TOKEN) nos headers e os campos solicitados conforme descrito abaixo. - API_TOKEN: Token de acesso obtido nas configurações do perfil. - (https://cloudchat.cloudhumans.com/app/accounts/ACCOUNT_ID/profile/settings) Requisição com campos de exemplo: 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 } }' ** Corpo da Requisição** A requisição deve conter um único campo, custom_attributes, que deve ser um objeto contendo os atributos customizados a serem atualizados. Observação: O conversation_id da conversa a ser atualizada não deve ser enviado no corpo da requisição, pois ele é passado como um parâmetro na URL. Exemplo de Requisição: PUT /conversations/123/custom_attributes { "custom_attributes": { "to_be_updated": "new_value", "to_be_removed": null } } ** Tipos de atributos** Os atributos customizados das conversas possuem um tipo definido de valor, definidos na sua configuração, que devem ser respeitados ao utilizar o endpoint para atualizar os valores: - Texto: Deve receber valores tipo String obrigatóriamente. - Número: Deve conter apenas números. Não pode conter caracteres alfabéticos ou especiais. - Link: Deve ser um URL válido (http ou https). O link deve obrigatoriamente terminar com um domínio válido (ex: .com, .net, .org). - Data: Deve estar no formato ISO8601 (YYYY-MM-DDTHH:MM:SS.sssZ). Exemplo válido: "2025-01-01T12:00:00.000Z". - Lista: Deve receber um valor do tipo String, e este valor deve obrigatoriamente estar presente na lista de opções definidas na configuração do atributo. - Checkbox: Deve ser valores "true" / "false" (string), ou valores true / false (Booleano). Observação: Para remover um valor atribuído a um atributo customizado, basta enviar null ou uma string vazia (""). O sistema processará a requisição e removerá o atributo do objeto de custom_attributes, garantindo que ele não esteja mais presente na conversa. ** Tratamento de Erros** Caso algum valor enviado no campo custom_attributes não respeite as regras definidas, a requisição não será processada e retornará um erro específico. - Se a conversa não for encontrada, o sistema retorna um erro "Conversation not found" com código 404. - Se o corpo da requisição estiver incorreto, um erro "Invalid attributes" com código 422 será retornado. - Caso um atributo não exista na configuração, será retornado um erro informando que o atributo não foi encontrado. - Se um valor não respeitar o tipo esperado, será retornada uma mensagem informando o problema, como: "number_attr must contain only numeric digits" ou "date_attr must be in ISO8601 format (YYYY-MM-DDTHH:MM:SS.sssZ)". Tipos de atributos suportados Além dos tipos padrão (text, number, date, list, checkbox, link), este endpoint também aceita: | Tipo | Requisitos | |---|---| | multi_list | Array de strings. Cada valor deve existir nas opções pré-definidas. Ex: ["opção1", "opção2"] | Cuidado: PUT (merge) vs POST (replace) Existem dois endpoints para alterar custom attributes: | Método | Comportamento | Quando usar | |---|---|---| | PUT .../custom_attributes (documentado acima) | 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 | Usar com cuidado — campos não enviados serão apagados | Recomendamos sempre usar o PUT para evitar perda de dados.

Última atualização em Apr 13, 2026

API: Extração de dados em lote (Data Extract API)

⚠️ Esta API é destinada exclusivamente para extração histórica de dados em lote. Para consultas em tempo real ou ações em tickets, consulte o Guia Mestre de APIs. A Data Extract API permite exportar dados completos dos seus tickets direto da sua conta no Cloud Chat, com datas, status, responsáveis, tempos de resposta e muito mais. Ideal para relatórios personalizados e integrações externas. Requisição base: curl --location 'https://{CLOUDCHAT_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T01:58:59&endDate=2025-03-28T01:59:00&type=BASE_TICKET_METRICS' \ --header 'Accept: application/json' \ --header 'api_access_token: {API_TOKEN}' O que você precisa substituir: 1. {CLOUDCHAT_DOMAIN}: seu domínio Cloud Chat (ex: app.Cloud Chat.cloudhumans.com) 2. {ACCOUNT_ID}: ID da conta 3. {API_TOKEN}: token de acesso gerado no perfil de um administrador ou supervisor Como obter essas informações? {CLOUDCHAT_DOMAIN} - Você pode obter seu domínio ao fazer login na sua conta no Cloud Chat. É a parte que aparece na URL do navegador, por exemplo: {ACCOUNT_ID} - Após o login, verifique a URL da sua dashboard inicial. O ID da conta aparece na URL como: app/accounts/1/dashboard. Encontrado na URL do seu Cloud Chat, após "accounts"; ex.: https://cloudchat.cloudhumans.com/app/accounts/**1**/conversations/6341 (nesse caso, o account_id é 1) {API_TOKEN} - O token de API deve ser gerado a partir do perfil de um usuário com permissão de administrador ou supervisor (na configuração de perfil): Quais parâmetros são obrigatórios? Ao fazer a requisição para a API, você deve informar os seguintes parâmetros: - startDate: Data e hora de início da extração. Formato esperado: yyyy-MM-ddTHH:mm:ss (Em UTC) Exemplo: 2025-03-27T01:58:59 - endDate: Data e hora de término da extração. Deve ser posterior ao startDate e o intervalo entre as duas datas não pode ultrapassar 5 dias (120 horas). Exemplo: 2025-03-28T01:59:00 (Em UTC) - type: O tipo de dados que deseja exportar. Tipos disponíveis: BASE_TICKET_METRICS, TICKET_METRICS_WITH_AGENT_INFORMATION, TICKET_SUMMARY, CAMPAIGN_DELIVERY_EVENTS, SINGLE_CONTACT_DELIVERY_EVENTS - account_id: ID da sua conta no Cloud Chat. Esse valor é informado no caminho da URL (ex: /accounts/1/data_extracts, onde o ID da conta é 1). Observação sobre o intervalo de datas Para garantir estabilidade e performance, o intervalo máximo permitido por requisição é de 5 dias. Se você deseja exportar dados de um período maior (por exemplo, 30 dias), é possível dividir a consulta em múltiplas requisições. Exemplo: Para extrair dados de um mês completo, você pode fazer 6 requisições consecutivas com intervalos de até 5 dias cada, variando o startDate e endDate de acordo com o período desejado. Limite de requisições (rate limit) Para proteger a estabilidade da plataforma, a Data Extract API aplica um limite de 20 requisições por minuto por token de API (api_access_token). O limite é contado por token, então tokens distintos da mesma conta têm orçamentos independentes. O que acontece ao ultrapassar o limite Requisições além do limite recebem resposta HTTP 429 Too Many Requests com o seguinte corpo: { "error": "Rate limit exceeded. Retry later.", "retry_after": 42 } Recomendações de integração - Respeite o cabeçalho Retry-After antes de tentar novamente. Loops de retry sem backoff amplificam o bloqueio e podem degradar sua extração. - Para extrações grandes (ex.: 30 dias), combine em janelas de 5 dias (descrito acima) com espaçamento entre requisições — 20/min é folgado para o volume típico de extração histórica. - Se sua integração precisa de throughput maior de forma sustentada, entre em contato com o suporte. 🔎 Novo parâmetro opcional: Todos os endpoints da Data Extract API agora aceitam o parâmetro opcional rangeFilterProperty. Define qual campo de data será utilizado para aplicar os filtros de período (start_date / end_date). Valores aceitos: - CREATED_AT: Filtra os registros com base na data de criação. Este é o comportamento padrão quando o parâmetro não é informado. - UPDATED_AT: Filtra os registros com base na data da última atualização. Tipos de extração disponíveis via API A Data Extract API agora suporta os seguintes valores para o parâmetro type: - BASE_TICKET_METRICS - TICKET_METRICS_WITH_AGENT_INFORMATION - TICKET_SUMMARY - CAMPAIGN_DELIVERY_EVENTS (novo) - SINGLE_CONTACT_DELIVERY_EVENTS (novo) 1. BASE_TICKET_METRICS Retorna dados básicos dos tickets, como: - ticketId: identificador interno e único do ticket - displayTicketId: ID visível na interface (o número do ticket que aparece na URL) - inboxId: ID da caixa de entrada usada - accountId e accountName: ID e nome da sua conta no Cloud Chat - ticketStatus: status do ticket (ex: resolved, open, pendente) - teamName: Nome do time atribuído ao ticket - ticketPriorityName: Prioridade atribuída ao ticket (ex: low, mediu, high, urgent) - ticketType: é a primeira tag colocada no ticket - inboxName: nome da Inbox usada - ticketTitle: título do ticket: uma concatenação do título do ticket (quando existir, pra email, por exemplo), telefone do contato e nome do contato - channel: canal usado (ex: WhatsApp, e-mail) - createdAt: timestamp de criação do ticket - firstReplyAt: timestamp da primeira resposta - firstReplyTime: tempo até a primeira resposta (em minutos) desde a criação do ticket. - resolvedAt: timestamp de resolução (se o ticket foi reaberto e, portanto, contém mais de uma resolução, é considerado a última data de resolução) - totalResolutionTimeMin: tempo total de resolução (em minutos) - tags: tags associadas ao ticket - agentId, ticketOwner e ticketOwnerEmail: ID, nome e email do agente responsável - contactId, contactName, contactEmail, contactPhone ID, nome do contato, email do contato e telefone do contato (cliente que abriu o ticket) - campaignId: ID da campanha que gerou este ticket (caso exista) - proactivelyInitiated: tickets gerados por campanhas ou disparos proativos unitários terão este valor como true, caso contrário este valor será false. ⚠️ IMPORTANTE: Ao configurar o fuso horário da conta (por exemplo, GMT-3 ou qualquer outro), os campos timestamp(createdAt, firstAgentAssignmentTime, firstReplyAt, firstAgentFirstReplyTime, resolvedAt, firstReplyTime, resolvedAt, firstReplierAgentAssignmentTime, firstReplierAgentFirstReplyTime, repliedAt, readAt, receivedAt, sentAt)são retornados no fuso horário definido na conta. Caso não haja fuso horário configurado os horários serão retornados em UTC (link da FAQ de como definir o fuso horário aqui) 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 os dados com detalhes sobre o agente que respondeu e resolveu, como: - ticketId: identificador interno e único do ticket - displayTicketId: ID visível na interface (o número do ticket que aparece na URL) - accountName: ID e nome da sua conta no Cloud Chat - inboxName: nome da Inbox usada - ticketLink: link do ticket para abrir diretamente ele no Cloud Chat - agentOnResolutionId, agentOnResolutionName e agentOnResolutionEmail: ID, nome e email do agente humano que resolveu o ticket - firstAgentReplyId, firstAgentReplyName, firstAgentReplyEmail: ID, nome e email do agente humano que respondeu primeiro - firstAgentAssignmentTime: timestamp da atribuição ao primeiro agente humano a entrar no ticket - firstAgentFirstReplyTime: timestamp da primeira resposta do primeiro agente humano a entrar no ticket - firstReplierAgentAssignmentTime : timestamp da atribuição do agente humano que primeiro respondeu o ticket - firstReplierAgentFirstReplyTime : tempo de primeira resposta humana ao ticket(caso o primeiro agente humano atribuído não responda o ticket, esse dado será diferente ao firstAgentFirstReplyTime) - firstAgentReplyTimeMin: tempo até a primeira resposta do primeiro agente humano a entrar no ticket desde sua atribuição (minutos) - firstAgentResolutionTimeMin: tempo entre a abertura do ticket até a última resolução do ticket (minutos) - csatScore e csatFeedback: avaliação (nota) de satisfação do cliente (CSAT) e comentário do CSAT (se houver) - contactCustomFields: campos personalizados do contato (JSON) - conversationCustomFields: campos personalizados da conversa (JSON) - conversationAdditionalFields: outros campos complementares que podem ou não vir no canal que o cliente entrou (JSON). Esse campo vêm preenchido se: - O canal é passível de passar essa informação - O cliente habilitou para passar essa informação no canal Exemplo de resposta: [ { "ticketId": 11111, "displayTicketId": 11111, "accountName": "account name", "inboxName": "WhatsApp", "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/11111", "ticketStatus": "resolved", "createdAt": "2025-03-27T13:00:40.897954", "resolvedAt": "2025-03-27T15:38:02.743726", "agentOnResolutionId": 225, "agentOnResolutionName": "ClaudIA", "agentOnResolutionEmail": "[email protected]", "firstAgentReplyId": 111, "firstAgentReplyName": "ClaudIA", "firstAgentReplyEmail": "[email protected]", "firstAgentAssignmentTime": "2025-03-27T13:16:13.001269", "firstAgentFirstReplyTime": "2025-03-27T13:17:01.344971", "firstAgentReplyTimeMin": 0.81, "firstAgentResolutionTimeMin": 141.83, "csatScore": null, "csatFeedback": "", "contactCustomFields": "{}", "conversationCustomFields": "{}", "conversationAdditionalFields": "{}" } ] ⚠️ Importante: 1. firstAgentReplyTimeMin — Calculado como o tempo entre o momento de atribuição do primeiro agente do ticket (firstAgentAssignmentTime) até sua primeira resposta (firstAgentFirstReplyTime). 2. firstAgentResolutionTimeMin — Calculado como o tempo entre a atribuição do primeiro agente do ticket (firstAgentAssignmentTime) até o momento em que o ticket foi resolvido (resolvedAt). 3. TICKET_SUMMARY Retorna um resumo textual (é a conversa inteira) da conversa dentro do ticket. Inclui ticketId, displayTicketId, ticketLink e summary. Exemplo de resposta: [ { "ticketId": 1111, "displayTicketId": 1111, "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111", "summary": "CONTATO: Oi\nUSUÁRIO: Olá!" } ] 4. CAMPAIGN_DELIVERY_EVENTS Retorna eventos de entrega de campanhas do WhatsApp no Cloud Chat, centralizando e rastreando, por contato e campanha, o status de mensagens enviadas. O objetivo é consolidar em um único ponto dados de eventos de campanha como envio, recebimento, leitura, resposta e erros. Campos retornados: - id: Identificador único do evento de entrega da campanha - campaignId: ID da campanha - campaignTitle: Título da campanha - audience: Nome do público da campanha - contactId: ID do contato - contactName: Nome do contato - contactEmail: E-mail do contato - contactPhoneNumber: Número de telefone do contato - ticketId: ID interno do ticket vinculado - displayTicketId: ID visível do ticket (exibido na URL da conversa / ticket) - messageSent: Indica se a mensagem foi enviada com sucesso para a API do WhatsApp (Meta) - sentAt: timestamp em que a mensagem foi efetivamente enviada para a API do WhatsApp - messageReceived: Indica se o WhatsApp confirmou que a mensagem foi entregue ao dispositivo do contato - receivedAt: timestamp em que a confirmação de entrega foi recebida - messageRead: Indica se o WhatsApp confirmou que a mensagem foi lida pelo contato. ⚠ Esse evento só será registrado se o contato tiver o status de leitura habilitado nas configurações de privacidade do WhatsApp - readAt: timestamp em que a confirmação de leitura foi recebida (ou null caso não tenha ocorrido) - messageReplied: Indica se o contato enviou alguma resposta após receber a mensagem da campanha - repliedAt: timestamp em que a primeira resposta foi registrada - error: Mensagem de erro retornada, caso o envio não tenha sido realizado ou tenha falhado em alguma etapa (por exemplo: número inválido, contato sem WhatsApp, bloqueio, etc.) - createdAt: timestamp de criação do registro na base de dados do Cloud Chat - updatedAt: timestamp da última atualização do registro (por exemplo, quando novos eventos de entrega ou leitura foram recebidos) Exemplo de resposta: [ { "id": 103, "campaignId": 5502, "campaignTitle": "Natal 2025 - Promoção Especial", "audience": "lista_fidelidade_natal", "contactId": 9003, "contactName": "Carla Souza", "contactEmail": "[email protected]", "contactPhoneNumber": "+55 31 99999-99999", "ticketId": 78414, "displayTicketId": "2027", "messageSent": false, "sentAt": null, "messageReceived": false, "receivedAt": null, "messageRead": false, "readAt": null, "messageReplied": false, "repliedAt": null, "error": "Número de telefone inválido ou não registrado no WhatsApp", "createdAt": "2025-12-10T09:00:00.000Z", "updatedAt": "2025-12-10T09:00:00.000Z" } ] 5. SINGLE_CONTACT_DELIVERY_EVENTS Retorna eventos de entrega de mensagens pró-ativas de disparo único do WhatsApp no Cloud Chat, centralizando e rastreando, o status das mensagens enviadas. O objetivo é consolidar em um único ponto dados de eventos de disparo pró-ativo como envio, recebimento, leitura, resposta e erros. Campos retornados: - id: Identificador único do evento de entrega pró-ativa - contactId: ID do contato - contactName: Nome do contato - contactEmail: E-mail do contato - contactPhoneNumber: Número de telefone do contato - ticketId: ID interno do ticket vinculado - displayTicketId: ID visível do ticket (exibido na URL da conversa / ticket) - messageSent: Indica se a mensagem foi enviada com sucesso para a API do WhatsApp (Meta) - sentAt: timestamp em que a mensagem foi efetivamente enviada para a API do WhatsApp - messageReceived: Indica se o WhatsApp confirmou que a mensagem foi entregue ao dispositivo do contato - receivedAt: timestamp em que a confirmação de entrega foi recebida - messageRead: Indica se o WhatsApp confirmou que a mensagem foi lida pelo contato. ⚠ Esse evento só será registrado se o contato tiver o status de leitura habilitado nas configurações de privacidade do WhatsApp - readAt: timestamp em que a confirmação de leitura foi recebida (ou null caso não tenha ocorrido) - messageReplied: Indica se o contato enviou alguma resposta após receber a mensagem - repliedAt: timestamp em que a primeira resposta foi registrada - error: Mensagem de erro retornada, caso o envio não tenha sido realizado ou tenha falhado em alguma etapa (por exemplo: número inválido, contato sem WhatsApp, bloqueio, etc.) - createdAt: timestamp de criação do registro na base de dados do Cloud Chat - updatedAt: timestamp da última atualização do registro (por exemplo, quando novos eventos de entrega ou leitura foram recebidos) 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" } ] 📌 Próximos passos Agora você pode seguir para: - 🔍 APIs de Consulta em Tempo Real (Contacts, Tickets e Messages) - ✏️ APIs de Atualização e Ação em Tickets E lembre-se: 👉 Sempre consulte o Guia Mestre antes de usar uma nova API.

Última atualização em Apr 17, 2026

Como importar histórico de tickets via API

Neste artigo, você vai aprender como importar o histórico de tickets via API no Cloud Chat — incluindo os requisitos, o endpoint e o formato esperado. Importante A importação de tickets via API só pode ser realizada após a conclusão da migração e com a inbox já criada e ativa no Cloud Chat. Requisito técnico Para realizar esse processo, é necessário que o cliente possua um desenvolvedor responsável por executar as requisições na API e estruturar os dados corretamente conforme a documentação. O time da Cloud Humans não realiza a importação via API para o cliente, apenas disponibiliza a documentação técnica e orientações para implementação. Import de histórico de tickets via API Para importar tickets advindos de outro helpdesk via API no Cloud Chat, basta enviar uma POST request para https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import enviando a chave de acesso e os dados estruturados da maneira definida abaixo. Requisição curl -X POST \ 'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import' \ --header 'content-type: application/json' \ --header 'api_access_token: API_TOKEN' \ --data '{ "conversations_data": [ { "contact": { "email": "[email protected]", "name": "John Doe", "phone_number": "+1234567890", "identifier": "external_helpdesk_id" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "My printer is on fire! The smoke is very colorful and I need immediate help.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false } ] } ] }' Corpo da requisição O corpo da requisição deve conter: - conversations_data: (obrigatório) Lista de objetos com os dados dos tickets, com os seguintes atributos: - created_at e updated_at (obrigatórios): datas de criação e de última atualização, respectivamente. Devem estar no padrão de Date Time ISO 8061. - contact (obrigatório): objeto contendo os dados do contato relacionado ao ticket. Contém os campos: - identifier (obrigatório): identificador único do contato no helpdesk externo. - email (opcional): email do contato. Deve ser um email válido. - name (opcional): nome do contato. - phone_number (opcional): telefone do contato. Deve estar no padrão internacional com o caractere "+" e o código do país; exemplo: +5599988888888 - messages (obrigatório): lista de objetos contendo os dados das mensagens enviadas no ticket. Possui os seguintes campos: - content (obrigatório): corpo da mensagem. - message_type (obrigatório): indicador de direção da mensagem. Utilize o valor "incoming" para designar mensagens inbound (enviadas pelo contato) e "outgoing" para mensagens outbound (enviadas pelo sistema ou por agentes durante o atendimento). - created_at (obrigatório): data de envio da mensagem. Deve estar no padrão de Date Time ISO 8061. - private (obrigatório): indicador de mensagem interna (privada). Utilize o valor "true" para mensagens privadas e "false" para mensagens públicas. Exemplo { "conversations_data": [ { "contact": { "email": "[email protected]", "name": "John Doe", "phone_number": "+1234567890", "identifier": "user_6782902" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T14:22:00Z", "messages": [ { "content": "My printer is on fire! The smoke is very colorful and I need immediate help.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false }, { "content": "Thanks for contacting us. I can see this is urgent. Let me help you resolve this immediately.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false }, { "content": "Internal note: Customer has premium support, prioritize this case.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true }, { "content": "**Status Update**: Escalated to Level 2 Support", "message_type": "activity", "created_at": "2024-01-15T12:00:00Z", "private": true } ] } ] } Regras importantes - Identificador único obrigatório: O identificador do contato identifier deve ser único. Note que dois contatos com dados divergentes porém mesmo identificador serão considerados como um mesmo contato. - Limites por requisição: Cada requisição para esse endpoint possui os seguintes limites: 10.000 tickets e 15 megabytes. Caso seu import ultrapasse esse limite, será necessário particionar os dados e efetuar a quantidade correspondente de requisições para a importação de todos os dados. Parâmetros CLOUDCHAT_DOMAIN: Você pode obter seu domínio ao fazer login na sua conta no Cloud Chat. É 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) INBOX_ID: Identificador da caixa que receberá os tickets a serem importados. Pode ser obtido na URL da aba de configurações da inbox:

Última atualização em Apr 13, 2026

Como criar tickets via API no Cloud Chat

📌 O que essa funcionalidade permite? Essa API permite que você crie um ticket no Cloud Chat a partir de qualquer sistema externo, como: - Um sistema de telefonia (ex: quando uma ligação chega) - Um formulário preenchido no seu site - Uma integração com CRM, ERP ou qualquer ferramenta personalizada Ao usar essa rota, você pode: - Criar um novo ticket com status em aberto, pendente, ou fechado - Associar o ticket a um contato via e-mail, telefone ou identificador - Incluir uma mensagem inicial (inbound ou outbound) - Definir atributos customizados da conversa no momento da criação 🧭 Quando usar essa API? Use quando for necessário iniciar uma conversa no Cloud Chat sem que o cliente tenha mandado uma mensagem por um canal ativo. Exemplos: - 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 que vêm de outras fontes? → Use essa API como ponto de entrada. Pré‑requisitos - api_access_token válido do usuário (ou agent bot), com acesso à conta - ACCOUNT_ID e INBOX_ID da mesma conta - Para alguns canais, a Inbox precisa estar com "Criar conversa via API" habilitado - Para canal E‑mail: existir o vínculo ContactInbox entre o contato e a Inbox com source_id correto 🔗 Endpoint POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations 🔐 Headers obrigatórios { "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", // Optional "private": false, // Optional "custom_attributes": { // Optional "example1": "valueXPTO" }, "additional_attributes": { // optional "mail_subject": "Protocolo de atendimento ABCD" }, "assignee_id": "1" // optional } 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 formato 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 principais inbox_id: Identificador da Inbox que pode ser obtido da barra do navegador (URI/rota) ao acessar a configuração de caixa de entrada. assignee_id(opcional): Identificador do agente que será atribuído no momento da criação. Para referenciar o contato envie um dos três campos abaixo: - contact_identifier: Identificador único do contato - contact_email: Email do contato - contact_phone_number: Número do contato message: A mensagem contendo seus campos: - content: que é o conteúdo da mensagem - message_type: - "incoming": mensagem vinda do cliente - "outgoing": enviada pelo agente - "activity": nota interna - private: se a mensagem é visível ao cliente (false) ou interna (true) additional_attributes -> mail_subject (opcional) Caso o ticket seja tratado via canal de email, você pode utilizar esse campo para customizar o assunto no email enviado ao contato quando a conversa se iniciar. custom_attributes (opcional, mas poderoso) Você pode adicionar qualquer campo customizado de conversa, já existente na sua configuração, direto aqui. Para saber como criar atributos customizados, veja essa FAQ. 🎯 O ticket já nasce como “em aberto”? Sim. O ticket será criado com status “open” por padrão, a menos que seja informado o campo status na requisição, o que o torna visível e pronto para atendimento imediato na caixa de entrada (inbox) especificada. 🧪 Como testar? 1. Acesse seu api_access_token no painel de configurações 2. Copie o ACCOUNT_ID, INBOX_ID e CLOUDCHAT_DOMAIN conforme descrito nesta FAQ de import 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 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 utiliza upsert, caso sejam fixados, o resultado será sempre um único contato sendo atualizado a cada chamada, com todas as conversas vinculadas a ele. Criação de Ticket não cria contato A criação manual de tickets via API não gera novos contatos. O sistema apenas utiliza contatos já existentes. Portanto, se o contato não existir, é necessário criá-lo previamente antes de iniciar uma conversa. Crie seguindo esta FAQ Fluxo exemplo para criar um E-mail com mensagem do usuário 1. Garantir/obter o contato - Buscar por 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 1. Vincular o contato à Inbox (ContactInbox) - POST /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes - Body: { "inbox_id": "INBOX_ID", "source_id": "<conforme canal>" } 1. Criar a conversa (sem mensagem inicial, se quiser registrar como cliente depois) - POST /api/v1/accounts/{account_id}/conversations - Body mínimo: { "source_id": "<...>", "inbox_id": "INBOX_ID", "status": "open" } 1. Postar mensagem como cliente (incoming) - POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages - Body: { "content": "Mensagem do cliente", "message_type": "incoming" } 1. Opcional: responder como agente (outgoing) - Mesmo endpoint de mensagens, com message_type: "outgoing" - Para canal E‑mail, content_attributes pode aceitar to_emails, cc_emails, bcc_emails conforme sua configuração Exemplo (Apps Script) — Fluxo exemplo para criar um E-mail com mensagem do usuário a partir do preenchimento de um Google Forms 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; // substitua pelo ID da conta var inboxId = INBOX_ID; // substitua pelo ID da inbox 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 (sem mensagem inicial) 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); }

Última atualização em Jan 21, 2026

Guia mestre: como acessar e operar dados do Cloud Chat via API

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. 🧠 Visão geral: existem 3 tipos 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 um objetivo claro. 📦 APIs de Extração de Dados Servem 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 🔍 APIs de Consulta em Tempo Real Servem 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 ✏️ APIs de Atualização e Ação ⚠️ Essas 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: 📦 API de Extração de Dados (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: 🔍 APIs de Consulta em Tempo Real (Contacts, Tickets e Messages) ✏️ Quando usar APIs de Atualização e Ação ⚠️ Atenção: essas APIs modificam dados reais no Cloud Chat. Use APIs de ação 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: ✏️ APIs de Atualização e Ação em Tickets 🧩 Regra prática para escolher a API certa Pergunte sempre: - Quero analisar dados históricos? → Use API de Extração de Dados - 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 Se ainda estiver em dúvida, não avance. Usar a API errada pode gerar efeitos colaterais inesperados. 🚦 Níveis de cuidado (importante) - Extração de dados → risco baixo - Consulta em tempo real → risco médio - Atualização / ação → risco 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 - 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 📌 Próximos passos Agora escolha a documentação certa para o seu caso: - 📦 API de Extração de Dados (Data Extract API) - 🔍 APIs de Consulta em Tempo Real (Contacts, Tickets e Messages) - ✏️ APIs de Atualização e Ação em Tickets Esse guia deve sempre ser lido antes das FAQs técnicas acima.

Última atualização em Apr 13, 2026

APIs de consulta em tempo real: contatos, tickets e mensagens

Neste artigo, você encontra os endpoints para leitura em tempo real de dados do Cloud Chat: contatos, tickets e mensagens. Nenhum desses endpoints altera dados. Sobre o namespace /api/client/ 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 os endpoints do namespace /api/v1/. As APIs de Consulta em Tempo Real permitem ler dados atuais do Cloud Chat, diretamente da base de produção, sem alterar nada no sistema. Elas 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?” 🧭 Antes de começar (leia isso) Se você ainda não sabe qual tipo de API usar, comece pela: 👉 🧭 Guia Mestre — Como acessar e operar dados do Cloud Chat via API Ele explica a diferença entre: - APIs de Extração de Dados (histórico / batch) - APIs de Consulta em Tempo Real (leitura) - APIs de Atualização e Ação (escrita) Esta FAQ cobre apenas leitura em tempo real. 🎯 Para que essas APIs servem? Use as APIs de Consulta em Tempo Real quando você precisa: - Ler dados agora - Integrar os dados do Cloud Chat a outro sistema - Exibir informações em uma aplicação - Tomar decisões baseadas no estado atual do atendimento Essas APIs não são para relatórios históricos nem para exportação em massa. ❌ Para que essas APIs NÃO servem? Não use essas APIs para: - Gerar relatórios - Exportar grandes volumes de dados - Analisar períodos longos de tempo - Criar ou atualizar tickets - Inserir mensagens 👉 Para isso, veja: - 📦 API de Extração de Dados (Data Extract API) - ✏️ APIs de Atualização e Ação em Tickets 🔑 Autenticação e domínio Todos os endpoints abaixo exigem: - {CLOUDCHAT_DOMAIN} → domínio da sua conta (ex: Cloud Chat.cloudhumans.com) - {ACCOUNT_ID} → ID da conta - api_access_token → token de administrador ou supervisor 🔎 1. Buscar contato por e-mail ou telefone Quando usar Use este endpoint quando você quer descobrir se um contato já existe no Cloud Chat. Exemplos: - Antes de criar um ticket - 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 importantes - Pelo menos um dos parâmetros (email ou phone_number) é obrigatório - Se ambos forem enviados, a API tenta fazer o match mais preciso possível O que ele 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 Use quando precisar buscar um contato por qualquer campo textual — nome, e-mail, telefone, identificador ou nome da empresa — sem saber exatamente qual campo contém a informação. Diferente do endpoint de busca por e-mail/telefone (seção 1), este endpoint faz uma 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 1 caractere). Busca parcial em: name, email, identifier, phone_number e company_name | | page | integer | Não | Página de resultados (padrão: 1, 15 resultados por página) | Campos pesquisados O endpoint busca simultaneamente em: - name — nome do contato - email — e-mail do contato - identifier — identificador externo - phone_number — telefone (busca com e sem prefixo +) - company_name — nome da empresa 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". Diferença entre os dois endpoints de busca | | Busca por e-mail/telefone (seção 1) | Busca por texto livre (esta seção) | |---|---|---| | 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) | 📋 2. Listar tickets de um contato Quando usar Use este endpoint quando você já tem o CONTACT_ID e quer listar os tickets desse cliente. Exemplos: - 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 ele retorna - IDs dos tickets - Status (open, resolved, etc.) - Prioridade - Inbox - Datas de criação - Se o ticket foi iniciado por campanha 💬 3. Listar mensagens de um ticket Quando usar Use este endpoint para recuperar o histórico de mensagens de um ticket específico. Exemplos: - Auditoria em tempo real - Exibição de 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 ele retorna - Conteúdo da mensagem - Tipo (incoming / outgoing) - Se é privada ou pública - Data de criação - Status da mensagem - Links dos anexos nas mensagens (se houverem) 🧠 Como essas APIs se conectam (fluxo típico) Um fluxo comum de uso é: 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 Tudo isso sem alterar nenhum dado. 🚦 Nível de risco dessas APIs Essas APIs são consideradas de risco médio, porque: - Não alteram dados - Mas consultam a base de produção em tempo real Boas práticas: - Evite loops agressivos - Use cache quando possível - Não use para exportação em massa ❌ Erros comuns - 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 📌 Próximos passos Agora você pode seguir para: - ✏️ APIs de Atualização e Ação em Tickets (quando precisar alterar status, prioridade ou criar mensagens) - 📦 API de Extração de Dados (Data Extract API) (para relatórios, BI e auditoria) E lembre-se: 👉 Sempre consulte o Guia Mestre antes de usar uma nova API.

Última atualização em Apr 13, 2026

APIs de atualização e ação em tickets

Neste artigo, você encontra os endpoints para modificar dados de tickets no Cloud Chat: alterar status, prioridade, time responsável e enviar mensagens via API. Estas APIs permitem modificar dados reais de tickets no Cloud Chat — como alterar status, prioridade, time, e enviar mensagens. 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. Autenticação Todos os endpoints abaixo exigem: | Header | Valor | |---|---| | content-type | application/json | | api_access_token | Token de administrador ou supervisor | 1. Alterar Status do Ticket (resolver, reabrir, etc.) POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}}/toggle_status Body { "status": "resolved" } Valores aceitos para status | Valor | Descrição | |---|---| | open | Reabrir ticket | | resolved | Resolver ticket | | pending | Marcar como pendente | Exemplo (curl) 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"}' Resposta Retorna o objeto da conversa atualizada com status 200 OK. Atenção: 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 PUT https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations/{{CONVERSATION_ID}} Body { "priority": "high" } Valores aceitos para priority | Valor | Descrição | |---|---| | nil / null | Sem prioridade | | low | Baixa | | medium | Média | | high | Alta | | urgent | Urgente | Exemplo (curl) 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"}' Importante: Este endpoint (PUT .../conversations/{ID}) aceita apenas o campo priority. Campos como status, team_id ou outros serão silenciosamente ignorados. 3. Alterar Status, Prioridade e Time (via Client API) Se você precisa alterar status, prioridade e/ou time em uma única chamada, use a Client API: PATCH https://{{CLOUDCHAT_DOMAIN}}/api/client/accounts/{{ACCOUNT_ID}}/conversations/{{DISPLAY_ID}} Atenção: Este endpoint usa o display_id (ID visível no Cloud Chat), não o conversation_id interno. Body { "status": "resolved", "priority": "high", "team_id": "1" } Campos aceitos | Campo | Descrição | |---|---| | status | Status do ticket (open, resolved, pending) | | priority | Prioridade (low, medium, high, urgent) | | team_id | ID do time para reatribuição | Todos os campos são opcionais — envie apenas o que deseja alterar. Exemplo (curl) 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 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) 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 ⚠️ Atenção: 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 | Se true, adiciona às labels existentes. Se false ou omitido, substitui todas as labels | Exemplo (curl) 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 acima). | 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 (veja APIs de Consulta em Tempo Real) 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 de configuração - CLOUDCHAT_DOMAIN: O domínio visível na URL do navegador ao acessar o Cloud Chat - 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

Última atualização em Apr 13, 2026

Como criar ou atualizar artigos na Central de Ajuda via API

Neste artigo, você vai aprender a criar novos artigos e atualizar artigos existentes na Central de Ajuda do Cloud Chat via API REST. Para criar um novo artigo na central de ajuda do Cloud Chat, basta realizar uma requisição POST para: https://{{{CLOUDCHAT_DOMAIN}}}/api/v1/accounts/{{ACCOUNT_ID}}/portals/{{PORTAL_SLUG}}/articles Requisição com campos de exemplo: 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, //Deve iniciar como draft! "title": "Título do artigo", "author_id": 1, "category_id": 1 }' Para marcar o artigo como "publicado" é necessário fazer uma segunda request, dessa vez um PUT, alterando o status para 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, // --- Demais campos abaixo são opcionais --- //"title": "...", //"content": "...", //"author_id": 2, //"category_id": 20, }' Para remover um artigo, basta passar o método como DELETE e um body vazio: 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' \ --data '{ "name": "Help name", "config": { "allowed_locales": ["en", "es"] } }' Parâmetros necessários CLOUDCHAT_DOMAIN: Você pode obter seu domínio ao fazer login na sua conta no Cloud Chat. É 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 seu perfil de usuário no Cloud Chat (https://{{{CLOUDCHAT_DOMAIN}}}/app/accounts/{{{ACCOUNT_ID}}}/profile/settings) author_id e category_id podem ser encontrados ao inspecionar a requisição que é realizada no navegador durante alguma alteração na própria tela de artigos: Nota sobre PORTAL_SLUG O parâmetro PORTAL_SLUG na URL é o slug do portal (ex: meu-portal), não um ID numérico. Você encontra o slug na URL do portal na interface do Cloud Chat.

Última atualização em Apr 13, 2026