Manual de integración del sistema telefónico

Al integrar el Audio Agent con un sistema telefónico, tu Agent de voz puede atender llamadas directamente. Los usuarios solo tienen que marcar el número para mantener una conversación de voz con el Agent.
Ámbito compatible en esta versión:

Proveedor Twilio · Llamada entrante (el usuario llama) · Llamada entrante por número, ideal para el escenario en que «el cliente marca directamente un número de teléfono y puede hablar con el Agent».
Transferencia de llamada entrante por SIP de terceros, ideal para el escenario en que ya se dispone de un centro de llamadas o un sistema de llamadas salientes que, tras conectar con el cliente, transfiere la llamada al Agent.

1. Antes de empezar (requisitos previos)

Un Agent con la capacidad de voz ya activada
El Agent debe tener configurados el modelo de voz, el timbre y el mensaje de bienvenida (todo ello en la configuración de voz del Agent). Cuando se establece la llamada, se reproduce precisamente el mensaje de bienvenida configurado aquí.
Una cuenta de Twilio
- Si utilizas la «llamada entrante por número público»: necesitas tu propia cuenta de Twilio y haber adquirido un número de teléfono.
- Si utilizas la «transferencia SIP de terceros»: se emplea el punto de conexión SIP compartido que proporciona la plataforma GPTBots, sin necesidad de disponer de un número propio.
Ruta de acceso: Espacio de Desarrollo → tu Agent → Integración → Sistema telefónico.

2. Vincular un número de teléfono público (lo más habitual)

Ideal para el escenario en que «el cliente marca directamente un número de teléfono y puede hablar con el Agent».

Pasos

Proveedor de servicios: selecciona Twilio · Elastic SIP Trunk.

Rellena la información de la cuenta de Twilio:

Campo	Contenido a rellenar	Descripción
Account SID	`ACxxxxxxxx…`	Visible en la página de inicio de la consola de Twilio
Auth Token	Tu Auth Token de Twilio	Se utiliza para verificar la firma de la solicitud de la llamada entrante (X-Twilio-Signature) y evitar llamadas entrantes falsificadas
Dominio de Elastic SIP Trunk	`your-trunk.pstn.twilio.com`	El dominio de tu Trunk
Región de acceso	Elige la más cercana (US1 / IE1 / DE1 / AU1 / JP1 / SG1)	Influye en la latencia de la llamada
Número de teléfono vinculado	`+1 415 555 0188`	El número que has adquirido en Twilio, incluido el código de país
Dirección de la llamada	Solo entrante	Esta versión solo admite llamadas entrantes

Haz clic en Guardar. Una vez guardado correctamente, en la zona «Webhook» se genera automáticamente una URL de medios / callback.
Vuelve a introducir esta URL en Twilio:
Copia la «URL de medios / callback» → abre en la consola de Twilio la configuración de ese número → localiza A CALL COMES IN (cuando entra una llamada) → selecciona el modo Webhook, pega esa URL y usa el método HTTP POST → guarda.
Listo. Marca ese número desde tu móvil: deberías oír el mensaje de bienvenida del Agent y comenzar la conversación.

3. Llamada entrante transferida desde un sistema SIP de terceros (centro de llamadas / PBX)

Ideal para el escenario en que «ya se dispone de un centro de llamadas o un sistema de llamadas salientes que, tras conectar con el cliente, transfiere la llamada al Agent». En este caso, GPTBots actúa como un punto de conexión SIP, con interconexión SIP pura y sin necesidad de número de teléfono.

Esta zona solo se muestra cuando el proveedor es Twilio y la plataforma tiene activado un SIP Domain compartido.

Información que verás

Dirección SIP del Agent (SIP URI) · Punto de entrada de voz único
Tu sistema de terceros, tras conectar con el cliente, transfiere la llamada a esta dirección mediante transferencia SIP REFER, es decir, accede al mismo Agent a través de la «llamada entrante».
Nombre de usuario SIP / Contraseña SIP (se generan automáticamente al guardar la configuración)
Tu PBX / softphone utiliza este par de nombre de usuario y contraseña para autenticarse en el SIP Domain.

