📌 ¿Qué permite esta funcionalidad?
Esta API permite que usted cree un ticket en Cloud Chat desde cualquier sistema externo, como:
-
Un sistema de telefonía (ej: cuando llega una llamada)
-
Un formulario completado en su sitio web
-
Una integración con CRM, ERP o cualquier herramienta personalizada
Al usar esta ruta, usted puede:
-
Crear un nuevo ticket con estado abierto, pendiente o cerrado
-
Asociar el ticket a un contacto mediante correo electrónico, teléfono o identificador
-
Incluir un mensaje inicial (entrada o salida)
-
Definir atributos personalizados de la conversación en el momento de la creación
🧭 ¿Cuándo usar esta API?
Utilice cuando sea necesario iniciar una conversación en Cloud Chat sin que el cliente haya enviado un mensaje por un canal activo.
Ejemplos:
-
¿Recibió una llamada fuera de Cloud Chat? → Genere un ticket con el resumen de la llamada.
-
¿Alguien completó un formulario? → Cree el ticket automáticamente y comience la gestión por correo electrónico.
-
¿Quiere centralizar comunicaciones que provienen de otras fuentes? → Use esta API como punto de entrada.
🔗 Endpoint
POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/conversations
🔐 Encabezados obligatorios
{
"content-type": "application/json",
"api_access_token": "SU_TOKEN_DE_API"
}
🧾 Cuerpo de la solicitud
{
"inbox_id": "1",
"contact_identifier": "id_123",
"contact_email": "[email protected]",
"contact_phone_number": "+12345",
"message": {
"content": "Hola, acabo de completar el formulario en el sitio y necesito ayuda.",
"message_type": "incoming"
},
"status": "open", // Opcional
"private": false, // Opcional
"custom_attributes": { // Opcional
"example1": "valorXPTO"
},
"additional_attributes": { // Opcional
"mail_subject": "Protocolo de atención ABCD"
},
"assignee_id": "1" // Opcional
}
🧠 Explicación de los campos principales
inbox_id: Identificador de la Bandeja de entrada que puede obtenerse de la barra del navegador (URI/ruta) al acceder a la configuración de la bandeja.
assignee_id (opcional): Identificador del agente que será asignado en el momento de la creación.
Para referenciar el contacto, envíe uno de los siguientes tres campos:
-
contact_identifier: Identificador único del contacto -
contact_email: Correo electrónico del contacto -
contact_phone_number: Número del contacto
message: El mensaje que contiene sus campos:
-
content: que es el contenido del mensaje
-
message_type:
-
"incoming": mensaje recibido del cliente
-
"outgoing": enviado por el agente
-
"activity": nota interna
-
-
private: si el mensaje es visible para el cliente (false) o interno (true)
additional_attributes → mail_subject (opcional)
Si el ticket se gestiona vía canal de email, puede usar este campo para personalizar el asunto en el email enviado al contacto cuando comience la conversación.
custom_attributes (opcional, pero potente)
Puede añadir cualquier campo personalizado de la conversación, ya existente en su configuración, directamente aquí. Para saber cómo crear atributos personalizados, vea esta FAQ.
🎯 ¿El ticket nace como “abierto”?
Sí. El ticket se creará con estado “open” por defecto, a menos que se indique el campo estado en la solicitud, lo que lo hace visible y listo para atención inmediata en la bandeja de entrada (inbox) especificada.
🧪 ¿Cómo probar?
-
Acceda a su api_access_token en el panel de configuraciones
-
Copie el ACCOUNT_ID, INBOX_ID y CLOUDCHAT_DOMAIN según lo descrito en esta FAQ de importación
-
Envíe la solicitud vía Postman o script
-
Verifique en Cloud Chat si el ticket apareció en la Bandeja correcta, con la información completa
⚠️ Errores comunes
Uso incorrecto de identificadores únicos
Los campos identifier, phone_number y email son atributos únicos del contacto. No deben fijarse en solicitudes de creación de tickets.
Como la solicitud usa upsert, si se fijan, el resultado será siempre un único contacto siendo actualizado en cada llamada, con todas las conversaciones vinculadas a él.
La creación de Ticket no crea contacto
La creación manual de tickets vía API no genera nuevos contactos. El sistema solo utiliza contactos ya existentes.
Por lo tanto, si el contacto no existe, es necesario crearlo previamente antes de iniciar una conversación. Crea siguiendo esta FAQ!