Cuándo usarlo
- Tu sistema necesita iniciar una atención por correo electrónico, sin esperar a que el cliente escriba primero.
- Quieres enviar un correo transaccional (confirmación, cobro, aviso de entrega) y que la respuesta del cliente llegue a tu bandeja de entrada de Cloud Chat como una conversación normal.
- Necesitas que la misma solicitud pueda repetirse de forma segura, sin generar dos conversaciones ni dos correos.
Para comunicarte con muchas personas a la vez, usa "Campanhas" (Campañas). Esta API es para envíos individuales: un contacto por llamada.
Requisitos previos
- Una bandeja de entrada de correo electrónico ya conectada y funcionando.
- Un token de acceso a la API pública de Cloud Humans.
- La bandeja de entrada no puede tener activada la opción "Manter Conversa Única" (Mantener conversación única). Con ella activa, el mensaje se adjuntaría a la conversación anterior y tu asunto sería ignorado; por eso la API lo rechaza con
inbox_locked_to_single_conversation, en lugar de hacer algo distinto de lo que pediste.
Cómo funciona
Llamada
POST /cloudchat/v1/accounts/{account_id}/conversations
Encabezados: Authorization: Bearer <token> y 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"
}
Identifica al destinatario por email o por contact_id: uno de los dos, nunca ambos juntos. Con email, el contacto se crea si todavía no existe.
La respuesta incluye id (número de la conversación), message_id y dispatch_status, que vale created para un envío nuevo y duplicate para una repetición.
Repetir de forma segura
Envía tu propio idempotency_key, de hasta 128 caracteres. Si la misma clave llega de nuevo, la API no crea otra conversación ni envía otro correo: devuelve la conversación original con dispatch_status: duplicate. La clave es válida por 24 horas.
La clave es por bandeja de entrada: la misma clave en otra bandeja es un envío nuevo, no una repetición.
Reutilizar una clave con contenido diferente se rechaza con idempotency_key_payload_mismatch, en lugar de descartar el mensaje nuevo en silencio.
Copias y adjuntos
cc_emailsybcc_emailsaceptan una lista o un texto separado por comas, con un máximo de 25 direcciones en total.- Usa
attachment_blob_idspara archivos ya cargados en la plataforma yattachment_urlspara enlaces públicos. Son como máximo 10 adjuntos, de los cuales hasta 5 por URL.
Cuándo la API rechaza la solicitud
| Código | Qué pasó |
|---|---|
inbox_not_assigned |
La bandeja no existe o tu acceso no la alcanza |
subject_required / content_required |
Faltó el asunto o el cuerpo |
invalid_email / invalid_recipient |
Dirección mal formada |
recipient_suppressed |
La dirección no es entregable: tuvo un hard bounce, fue marcada como spam o ya falló en esta bandeja |
too_many_recipients / too_many_attachments |
Se superaron los límites anteriores |
email_claimed_by_another_contact |
La dirección ya pertenece a otro contacto en esta bandeja |
Cada código es estable: manéjalo en tu sistema, en lugar de leer el mensaje de texto.
Observaciones
- El límite es de 30 envíos por minuto por cuenta.
- La conversación se crea marcada como iniciada por tu equipo, lo que mantiene correctas las métricas de tiempo de respuesta.
- El correo sale desde la propia bandeja de entrada, por lo que el remitente, la firma y el dominio son los que ya configuraste.