⚠️ La contraseña solo se muestra una vez en el momento de su generación / regeneración; la plataforma no la almacena. Cópiala de inmediato y guárdala en un lugar seguro; si la olvidas, la única opción es hacer clic en «Regenerar» para obtener un par nuevo.
Capacidades compatibles: SIP REFER / transferencia, paso de parámetros mediante cabeceras personalizadas (X-headers), TLS / SRTP.

Guía de uso

En tu sistema SIP, utiliza el nombre de usuario + contraseña SIP anteriores para iniciar / transferir la llamada hacia la dirección SIP del Agent. Si además has vinculado un número público, ambos accesos conectan con el mismo Agent, sin necesidad de una configuración adicional.

4. Avanzado: transmitir la identidad del usuario final para la personalización

De forma predeterminada, el Agent identifica a quien llama por el número de la llamada entrante. Si tu sistema ya dispone de su propio sistema de usuarios, puedes incluir un identificador de usuario en la llamada SIP mediante cabeceras personalizadas (X-headers):

Nombre de la cabecera: X-User-Id
Función: el Agent asociará en consecuencia los atributos y las conversaciones anteriores de ese usuario, logrando una respuesta personalizada (por ejemplo, respondiendo según el nivel de membresía o los pedidos anteriores).

Si no se transmite X-User-Id, el Agent utiliza el número de la persona que llama como identificador de visita; la conversación sigue funcionando con normalidad, pero sin la personalización basada en el perfil del usuario.

5. Realizar una llamada de prueba y consultar los registros

Marca el número vinculado (o transfiere desde el sistema de terceros) y confirma que:
- se oye el mensaje de bienvenida;
- se puede mantener con normalidad una conversación de varios turnos;
- al hablar se puede interrumpir el contenido que el Agent está reproduciendo.
En la página de registros / historial de conversaciones puedes consultar esa llamada:
- el origen de la sesión se marca como Twilio y se muestra el número de la llamada entrante;
- el registro completo de preguntas y respuestas de varios turnos;
- la secuencia de ejecución (logtree): nodo de inicio → cada turno de conversación / llamada a herramientas → voz de finalización.

6. Preguntas frecuentes (FAQ)

P1. ¿Marco el número y no hay respuesta / se cuelga directamente?

Comprueba si la «URL de medios / callback» se ha vuelto a introducir correctamente en la opción A CALL COMES IN del número de Twilio, con el método HTTP POST.
Comprueba si el Auth Token está bien introducido: un valor incorrecto provoca que la verificación de la firma de la llamada entrante falle y la llamada sea rechazada.
Asegúrate de que la capacidad de voz del Agent esté configurada por completo (modelo / timbre / mensaje de bienvenida).

P2. ¿Aparece un aviso de credenciales insuficientes / no se puede conectar?

Asegúrate de que la cuenta disponga de puntos suficientes: si se agotan los puntos, se rechazará la llamada entrante.
Asegúrate de no superar el límite de llamadas simultáneas: las nuevas llamadas entrantes que excedan el límite serán rechazadas.

P3. ¿Qué hago si olvido la contraseña SIP?

Haz clic en «Regenerar» para obtener una nueva contraseña (la anterior queda invalidada de inmediato) y actualízala también en tu sistema SIP. La contraseña solo se muestra una vez, así que guárdala a tiempo.

P4. ¿Cuál es la duración máxima de una sola llamada?

Una sola llamada dura como máximo 60 minutos; al superarse, finaliza automáticamente.

P5. ¿Puedo hacer que el Agent realice llamadas salientes por iniciativa propia?

Esta versión solo admite llamadas entrantes (el usuario llama); por ahora no se admiten las llamadas salientes.

7. Consideraciones

Esta versión solo admite el proveedor Twilio y la dirección entrante.
La facturación de las llamadas es la misma que la de un Agent de voz normal: se descuentan puntos según el uso.
Tras modificar la configuración de la integración (número, credenciales, etc.), es necesario volver a guardar para que surta efecto.