Canal externo de Chat2Desk OnCloud
El canal externo permite integrar en Chat2Desk cualquier canal de mensajería que la plataforma no soporte de forma nativa: la mensajería de tu propia app, un portal, un chat de un proveedor o cualquier sistema que pueda enviar y recibir mensajes. Los mensajes de tus usuarios llegan a Chat2Desk sin pasar por un mensajero conocido, y tus operadores los atienden junto con WhatsApp y el resto de los canales, con chatbots, Chatbots Conversacionales y respuestas automáticas incluidos.
En resumen
- Entrada: tu sistema envía cada mensaje del usuario a Chat2Desk con
POST /v1/messages/inbox. - Salida: Chat2Desk te avisa de cada respuesta con un webhook del evento
outbox, y tu sistema la reenvía al usuario. - Estados de entrega: los recibes con
outbox_statusy los actualizas conPUT /v1/messages/{id}/status/{estatus}. - Activación: la hace el soporte técnico de Chat2Desk, que crea el canal y te entrega su
channel_id.
Cómo funciona
- Tu usuario escribe en tu canal (tu app, tu portal o el sistema que integres).
- Tu servidor envía el mensaje a Chat2Desk con
POST /messages/inbox. - Los operadores, los chatbots o las respuestas automáticas responden en Chat2Desk.
- Chat2Desk te avisa por webhook (
outbox) y tu servidor entrega la respuesta al usuario en tu canal. - Tu servidor informa el estado de entrega (
PUT /messages/{id}/status/{estatus}), y Chat2Desk te notifica los cambios de estado conoutbox_status.
Paso a paso
1. Pide que creen tu canal externo
Solicita al soporte técnico de Chat2Desk la creación de un canal nuevo con el transporte «canal externo» habilitado. El equipo de soporte lo habilita y te devuelve el channel_id.
El channel_id solo se puede consultar por la API, no en la interfaz web. Para listarlo con tu token:
curl -H "Authorization: TU_TOKEN" https://api.chat2desk.com.mx/v1/channelsSi todavía no tienes tu token, está en la guía de la API.
2. Crea el webhook de respuestas
Con POST /v1/webhooks crea un webhook suscrito a los eventos outbox (un mensaje saliente de Chat2Desk hacia tu usuario) y outbox_status (cambios de estado del envío). Limita los eventos a tu canal con el campo channels. Verifica siempre la firma HMAC de cada entrega: la explicación y el código están en la sección de webhooks de la guía de la API.
3. Envía los mensajes de tus usuarios
Cada mensaje entrante se envía con POST /v1/messages/inbox. Ejemplo con valores ficticios:
{
"channel_id": "123",
"body": "Hola, necesito ayuda con mi pedido",
"from_client": {
"id": "usuario-4821",
"nickname": "Ana",
"avatar": "https://ejemplo.com/avatares/ana.png",
"client_phone": 5512345678,
"custom_fields": { "1": "Plan Premium" }
},
"extra_data": { "external_id": "msg-90001" }
}| Campo | Qué es |
|---|---|
channel_id | El identificador de tu canal externo, que te entrega soporte |
body | Texto del mensaje |
attachment y attachment_filename | Dirección directa de un archivo adjunto y su nombre original |
location | Ubicación en formato lat lng |
from_client.id o from_client.phone | Cómo identificas al cliente: id es cualquier cadena propia (que no sea un teléfono); si lo identificas con un teléfono, usa phone (solo dígitos). Envía solo uno de los dos: si mandas ambos o ninguno, la API devuelve un error |
from_client.nickname y from_client.avatar | Nombre y avatar del cliente que se muestran en Chats (opcionales) |
from_client.client_phone y from_client.custom_fields | Teléfono y campos personalizados de la ficha del cliente |
extra_data.external_id | Tu propio identificador del mensaje (opcional): vuelve en el evento inbox del webhook y también aparece en GET /messages |
4. Entrega las respuestas
Cuando llegue un evento outbox, toma el texto y los adjuntos y entrégalos a tu usuario en tu canal. Responde al webhook con un código 2xx lo antes posible y procesa el contenido después. Si tu servidor no responde, Chat2Desk reintenta a los 10 segundos, a los 5 minutos y a las 2 horas, y desactiva el webhook si pasan 5 horas sin respuesta.
5. Informa el estado de entrega
Cuando tu canal confirme que el usuario recibió o leyó la respuesta, actualiza el estado con PUT /v1/messages/{id}/status/{estatus}. Solo funciona para mensajes salientes de un canal externo.
| Estado | Valor |
|---|---|
pending | 1 |
sent | 2 |
failed | 3 |
canceled | 5 |
delivered | 6 |
seen | 7 |
Chat2Desk también te envía el evento outbox_status cuando el estado de un envío cambia (por ejemplo, de enviado a entregado o a fallido).
Buenas prácticas
- Correlaciona con
external_id: guarda el identificador de tu mensaje para relacionar cada respuesta con su conversación. - Identifica siempre al cliente de la misma forma (
idophone), para que no se creen clientes duplicados. - Respeta los límites: el envío de mensajes admite unos 15–20 por segundo; si lo excedes, la API responde
429 Too many requests. - Verifica la firma de cada webhook antes de procesarlo.
- Prueba antes de lanzar: Chat2Desk no tiene un entorno de pruebas aparte. Para probar, pide a soporte un canal de prueba (con su transporte) y úsalo con tus usuarios de prueba.
Preguntas frecuentes
¿Qué canales puedo integrar? Cualquier canal de mensajería que no sea nativo en Chat2Desk y que pueda enviar y recibir mensajes por API: la mensajería de tu app, un portal propio u otro sistema.
¿Cómo se activa? Pide al soporte técnico de Chat2Desk un canal nuevo con el transporte «canal externo» habilitado. Soporte lo habilita y te devuelve el channel_id.
¿Dónde veo mi channel_id? Solo por la API, por ejemplo con GET /v1/channels. No aparece en la interfaz web.
¿Los chatbots y las respuestas automáticas funcionan en un canal externo? Sí: lo que responden los operadores, los chatbots, los Chatbots Conversacionales y las respuestas automáticas llega a tu sistema por el evento outbox.
¿Hay un entorno de pruebas? No. Se crean canales y transportes de prueba; pídelos a soporte.
¿Dónde veo todos los parámetros? En la referencia completa de la API.
¿Necesitas ayuda con tu integración?
Cuéntanos qué canal quieres integrar y te orientamos. Si todavía no tienes cuenta, empieza con la prueba gratuita.
¿Prefieres escribirnos? Habla con un asesor de Chat2Desk por WhatsApp.