# Canales personalizados Conecte cualquier plataforma de mensajería o herramienta de comunicación a la plataforma mediante canales personalizados. Esto le permite llevar mensajes de plataformas como widgets de chat en vivo en sitios web, sistemas de correo electrónico, CRM o cualquier otro servicio a su bandeja de entrada, y responder a ellos con su Agente de IA. --- ## ¿Qué son los canales personalizados? Los canales personalizados amplían la plataforma más allá de sus plataformas de mensajería integradas ([WhatsApp](whatsapp-business.md), [SMS](sms.md), [Instagram](instagram-dms.md), [Messenger](facebook-messenger.md)). Con los canales personalizados, puede: - **Recibir mensajes** desde cualquier plataforma externa en la bandeja de entrada unificada de la plataforma. - **Enviar respuestas** desde la aplicación de vuelta a su plataforma externa automáticamente. - **Usar un Agente de IA** para responder a mensajes de cualquier fuente. - **Realizar un seguimiento de todas las conversaciones** junto con sus otros canales en una sola bandeja de entrada. Esto es ideal para empresas que utilizan herramientas de comunicación especializadas, tienen una plataforma personalizada o desean tener todos los mensajes de los clientes en un solo lugar. ::: note **Nota:** Los canales personalizados requieren cierta configuración técnica. Si usted o su equipo no se sienten cómodos con las integraciones técnicas, es posible que desee pedir ayuda a su desarrollador web o equipo de TI con esta sección. ::: --- ## Cómo funciona Los canales personalizados funcionan enviando mensajes de un lado a otro entre su plataforma externa y la plataforma mediante **webhooks** (mensajes automatizados enviados entre sistemas a través de Internet). Este es el flujo: ``` Your Platform ──(sends message to)──> The App | AI Agent responds Contact saved Message stored | The App ──(sends reply to)──> Your Platform ``` 1. **Mensajes entrantes:** Su plataforma externa envía mensajes a una dirección web (URL). Piense en ello como si su plataforma "publicara" un mensaje en el buzón de la plataforma. 2. **Procesamiento:** La plataforma crea o actualiza el contacto, almacena el mensaje y hace que un Agente de IA genere una respuesta (si está activo). 3. **Mensajes salientes:** Cuando la plataforma envía una respuesta (ya sea desde la IA o escrita por usted), envía el mensaje a una URL en su plataforma, donde su sistema puede entregarlo al usuario final. --- ## Configuración de mensajes entrantes (de su plataforma a la aplicación) Para enviar mensajes desde su plataforma externa a la aplicación, su plataforma debe enviar datos a la siguiente URL. Su desarrollador reconocerá esto como una solicitud POST estándar (una forma común en que un sistema envía datos a otro a través de Internet). ### Dónde enviar los mensajes ``` POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY ``` Reemplace `YOUR_API_KEY` con su clave de API (un código privado que demuestra a la plataforma que su plataforma tiene permiso para enviarle mensajes). Encuéntrela o genérela en **Configuración → Integraciones → Clave de API**. ### Formato del mensaje Envíe los datos del mensaje en el siguiente formato (JSON): ```json { "customData": { "messageSid": "unique-message-id-123", "fromId": "user-456", "toId": "your-business-id", "body": "Hello, I have a question about your service.", "status": "received", "channel": "my-live-chat", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "mediaUrl": null, "mediaContentType": null }, "messageType": "text" } ``` **Qué significa cada parte:** - `messageSid` - Un ID único para este mensaje específico (su sistema lo crea). Se utiliza para evitar que el mismo mensaje se procese dos veces. - `fromId` - Quién envió el mensaje (podría ser un ID de usuario, correo electrónico o número de teléfono de su sistema). - `toId` - Su identificador de empresa (puede ser cualquier etiqueta que elija). - `body` - El texto real del mensaje. - `channel` - Una etiqueta que usted elige para identificar de dónde proviene el mensaje (p. ej., "website-chat", "email"). ### Referencia completa de campos | Campo | ¿Obligatorio? | Qué hace | |---|---|---| | `customData.messageSid` o `customData.id` | Sí | Un ID único para este mensaje (evita duplicados) | | `customData.fromId` | Sí | Identifica quién envió el mensaje (p. ej., un ID de usuario, correo electrónico o número de teléfono de su sistema) | | `customData.toId` | Sí | Identifica el lado receptor (su empresa). Puede ser cualquier texto que elija. | | `customData.body` | Sí | El texto real del mensaje. No puede estar vacío. | | `customData.status` | No | Estado del mensaje. Déjelo fuera para usar el valor predeterminado (`"received"`). | | `customData.channel` | No | Una etiqueta para la fuente (p. ej., `"live-chat"`, `"email"`, `"my-crm"`). Le ayuda a identificar de dónde provienen los mensajes en su bandeja de entrada. | | `customData.campaignId` | No | Un ID de campaña/Agente. Úselo para enrutar el mensaje a una configuración de IA específica. | | `customData.firstName` | No | Nombre del contacto. Se incluye al crear un nuevo registro de contacto. | | `customData.lastName` | No | Apellido del contacto. Se incluye al crear un nuevo registro de contacto. | | `customData.email` | No | Dirección de correo electrónico del contacto. Se incluye al crear un nuevo registro de contacto. | | `customData.mediaUrl` | No | Un enlace a un archivo adjunto (imagen, video, audio o documento). También puede ser un archivo codificado en base64 (ver más abajo). | | `customData.mediaContentType` | No | El tipo de archivo (p. ej., `"image/jpeg"`, `"video/mp4"`, `"audio/ogg"`, `"application/pdf"`). Obligatorio si incluye `mediaUrl`. | | `messageType` | No | Tipo de mensaje. Déjelo fuera para texto normal. Establézcalo en `"reaction"` para reacciones con emojis. | ### Reacciones con emojis Si tu plataforma admite reacciones con emojis (un pulgar hacia arriba en un mensaje, por ejemplo), envíalas como una reacción en lugar de como un mensaje de texto: establece `messageType` en `"reaction"` y coloca solo el emoji en `customData.body`. ```json { "messageType": "reaction", "customData": { "messageSid": "reaction-123", "fromId": "user-42", "toId": "my-business", "body": "👍" } } ``` El asistente lo tratará entonces de la forma que esperarías: - Una reacción a una pregunta que hizo el asistente (por ejemplo, "¿Te viene bien el jueves?") se trata como la respuesta, y el asistente responde. - Una reacción a un mensaje de cierre (por ejemplo, "¡Hablamos pronto!") finaliza la conversación discretamente. No se envía ninguna respuesta. Si tu plataforma convierte las reacciones en texto como "Reaccionó con: 👍", el asistente ve un mensaje de texto normal y decide por sí mismo si responder o no. Enviar el tipo de reacción evita eso. ### Qué obtiene a cambio Una solicitud exitosa devuelve: ```json { "success": true, "messageId": "1234567890" } ``` Si algo sale mal, recibirá un mensaje de error explicando el problema: ```json { "error": "Message body cannot be empty" } ``` ### Códigos de estado | Código | Qué significa | |---|---| | `200` | Éxito: mensaje recibido y en proceso de procesamiento | | `400` | Algo está mal con su solicitud: verifique si faltan campos obligatorios o si el cuerpo del mensaje está vacío | | `401` | Clave de API no válida: verifique la clave en **Configuración → Integraciones → Clave de API** | | `405` | Método de solicitud incorrecto: asegúrese de estar usando POST, no GET | | `500` | Algo salió mal por parte de la plataforma: inténtelo de nuevo en unos momentos | > Si establece `customData.status`, el único valor aceptado es `"received"`; omítalo por completo para usar el valor predeterminado en lugar de enviar cualquier otra cosa, o recibirá un `400`. --- ## Envío de archivos adjuntos multimedia (imágenes, videos, archivos) Puede incluir archivos adjuntos (imágenes, videos, audio, documentos) con sus mensajes. Hay dos formas de hacerlo: ### Opción 1: Enlace a un archivo Si el archivo ya está alojado en línea, proporcione la URL (dirección web) desde donde la plataforma pueda descargarlo: ```json { "customData": { "messageSid": "msg-789", "fromId": "user-456", "toId": "business-1", "body": "Here is a photo of the issue.", "channel": "support-portal", "mediaUrl": "https://example.com/uploads/photo.jpg", "mediaContentType": "image/jpeg" }, "messageType": "text" } ``` ### Opción 2: Incrustar el archivo directamente (Base64) Si el archivo no está alojado en línea, puede incrustarlo directamente en el mensaje como texto codificado (formato base64). Esto es común en integraciones técnicas donde su sistema genera archivos sobre la marcha. La plataforma decodificará y almacenará el archivo automáticamente: ```json { "customData": { "messageSid": "msg-790", "fromId": "user-456", "toId": "business-1", "body": "Screenshot attached.", "channel": "support-portal", "mediaUrl": "data:image/png;base64,iVBORw0KGgo...", "mediaContentType": "image/png" }, "messageType": "text" } ``` ::: note **Nota:** Incrustar archivos directamente hace que los datos del mensaje sean mucho más grandes. Para archivos grandes, es mejor alojar el archivo en línea y enviar un enlace (Opción 1) en su lugar. ::: --- ## Configuración de mensajes salientes (de la plataforma a su plataforma) Cuando la plataforma envía una respuesta en un canal personalizado (ya sea desde la IA o escrita por usted), envía automáticamente esa respuesta a una URL en su plataforma para que su sistema pueda entregarla al usuario final. > **Configure primero la URL del webhook.** Debe guardar la URL del webhook del canal personalizado antes de que se puedan entregar las respuestas. Si no se guarda ninguna URL, las respuestas se generan y almacenan, pero nunca se envían, y **no** mostrarán un estado de "Error", por lo que nada en su bandeja de entrada marcará el problema. Configure siempre la URL del webhook antes de entrar en funcionamiento. ### Indique a la aplicación dónde enviar las respuestas 1. En la barra lateral izquierda, haga clic en **Configuración** cerca de la parte inferior. 2. En el panel izquierdo de Configuración, bajo **Canales**, haga clic en **Canales**. 3. Busque la tarjeta **Canal personalizado** en la parte inferior de la página (después de Android SMS Gateway, iMessage, el widget de chat del sitio web, la cuenta de Twilio y el cumplimiento normativo). 4. Ingrese la **URL del Webhook**: la URL en su plataforma donde la IA debe enviar los mensajes salientes (su desarrollador configura esto para recibir y procesar respuestas). Debe ser una **URL HTTPS pública**: las direcciones `http://` y los hosts no públicos serán rechazados. 5. Haga clic en **Guardar**. ### Lo que la plataforma envía a su plataforma Cuando la plataforma envía una respuesta, su plataforma recibirá los siguientes datos: ```json { "contactId": "abc123", "messageId": "msg-456", "userId": "your-user-id", "body": "Thank you for your message! Here is the information you requested...", "toId": "user-456", "channel": "my-live-chat" } ``` ### Qué significa cada campo | Campo | Qué contiene | |---|---| | `contactId` | el ID interno de la plataforma para este contacto | | `messageId` | El ID único de este mensaje en la aplicación | | `userId` | Su ID de usuario | | `body` | El texto de la respuesta | | `toId` | El ID del contacto en su plataforma (esto coincide con el `fromId` que envió en el mensaje entrante) | | `channel` | La etiqueta del canal personalizado que asignó | Su plataforma recibe estos datos y los utiliza para entregar la respuesta al usuario final a través de su propio sistema. ### Cómo rastrea la entrega la plataforma Después de enviar la respuesta a su plataforma, la plataforma actualiza el estado del mensaje: - **Enviado** - Su plataforma recibió el mensaje correctamente. - **Fallido** - Su plataforma devolvió un error o no se pudo contactar con ella. La plataforma almacena los detalles del error con el mensaje para que pueda solucionar el problema. --- ## Envío de mensajes desde su sistema a la aplicación Además de recibir mensajes, también puede enviar mensajes salientes a través de un canal personalizado directamente desde su propio sistema. Esto es útil cuando desea iniciar una conversación o enviar un mensaje proactivo. > **Requisito del plan.** El envío y la sincronización de mensajes a través de la API requiere un plan que incluya acceso a la API y al menos un canal de mensajería. Si recibe un error `403` "permission denied / feature not enabled" (permiso denegado / función no habilitada), su plan actual no incluye esto; actualice su plan o póngase en contacto con el servicio de asistencia. ### Dónde enviar ``` POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY ``` ### Formato del mensaje ```json { "customData": { "fromId": "user-456", "customChannel": "my-live-chat", "body": "Hello! How can I help you today?", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com" } } ``` ### Campos obligatorios | Campo | Qué hace | |---|---| | `customData.fromId` | El ID del contacto en su plataforma | | `customData.customChannel` | El nombre de su canal personalizado (p. ej., "my-live-chat") | | `customData.body` | El texto del mensaje a enviar | Los campos opcionales (`campaignId`, `firstName`, `lastName`, `email`) funcionan igual que en los mensajes entrantes: ayudan a la plataforma a crear o actualizar el registro del contacto. ### Qué obtiene a cambio ```json { "success": true, "messageId": "generated-message-id", "contactId": "contact-id", "message": "Message sent successfully" } ``` --- ## Registro de mensajes enviados desde otro sistema A veces, ya ha enviado un mensaje a un contacto desde una herramienta diferente (por ejemplo, un flujo de trabajo en otra plataforma) y simplemente desea que la plataforma lo sepa para que la IA tenga el contexto completo. Esto es diferente al envío: la plataforma registra el mensaje pero **no** lo vuelve a entregar al contacto. ### Dónde enviar ``` POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY ``` Incluya `customData.fromId` (el ID del contacto en su plataforma) y `customData.body` (el texto del mensaje que ya se envió). ### Cómo se comporta - **El mensaje se registra, no se reenvía.** La plataforma lo almacena en la conversación solo como contexto. - **La IA se pausa en ese contacto de forma predeterminada.** Esto evita que el bot responda sobre un mensaje que un humano ya gestionó. Para mantener el bot activo, pase `customData.pauseAi: false`. - **Se pueden crear nuevos contactos automáticamente.** Incluya `customData.customChannel` y el contacto se creará si aún no existe. - **Los duplicados se ignoran.** Si vuelve a utilizar el mismo `messageSid`, la plataforma reconoce que el mensaje ya se ha registrado y no realiza cambios. > **Requisito del plan.** Al igual que el envío, la grabación de mensajes a través de la API requiere un plan que incluya acceso a la API y al menos un canal de mensajería. Un error de `403` "permission denied / feature not enabled" significa que su plan actual no incluye esto. --- ## Ejemplos del mundo real ### Chat en vivo en el sitio web Conecte un widget de chat en vivo en su sitio web a la plataforma para que su Agente de IA pueda responder a las preguntas de los visitantes: 1. Un visitante escribe un mensaje en el widget de chat de su sitio web. 2. Su widget de chat envía el mensaje a la plataforma. 3. El Agente de IA genera una respuesta. 4. La respuesta se envía de vuelta a su widget de chat, que la muestra al visitante. **Por qué es útil:** Los visitantes de su sitio web obtienen respuestas instantáneas impulsadas por IA a sus preguntas sin que usted necesite estar en línea. ### Correo electrónico Enrute las conversaciones por correo electrónico a través de la plataforma para que su Agente de IA pueda responder a los correos electrónicos: 1. Configure un sistema que reenvíe los correos electrónicos entrantes a la plataforma (utilizando la dirección del remitente del correo electrónico como `fromId`, el asunto y el cuerpo del correo electrónico como `body`, y `"email"` como `channel`). 2. El Agente de IA lee el correo electrónico y genera una respuesta. 3. La respuesta se envía de vuelta a su sistema de correo electrónico, que la envía como una respuesta de correo electrónico normal. **Por qué es útil:** Las preguntas frecuentes por correo electrónico (precios, horarios, disponibilidad) son respondidas al instante por su Agente de IA. > Si su sistema de correo electrónico utiliza IMAP/SMTP u OAuth, el [canal de correo electrónico](email.md) integrado puede ser más sencillo que una integración personalizada. ### Integración con CRM Conecte su sistema CRM (gestión de relaciones con los clientes) existente a la plataforma: 1. Cuando un cliente potencial envía un mensaje a través de su CRM, reenvíelo a la plataforma. 2. El Agente de IA responde y realiza un seguimiento de la conversación. 3. La respuesta de la IA se envía de vuelta a su CRM para su entrega. 4. El historial completo de la conversación está disponible tanto en la plataforma como en su CRM. **Por qué es útil:** Su equipo de ventas obtiene respuestas asistidas por IA para los clientes potenciales sin salir de su CRM. ### Sistema de tickets de soporte Utilice la plataforma como un primer respondedor impulsado por IA para el servicio de atención al cliente: 1. Su sistema de tickets reenvía los nuevos tickets de soporte a la plataforma. 2. El Agente de IA envía una respuesta inicial (por ejemplo, confirmando la recepción del ticket y haciendo preguntas aclaratorias). 3. La respuesta se adjunta al ticket en su sistema de soporte. 4. Su equipo de soporte puede revisar lo que dijo la IA y tomar el control cuando sea necesario. **Por qué es útil:** Los clientes reciben un acuse de recibo inmediato y ayuda inicial, incluso fuera del horario laboral. --- ## Solución de problemas ### Mensajes no recibidos por la plataforma - Verifique que su clave API sea correcta y esté activa (consulte **Configuración → Integraciones → Clave API**). - Asegúrese de estar enviando una solicitud POST (no GET). Su desarrollador conocerá la diferencia. - Compruebe que el campo `customData.body` no esté vacío o contenga solo espacios en blanco. - Verifique que el campo `customData.fromId` esté incluido. - Lea el mensaje de respuesta para obtener detalles específicos del error. ### Respuestas que no llegan a su plataforma - Asegúrese de haber ingresado la URL de su plataforma en la tarjeta **Canal personalizado** en la página Canales. Si no se guarda ninguna URL, las respuestas se generan y almacenan pero nunca se envían, y **no** se marcarán como "Fallidas", así que verifique esto primero. - Verifique que la URL sea accesible públicamente (que no esté detrás de un inicio de sesión o firewall) y que devuelva una respuesta de éxito. - Solo las respuestas (mensajes salientes) se envían a su URL; los mensajes entrantes no activan esto. - Compruebe los detalles del error en el mensaje dentro de su bandeja de entrada. ### El contacto no se crea - Asegúrese de que el valor `fromId` sea coherente para el mismo usuario en todos sus mensajes. La plataforma utiliza este valor para identificar contactos; si cambia entre mensajes, la plataforma creará un nuevo contacto cada vez. - Incluya `firstName`, `lastName` y `email` en el primer mensaje de un nuevo contacto para crear un registro de contacto completo. ### Los archivos adjuntos multimedia no funcionan - Para enlaces de archivos (URL), asegúrese de que el archivo sea accesible públicamente (no se requiere inicio de sesión para acceder a él). - Incluya siempre `mediaContentType` cuando incluya `mediaUrl`. - Para archivos incrustados (base64), verifique que el formato sea `data:MIME_TYPE;base64,ENCODED_DATA`. - Asegúrese de que el tipo de archivo que especifica coincida con el contenido real del archivo. --- ## Mejores prácticas - **Utilice valores `fromId` coherentes.** Cada usuario en su plataforma siempre debe tener el mismo `fromId`. Esto garantiza que la plataforma agrupe todos sus mensajes en una sola conversación en lugar de crear contactos duplicados. - **Elija un nombre `channel` claro.** Elija algo descriptivo como `"website-chat"`, `"email"` o `"zendesk"` para que pueda saber fácilmente de dónde provienen los mensajes al ver su bandeja de entrada. - **Incluya detalles de contacto** (`firstName`, `lastName`, `email`) en el primer mensaje de un nuevo contacto. Esto crea un registro de contacto completo y útil de inmediato. - **Incorpore lógica de reintento.** Haga que su plataforma vuelva a intentar enviar mensajes si la plataforma no responde en el primer intento (los problemas de red ocurren). - **Utilice valores `messageSid` únicos** para cada mensaje. Esto evita que el mismo mensaje se procese dos veces si su sistema lo envía más de una vez. - **Utilice `campaignId`** para enrutar mensajes a diferentes Agentes de IA cuando tenga múltiples casos de uso (por ejemplo, consultas de ventas frente a preguntas de soporte). - **Pruebe antes de publicar.** Envíe mensajes de prueba en ambas direcciones y verifique que los contactos, las conversaciones y las respuestas de la IA funcionen correctamente antes de lanzarlo a los usuarios reales.