Principal APIs
🔗

APIs

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

API: Enviar Mensagem Proativa pelo WhatsApp

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. API: Enviar Mensagem Proativa pelo WhatsApp 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 Oct 21, 2025

Cloud Chat: Import em massa de contatos via API

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 Aug 08, 2025

API: Enviar Mensagem Proativa pelo WhatsApp via integração com Hubspot

Envio de mensagens proativas em disparos de webhook via hubspot 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. Exemplo de configuração de webhook utilizando workflows do Hubspot Para criar um webhook de disparo proativo 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 do payload para efetuar o disparo, adicionando os campos estáticos de template_name e inbox_id, o campo dinâmico obrigatório phone_number, bem como quaiquer outros campos dinâmicos definidos na template escolhida: 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 Aug 08, 2025

API: Import de Contato via integração com Hubspot

Import de Contato utilizando disparo de webhook no hubspot Utilizando nosso endpoint de importação, é possível criar ou atualizar seus contatos no Cloud Chat através de webhooks integrados ao Hubspot. 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 Aug 08, 2025

API: Import de Contato

Import de Contato via API Para importar ou atualizar contatos via API no Cloud Chat, basta enviar uma POST request para https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import enviando a chave de acesso e os campos solicitados abaixo. 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: API_TOKEN' \ --data --data '{"phone_number": "+5599123456789", "identifier": "CUSTOM_ID", "email": "[email protected]", "name": "Contact Name", "CUSTOM_ATTRIBUTE_1": "123456789", "company_name": "Empresa X", "tags": "tag1, tag2, tag3 [...]"}' 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) Corpo da requisição O corpo da requisição possui os seguintes campos, onde pelo menos um dentre os campos phone_number, identifier e email deve estar presente. Obs.: Campos customizados podem ser adicionados no corpo da requisição livremente utilizando a chave obtidada na aba de gerenciamento de Atributos Personalizados: Tags são similarmente adicionadas ao contato inserindo seus nomes em uma lista separada por vírgulas no campo tags.

Última atualização em Aug 08, 2025

Remoção em massa de Tags de Contatos via API no Cloud Chat

Para remoção em massa de tags de contatos via API no Cloud Chat, basta enviar uma requisição POST 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"] } ] }

Última atualização em Aug 09, 2025

Atualização de Atributos Customizados em Conversas 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 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)".

Última atualização em Aug 09, 2025

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

A Data Extract API permite exportar dados completos dos seus tickets direto da sua conta no CloudChat, com datas, status, responsáveis, tempos de resposta e muito mais. Ideal para relatórios personalizados e integrações externas. Requisição base: curl --location 'https://{CLOUDCHAT_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T01:58:59&endDate=2025-03-28T01:59:00&type=BASE_TICKET_METRICS' \ --header 'Accept: application/json' \ --header 'api_access_token: {API_TOKEN}' O que você precisa substituir: 1. {CLOUDCHAT_DOMAIN}: seu domínio CloudChat (ex: app.cloudchat.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 CloudChat. É a parte que aparece na URL do navegador, por exemplo: {ACCOUNT_ID} - Após o login, verifique a URL da sua dashboard inicial. O ID da conta aparece na URL como: app/accounts/1/dashboard. Encontrado na URL do seu Cloud Chat, após "accounts"; ex.: https://cloudchat.cloudhumans.com/app/accounts/**1**/conversations/6341 (nesse caso, o account_id é 1) {API_TOKEN} - O token de API deve ser gerado a partir do perfil de um usuário com permissão de administrador ou supervisor (na configuração de perfil): Quais parâmetros são obrigatórios? Ao fazer a requisição para a API, você deve informar os seguintes parâmetros: - startDate: Data e hora de início da extração. Formato esperado: yyyy-MM-ddTHH:mm:ss (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 CloudChat. Esse valor é informado no caminho da URL (ex: /accounts/1/data_extracts, onde o ID da conta é 1). Observação sobre o intervalo de datas Para garantir estabilidade e performance, o intervalo máximo permitido por requisição é de 5 dias. Se você deseja exportar dados de um período maior (por exemplo, 30 dias), é possível dividir a consulta em múltiplas requisições. Exemplo: Para extrair dados de um mês completo, você pode fazer 6 requisições consecutivas com intervalos de até 5 dias cada, variando o startDate e endDate de acordo com o período desejado. Tipos de extração disponíveis via API A Data Extract API agora suporta os seguintes valores para o parâmetro type: - BASE_TICKET_METRICS - TICKET_METRICS_WITH_AGENT_INFORMATION - TICKET_SUMMARY - CAMPAIGN_DELIVERY_EVENTS (novo) - 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) ⚠️ 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" } ] 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 CloudChat, centralizando e rastreando, por contato e campanha, o status de mensagens enviadas. O objetivo é consolidar em um único ponto dados de eventos de campanha como envio, recebimento, leitura, resposta e erros. Campos retornados: - id: Identificador único do evento de entrega da campanha - campaignId: ID da campanha - campaignTitle: Título da campanha - audience: Nome do público da campanha - contactId: ID do contato - contactName: Nome do contato - contactEmail: E-mail do contato - contactPhoneNumber: Número de telefone do contato - ticketId: ID interno do ticket vinculado - displayTicketId: ID visível do ticket (exibido na URL da conversa / ticket) - messageSent: Indica se a mensagem foi enviada com sucesso para a API do WhatsApp (Meta) - sentAt: 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 CloudChat - 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 CloudChat, 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 CloudChat - 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" } ] by CloudChat

Última atualização em Nov 05, 2025

Cloud Chat: Import de histórico de tickets

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 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) 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 Aug 08, 2025

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. 🔗 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 } 🧠 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!

Última atualização em Oct 15, 2025