Conectar Telnyx (voz) — Manual del operador | AI Agent Builder

Conectar Telnyx (voz)

Paso a paso para que un asistente de voz de Telnyx use un agente como su modelo de lenguaje: la URL y la clave, cómo una llamada se vuelve una conversación, las herramientas de control de llamada y qué hacer cuando el agente se queda en silencio.

7 min de lectura · Actualizado 13 de noviembre de 2026

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 TelnyxQué va
URL basehttps://agent.ai.synapticlinks.com.ar/v1
Clave de APILa clave del paso 1
ModeloLa clave del agente, por ejemplo turnos-clinica
  • Usá la URL agent., que va directo al servidor. También funciona https://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:

  1. Toma el identificador de la llamada de los metadatos (call_control_id) y lo usa para encontrar la sesión de esa llamada.
  2. Copia a la sesión los mensajes anteriores que todavía no tenía.
  3. 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".
  4. 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íntomaCausa probableQué hacer
La llamada no conecta con el agenteClave sin el permiso channel:openai_compat, o el modelo no es la clave de un agenteRevisá la clave y probá GET /v1/models
Silencio después de una pregunta largaLa ruta ai.…/api/v1 cortó la respuesta a los 30 segundosUsá la URL agent.…/v1 y aligerá el workflow
Silencio cuando el que llama interrumpeLa frase nueva llegó mientras el agente seguía respondiendo la anteriorPedí respuestas más cortas en el prompt
Silencio con varias llamadas a la vezSe superó el límite de 60 pedidos por minuto del tenantPedí a un super admin que lo suba
Cada frase aparece como una sesión distintaTelnyx no reenvía los metadatos de la llamadaActivá el reenvío de metadatos
El agente no puede cortar ni transferirFalta la integración Telnyx, o el agente no encuentra el identificador de la llamadaInstalá la integración e indicá en el prompt que use call_control_id
El agente responde con listas o enlacesNo recibe instrucciones de voz de la plataformaAgregá 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_compat y 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.