Abrir conversa de e-mail pela API

Quando usar

Seu sistema precisa iniciar um atendimento por e-mail, sem esperar o cliente escrever primeiro.
Você quer enviar um e-mail transacional (confirmação, cobrança, aviso de entrega) e que a resposta do cliente caia na sua caixa de entrada do Cloud Chat, como uma conversa normal.
Você precisa que a mesma requisição possa ser repetida com segurança, sem gerar duas conversas nem dois e-mails.

Para falar com muita gente de uma vez, use as Campanhas. Esta API é para disparo unitário: um contato por chamada.

Pré-requisitos

Uma caixa de entrada de e-mail já conectada e funcionando.
Um token de acesso à API pública da Cloud Humans.
A caixa de entrada não pode estar com a opção Manter Conversa Única ligada. Com ela ativa, a mensagem seria anexada à conversa antiga e o seu assunto seria ignorado — por isso a API recusa com inbox_locked_to_single_conversation, em vez de fazer algo diferente do que você pediu.

Como funciona

Chamada

POST /cloudchat/v1/accounts/{account_id}/conversations

Cabeçalhos: Authorization: Bearer <token> e cloudchat-instance.

{
  "inbox_id": 12,
  "email": "[email protected]",
  "name": "Maria Silva",
  "subject": "Seu pedido foi enviado",
  "content": "Olá! Seu pedido saiu para entrega hoje.",
  "idempotency_key": "pedido-12345"
}

Identifique o destinatário por email ou por contact_id — um dos dois, nunca os dois juntos. Com email, o contato é criado se ainda não existir.

A resposta traz id (número da conversa), message_id e dispatch_status, que vale created para um disparo novo e duplicate para uma repetição.

Repetir com segurança

Envie um idempotency_key seu, com até 128 caracteres. Se a mesma chave chegar de novo, a API não cria outra conversa nem envia outro e-mail: devolve a conversa original com dispatch_status: duplicate. A chave vale por 24 horas.

A chave é por caixa de entrada: a mesma chave em outra caixa é um disparo novo, não uma repetição.

Reaproveitar uma chave com conteúdo diferente é recusado com idempotency_key_payload_mismatch, em vez de descartar a mensagem nova em silêncio.

Cópias e anexos

cc_emails e bcc_emails aceitam uma lista ou um texto separado por vírgulas, somando no máximo 25 endereços.
Use attachment_blob_ids para arquivos já enviados à plataforma e attachment_urls para links públicos. São no máximo 10 anexos, dos quais até 5 por URL.

Quando a API recusa

Código	O que aconteceu
`inbox_not_assigned`	A caixa não existe ou o seu acesso não a alcança
`subject_required` / `content_required`	Faltou o assunto ou o corpo
`invalid_email` / `invalid_recipient`	Endereço mal formado
`recipient_suppressed`	O endereço não é entregável: deu hard bounce, foi marcado como spam, ou já falhou nesta caixa
`too_many_recipients` / `too_many_attachments`	Passou dos limites acima
`email_claimed_by_another_contact`	O endereço já pertence a outro contato nesta caixa

Cada código é estável: trate-o no seu sistema, em vez de ler a mensagem de texto.

Observações

O limite é de 30 disparos por minuto por conta.
A conversa nasce marcada como iniciada por vocês, o que mantém corretas as métricas de tempo de resposta.
O e-mail sai pela própria caixa de entrada, então remetente, assinatura e domínio são os que você já configurou.