Cuándo usar
- 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 crear dos conversaciones ni enviar dos correos.
Para comunicarte con muchísima gente a la vez, usa las Campañas. Esta API es para envíos unitarios: 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 Mantener Conversación Única. Con ella activa, el mensaje se adjuntaría a la conversación antigua y se ignoraría el asunto — por eso la API rechaza con
inbox_locked_to_single_conversation, en lugar de hacer algo diferente a lo solicitado.
Cómo funciona
Llamada
POST /cloudchat/v1/accounts/{account_id}/conversations
Cabeceras: Authorization: Bearer <token> y cloudchat-instance.
{
"inbox_id": 12,
"email": "[email protected]",
"name": "Maria Silva",
"subject": "Tu pedido ha sido enviado",
"content": "¡Hola! Tu pedido salió para entrega hoy.",
"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 aún no existe.
La respuesta incluye id (número de la conversación), message_id y dispatch_status, que puede ser created para un envío nuevo y duplicate para una repetición.
Repetir de forma segura
Envía una idempotency_key propia, 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 la nueva mensaje en silencio.
Copias y adjuntos
cc_emailsybcc_emailsaceptan una lista o un texto separado por comas, sumando un máximo de 25 direcciones.- Usa
attachment_blob_idspara archivos ya enviados a la plataforma yattachment_urlspara enlaces públicos. Son hasta 10 adjuntos, de los cuales hasta 5 por URL.
Cuándo la API rechaza
| Código | Qué ocurrió |
|---|---|
inbox_not_assigned |
La bandeja no existe o no tienes acceso a ella |
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 rebote duro, fue marcada como spam, o ya falló en esta bandeja |
too_many_recipients / too_many_attachments |
Se superaron los límites |
email_claimed_by_another_contact |
La dirección ya pertenece a otro contacto en esta bandeja |
Cada código es estable: trátalo 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 aparece marcada como iniciada por ustedes, lo que mantiene correctas las métricas de tiempo de respuesta.
- El correo sale por la propia bandeja, así que remitente, firma y dominio son los que ya configuraste.