Esta guía conecta un número de Telnyx de Clínica del Sol con el agente de turnos. Telnyx atiende la llamada, convierte la voz en texto y el texto en voz; la plataforma solo piensa la respuesta, como si fuera un modelo de lenguaje compatible con OpenAI. Por qué conviene este camino frente a Twilio o Asterisk está en el capítulo Voz, y el contrato completo del endpoint, en la guía Llamar a un agente desde tu sistema.
Lo mismo sirve para otras plataformas de voz que aceptan un modelo propio compatible con OpenAI, como Vapi, Retell, LiveKit o Bland. Los pasos del lado de Telnyx siguen su portal al momento de escribir esta guía; lo que dice del lado de la plataforma está verificado contra el código.
Antes de empezar
- La voz la elige Telnyx. Reconocimiento de voz, voz del asistente e idioma se configuran en Telnyx, no en la plataforma.
- El agente responde con texto, que Telnyx dice en voz alta. Por eso su prompt tiene que pedir respuestas cortas, sin listas ni enlaces: en este canal no se agregan las instrucciones de voz de la plataforma.
- Una ejecución por turno. Cada frase del que llama corre el workflow completo: cuanto más liviano el agente —modelo rápido, pocos pasos—, menos espera el que llama.
1. La clave de API
En el tenant de la clínica, creá una clave de API con el permiso channel:openai_compat (capítulo 8). Es la que Telnyx va a usar en cada turno.
2. Configurar el asistente en Telnyx
En el asistente de IA de Telnyx, elegí usar un modelo propio compatible con OpenAI y completá:
| Campo en Telnyx | Qué va |
|---|---|
| URL base | https://agent.ai.synapticlinks.com.ar/v1 |
| Clave de API | La clave del paso 1 |
| Modelo | La clave del agente, por ejemplo turnos-clinica |
- Usá la URL
agent., que va directo al servidor. También funcionahttps://ai.synapticlinks.com.ar/api/v1, pero esa ruta corta una respuesta que se queda más de 30 segundos sin enviar nada, y en voz eso es una llamada en silencio. - El modelo no es un nombre libre: tiene que ser la clave de un agente activo del tenant. Si no existe, la llamada falla con "model not found".
- Activá el reenvío de metadatos de la llamada. Es lo que le permite a la plataforma saber que todas las frases son de la misma llamada (ver más abajo).
Para comprobar la clave sin llamar, GET https://agent.ai.synapticlinks.com.ar/v1/models con la clave como Authorization: Bearer … lista los agentes que se pueden usar como modelo.
3. Cómo una llamada se vuelve una conversación
En cada turno, Telnyx manda la conversación completa hasta ese momento. La plataforma:
- Toma el identificador de la llamada de los metadatos (
call_control_id) y lo usa para encontrar la sesión de esa llamada. - Copia a la sesión los mensajes anteriores que todavía no tenía.
- Corre el agente con la última frase del que llama, y le pasa los metadatos de Telnyx como contexto, con el título "Caller metadata".
- Devuelve la respuesta a medida que se genera.
Si Telnyx no manda el identificador de la llamada, cada frase queda registrada como una sesión distinta. El agente igual ve lo que se dijo antes, porque Telnyx manda toda la conversación, pero en Monitoreo → Sesiones una llamada aparece partida en muchas sesiones, y lo que el workflow recuerda entre turnos se pierde.
El idioma de la respuesta sigue al que llama: si habla en español, el agente responde en español. Aun así, la sesión se registra en inglés salvo que los metadatos incluyan locale: "es"; eso afecta algunos textos fijos de la plataforma y la detección de datos personales (capítulo 9). Si Telnyx permite agregar variables a los metadatos, agregá locale con el idioma del tenant.
4. Controlar la llamada desde el agente
Para que el agente pueda cortar, transferir o reproducir audio, instalá la integración Telnyx del catálogo de Integraciones con una clave de API de Telnyx (de tu cuenta de Telnyx, distinta de la del paso 1). La integración tiene una prueba de conexión que valida esa clave contra Telnyx.
La integración agrega herramientas de control de llamada. Vienen activadas por defecto:
- cortar la llamada;
- transferirla;
- reproducir y detener audio;
- enviar tonos.
Se pueden activar otras: atender, rechazar, marcar, poner en cola, grabar, pedir dígitos, conferencias.
Todas necesitan el identificador de la llamada, que el agente encuentra en el contexto "Caller metadata". La plataforma no lo conecta solo: el prompt del paso que usa las herramientas tiene que indicarle que use ese valor. Si Telnyx no reenvía los metadatos, el agente no puede controlar la llamada.
Cuando el agente se queda en silencio
Si algo falla mientras se genera la respuesta, Telnyx recibe una respuesta vacía y el que llama escucha silencio. Ese error no le llega a Telnyx: queda en los registros del servidor y en la ejecución.
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| La llamada no conecta con el agente | Clave sin el permiso channel:openai_compat, o el modelo no es la clave de un agente | Revisá la clave y probá GET /v1/models |
| Silencio después de una pregunta larga | La ruta ai.…/api/v1 cortó la respuesta a los 30 segundos | Usá la URL agent.…/v1 y aligerá el workflow |
| Silencio cuando el que llama interrumpe | La frase nueva llegó mientras el agente seguía respondiendo la anterior | Pedí respuestas más cortas en el prompt |
| Silencio con varias llamadas a la vez | Se superó el límite de 60 pedidos por minuto del tenant | Pedí a un super admin que lo suba |
| Cada frase aparece como una sesión distinta | Telnyx no reenvía los metadatos de la llamada | Activá el reenvío de metadatos |
| El agente no puede cortar ni transferir | Falta la integración Telnyx, o el agente no encuentra el identificador de la llamada | Instalá la integración e indicá en el prompt que use call_control_id |
| El agente responde con listas o enlaces | No recibe instrucciones de voz de la plataforma | Agregá las reglas de voz al prompt del agente |
Una llamada hace más o menos un pedido por frase, unos 10 a 20 por minuto. Con 3 a 5 llamadas simultáneas en el mismo tenant, más otros usos de la API, se llega al límite de 60 por minuto.
Dónde termina
- No se agregan las instrucciones de voz de la plataforma: el tono hablado va en el prompt del agente.
- Solo llega texto a Telnyx: aprobaciones, tarjetas y otros resultados del workflow no se transmiten. Un paso de aprobación deja la llamada esperando.
- Un error durante la respuesta se escucha como silencio.
- El límite de 60 pedidos por minuto se comparte con el resto de la API del tenant.
- El identificador de la llamada no se pasa solo a las herramientas: el prompt tiene que indicarlo.
- En llamadas muy largas, de más de 50 mensajes guardados, la copia del historial puede duplicar mensajes en la sesión.
- La guía de instalación que muestra la integración tiene una URL con un marcador sin reemplazar (
{CHAT_SERVER_BASE}): usá la de esta guía.
Para revisar
- La clave de API tiene el permiso
channel:openai_compaty está en el tenant del agente. - En Telnyx, la URL base es la de
agent.y el modelo es la clave del agente. - El reenvío de metadatos está activado y una llamada aparece como una sola sesión.
- El prompt del agente pide respuestas cortas, sin listas ni enlaces.
- Si el agente controla la llamada, la integración Telnyx está instalada y el prompt usa
call_control_id. - El límite por minuto alcanza para las llamadas simultáneas esperadas.