📌 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"
}
}
🧠 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.
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)
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?
-
Acesse seu api_access_token no painel de configurações
-
Copie o ACCOUNT_ID, INBOX_ID e CLOUDCHAT_DOMAIN conforme descrito nesta FAQ de import
-
Envie a requisição via Postman ou script
-
Verifique no Cloud Chat se o ticket apareceu na Inbox correta, com as informações completas