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