Connect Telnyx (voice) — Operator manual | AI Agent Builder

Connect Telnyx (voice)

Step by step so a Telnyx voice assistant uses an agent as its language model: the URL and key, how a call becomes a conversation, the call-control tools and what to do when the agent goes silent.

6 min read · Updated November 13, 2026

This guide connects a Clínica del Sol Telnyx number to the scheduling agent. Telnyx answers the call, turns speech into text and text into speech; the platform only thinks the answer, as if it were an OpenAI-compatible language model. Why this path is worth it over Twilio or Asterisk is in the Voice chapter, and the endpoint's full contract is in the guide Calling an agent from your system.

The same applies to other voice platforms that accept their own OpenAI-compatible model, such as Vapi, Retell, LiveKit or Bland. The Telnyx-side steps follow its portal as it was when this guide was written; what the guide says about the platform side is verified against the code.

Before you start

  • Telnyx chooses the voice. Speech recognition, the assistant's voice and the language are configured in Telnyx, not in the platform.
  • The agent answers with text, which Telnyx speaks aloud. So its prompt must ask for short answers, with no lists or links: on this channel the platform's voice instructions are not added.
  • One run per turn. Each phrase from the caller runs the whole workflow: the lighter the agent —fast model, few steps—, the less the caller waits.

1. The API key

In the clinic's tenant, create an API key with the channel:openai_compat permission (chapter 8). Telnyx uses it on every turn.

2. Configure the assistant in Telnyx

In Telnyx's AI assistant, choose to use your own OpenAI-compatible model and fill in:

Field in TelnyxWhat goes in
Base URLhttps://agent.ai.synapticlinks.com.ar/v1
API keyThe key from step 1
ModelThe agent key, for example turnos-clinica
  • Use the agent. URL, which goes straight to the server. https://ai.synapticlinks.com.ar/api/v1 also works, but that route cuts off an answer that goes more than 30 seconds without sending anything, and in voice that is a silent call.
  • The model is not a free-form name: it must be the key of an active agent in the tenant. If it doesn't exist, the call fails with "model not found".
  • Turn on forwarding of call metadata. It is what lets the platform know that every phrase belongs to the same call (see below).

To check the key without calling, GET https://agent.ai.synapticlinks.com.ar/v1/models with the key as Authorization: Bearer … lists the agents that can be used as a model.

3. How a call becomes a conversation

On each turn, Telnyx sends the whole conversation so far. The platform:

  1. Takes the call identifier from the metadata (call_control_id) and uses it to find that call's session.
  2. Copies into the session the earlier messages it didn't have yet.
  3. Runs the agent with the caller's last phrase, and passes it Telnyx's metadata as context, titled "Caller metadata".
  4. Returns the answer as it is generated.

If Telnyx does not send the call identifier, each phrase is recorded as a separate session. The agent still sees what was said before, because Telnyx sends the whole conversation, but in Monitoring → Sessions a call shows up split into many sessions, and what the workflow remembers between turns is lost.

The answer's language follows the caller: if they speak Spanish, the agent answers in Spanish. Even so, the session is recorded in English unless the metadata includes locale: "es"; that affects some fixed platform texts and personal-data detection (chapter 9). If Telnyx lets you add variables to the metadata, add locale with the tenant's language.

4. Controlling the call from the agent

For the agent to hang up, transfer or play audio, install the Telnyx integration from the Integrations catalog with a Telnyx API key (from your Telnyx account, different from the one in step 1). The integration has a connection test that validates that key against Telnyx.

The integration adds call-control tools. These are on by default:

  • hang up the call;
  • transfer it;
  • play and stop audio;
  • send tones.

Others can be turned on: answer, reject, dial, queue, record, gather digits, conferences.

All of them need the call identifier, which the agent finds in the "Caller metadata" context. The platform does not wire it automatically: the prompt of the step that uses the tools must tell it to use that value. If Telnyx doesn't forward metadata, the agent cannot control the call.

When the agent goes silent

If something fails while the answer is being generated, Telnyx receives an empty answer and the caller hears silence. That error does not reach Telnyx: it stays in the server logs and in the run.

SymptomLikely causeWhat to do
The call doesn't connect to the agentKey without the channel:openai_compat permission, or the model isn't an agent keyCheck the key and try GET /v1/models
Silence after a long questionThe ai.…/api/v1 route cut the answer at 30 secondsUse the agent.…/v1 URL and lighten the workflow
Silence when the caller interruptsThe new phrase arrived while the agent was still answering the previous oneAsk for shorter answers in the prompt
Silence with several calls at onceThe tenant's limit of 60 requests per minute was exceededAsk a super admin to raise it
Each phrase shows up as a separate sessionTelnyx doesn't forward call metadataTurn on metadata forwarding
The agent can't hang up or transferThe Telnyx integration is missing, or the agent can't find the call identifierInstall the integration and tell the prompt to use call_control_id
The agent answers with lists or linksIt gets no platform voice instructionsAdd voice rules to the agent's prompt

A call makes roughly one request per phrase, about 10 to 20 per minute. With 3 to 5 simultaneous calls in the same tenant, plus other API use, the 60-per-minute limit is reached.

Where it stops

  • The platform's voice instructions are not added: the spoken tone goes in the agent's prompt.
  • Only text reaches Telnyx: approvals, cards and other workflow output are not sent. An approval step leaves the call waiting.
  • An error during the answer is heard as silence.
  • The 60-requests-per-minute limit is shared with the rest of the tenant's API.
  • The call identifier is not passed to the tools automatically: the prompt has to say so.
  • On very long calls, with more than 50 stored messages, the history copy can duplicate messages in the session.
  • The setup guide shown by the integration has a URL with an unreplaced placeholder ({CHAT_SERVER_BASE}): use the one in this guide.

To check

  • The API key has the channel:openai_compat permission and is in the agent's tenant.
  • In Telnyx, the base URL is the agent. one and the model is the agent key.
  • Metadata forwarding is on and a call shows up as a single session.
  • The agent's prompt asks for short answers, with no lists or links.
  • If the agent controls the call, the Telnyx integration is installed and the prompt uses call_control_id.
  • The per-minute limit covers the expected simultaneous calls.