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, SMS, Instagram, Messenger). 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.

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 de la IA o escrita por usted), envía el mensaje a una URL en su plataforma, donde su sistema puede entregarlo al usuario final. Las respuestas también pueden incluir un archivo: un elemento que el Agente de IA envía desde su biblioteca multimedia, un archivo adjunto o nota de voz desde la bandeja de entrada, o un archivo enviado a través de la API que llega como un enlace de descarga junto al texto.

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.

Una clave con ámbito también funciona, siempre y cuando no sea de solo lectura y sus áreas incluyan Messages. Los mensajes llegan a la cuenta a la que pertenece la clave, así que utilice la clave de la cuenta (o subcuenta) cuya bandeja de entrada deba recibirlos.

Formato del mensaje #

Envíe los datos del mensaje en el siguiente formato (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 (tu sistema lo crea). Se utiliza para evitar que el mismo mensaje se procese dos veces.
• fromId - Quién envió el mensaje (puede ser un ID de usuario, correo electrónico o número de teléfono de tu sistema).
• toId - Tu identificador de negocio (puede ser cualquier etiqueta que elijas).
• body - El texto real del mensaje.
• channel - Una etiqueta que eliges para identificar de dónde vino el mensaje (p. ej., “website-chat”, “email”). Se convierte en el nombre del canal que se muestra para ese contacto en la bandeja de entrada y en las notificaciones.

Referencia completa de campos #

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.

{
  "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:

{
  "success": true,
  "messageId": "1234567890"
}

Si algo sale mal, recibirá un mensaje de error explicando el problema:

{
  "error": "Message body cannot be empty"
}

Códigos de estado #

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) #

Esta sección cubre los archivos que entran (desde su plataforma a la aplicación). Para los archivos que salen **con una respuesta, consulte Respuestas con 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:

{
  "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:

{
  "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"
}

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:

{
  "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",
  "mediaUrl": null,
  "mediaContentType": null,
  "mediaFileName": null,
  "isVoiceNote": false
}

Qué significa cada campo #

Su plataforma recibe estos datos y los utiliza para entregar la respuesta al usuario final a través de su propio sistema.

Respuestas con archivos #

Una respuesta lleva un archivo cuando:

• el Agente de IA envía un elemento desde su biblioteca multimedia (un folleto, una lista de precios, una foto),
• alguien adjunta un archivo o graba una nota de voz en la bandeja de entrada,
• se envía un mensaje a través de la API con mediaUrl y mediaContentType.

El archivo llega en la misma llamada de webhook que el texto, en los cuatro campos media… anteriores. Una respuesta de solo texto tiene todos ellos configurados en null (y isVoiceNote en false), por lo que un receptor que solo lee body sigue funcionando sin cambios.

{
  "contactId": "abc123",
  "messageId": "msg-789",
  "userId": "your-user-id",
  "body": "Here is our pricing breakdown.",
  "toId": "user-456",
  "channel": "my-live-chat",
  "mediaUrl": "https://storage.googleapis.com/.../Pricing.pdf?X-Goog-Signature=...",
  "mediaContentType": "application/pdf",
  "mediaFileName": "Pricing.pdf",
  "isVoiceNote": false
}

Obtenga mediaUrl con un GET simple (sin inicio de sesión, sin encabezados adicionales) y pase el archivo al usuario final a través de su propio canal. Entregue body como pie de foto o como un mensaje de texto separado, según lo que admita su canal.

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 #

{
  "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 #

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 #

{
  "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 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 (no detrás de un inicio de sesión o firewall) y devuelva una respuesta de éxito.
• Solo las respuestas (mensajes salientes) se envían a su URL; los mensajes entrantes no activan esto.
• Verifique los detalles del error en el mensaje en su bandeja de entrada.
• Una respuesta con un archivo llega en la misma llamada, con el enlace de descarga en mediaUrl. Si su receptor solo reenvía body, el archivo se descarta de su lado; lea también los campos media… (consulte Respuestas con archivos).
• El enlace mediaUrl caduca después de una hora. Descárguelo cuando llegue el webhook, no más tarde desde una cola.

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.