canonical: https://jentic.com/apis/telnyx.com/telnyx-api

# Telnyx API

Deliver SMS, MMS, voice calls, fax, SIP trunking, and AI-powered call control through a unified API with 713 endpoints. Purchase and manage phone numbers across 60+ countries, configure messaging profiles and campaigns for 10DLC compliance, and run AI assistants on live calls. Includes embedded AI features for chat completions, embeddings, transcription, and fine-tuning alongside core telephony services.

## For AI agents

Send SMS/MMS, control voice calls, manage phone numbers, and run AI assistants on calls through a single API with 713 endpoints covering telephony, messaging, and AI inference.

## Scope

Does not handle email delivery, push notifications, or notification orchestration - use for telephony, SMS, fax, SIP, and embedded AI only.

## Capabilities

- Send SMS, MMS, and group messages through long codes, short codes, and number pools with delivery tracking
- Control active voice calls with answer, hangup, transfer, gather DTMF, record, and text-to-speech commands
- Purchase and configure phone numbers across 60+ countries with instant activation
- Run AI assistants on live calls for conversational IVR, transcription, and intelligent call routing
- Send and receive faxes programmatically with status tracking and media retrieval
- Configure SIP trunking with credential and IP-based authentication for enterprise voice
- Generate text embeddings, run chat completions, and fine-tune models through integrated AI endpoints

## Use cases

### AI Agent Communications Automation

AI agents send messages and control calls through Jentic by searching for Telnyx operations, loading schemas, and executing with bearer token injection. Jentic handles authentication from your Jentic One instance so agents operate across SMS, voice, and AI endpoints without managing API keys. A single API surface covers messaging, call control, number management, and AI inference.

Example prompt: Send an SMS from +15551234567 to +15559876543 with text 'Your appointment is confirmed' via POST /messages and verify the message_id is returned

### Programmable Voice with AI Assistants

Build intelligent call flows by combining Telnyx call control commands with embedded AI assistants. Start a call, then attach an AI assistant for real-time transcription, conversational IVR, or AI-powered information gathering. The assistant handles natural language interaction while the call control API manages hold, transfer, and recording - all through a single platform without external AI service integrations.

Example prompt: Initiate a call via POST /calls, then start an AI assistant on the call via POST /calls/{call_control_id}/actions/ai_assistant_start with a greeting prompt

### 10DLC Messaging Compliance

Register brands and campaigns for US 10DLC messaging compliance through the API. Create messaging profiles that associate phone numbers with registered campaigns, ensuring messages are delivered with carrier trust scores. The API handles brand registration, campaign submission, and number assignment - covering the full compliance lifecycle without manual carrier portals.

Example prompt: Create a messaging profile via the API, register a brand, submit a campaign for approval, and assign a phone number to the messaging profile

### Multi-Channel Number Management

Search, purchase, and configure phone numbers for voice, SMS, MMS, and fax across 60+ countries. Filter available numbers by area code, features, and number type. Configure purchased numbers with connection assignments, messaging profiles, and emergency addresses. Supports number porting, block purchases, and sub-organization number allocation.

Example prompt: Search available US phone numbers with SMS capability via GET /available_phone_numbers with filter[features]=sms and purchase the first result

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /messages | Send an SMS or MMS message |
| GET | /messages/{id} | Retrieve message details and delivery status |
| POST | /calls | Initiate an outbound voice call |
| POST | /calls/{call_control_id}/actions/answer | Answer an incoming call |
| POST | /calls/{call_control_id}/actions/ai_assistant_start | Start an AI assistant on an active call |
| GET | /available_phone_numbers | Search available phone numbers for purchase |
| POST | /faxes | Send a fax |
| POST | /ai/chat/completions | Run AI chat completions |

## Key resources

- **Messages** — Send SMS, MMS, group messages and track delivery status
- **Calls** — Initiate and control voice calls with answer, hangup, transfer, record, and AI assistant actions
- **Phone Numbers** — Search, purchase, configure, and manage phone numbers across 60+ countries
- **Faxes** — Send and receive faxes with status tracking and media access
- **AI** — Chat completions, embeddings, transcription, and fine-tuning through integrated AI endpoints
- **Messaging Profiles** — Configure messaging settings, 10DLC campaigns, and number associations

## Why Jentic

- **Setup:** Wiring the Telnyx API by hand means setting up its bearer token, attaching it to every call against api.telnyx.com/v2, and writing the call-control, messaging, and retry glue across hundreds of endpoints yourself. Through Jentic you install once, import the Telnyx API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Telnyx API puts the call control id in the URL path (/calls/{call_control_id}/actions/answer), so a rule can pin your agent to one call: it can answer that call or start its AI assistant and nothing else. You choose the operations it may call, so ones like sending messages or ordering phone numbers are not included unless you add them.
- **Credential handling:** Your Telnyx token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an SMS' or 'answer an inbound call', and Jentic returns the matching Telnyx API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio REST API** — Twilio offers comparable SMS and voice with a larger ecosystem of add-on services and 180+ country coverage
- **Plivo SMS API** — Plivo provides SMS and voice APIs with competitive pricing to 200+ countries
- **Sinch API** — Sinch provides messaging, voice, and verification APIs with strong operator connectivity
- **Twilio SendGrid Mail API** — SendGrid adds transactional email delivery alongside Telnyx SMS and voice

## FAQ

### What authentication does the Telnyx API use?

The Telnyx API uses Bearer token authentication. Include your API key in the Authorization header as 'Bearer YOUR_API_KEY'. Through Jentic, your Telnyx bearer token is stored encrypted in your Jentic One instance and injected automatically into requests, so agents never handle the raw API key.

### Can I run AI assistants on live voice calls with Telnyx?

Yes. After initiating or answering a call, POST to /calls/{call_control_id}/actions/ai_assistant_start with a system prompt and configuration. The AI assistant handles conversational interaction on the call in real-time. Stop it with /actions/ai_assistant_stop when complete.

### What are the rate limits for the Telnyx messaging API?

Telnyx messaging rate limits depend on your number type and messaging profile. Long codes support 1 message per second per number. Toll-free numbers support higher throughput after verification. Short codes support 30+ messages per second. The API returns 429 when limits are exceeded.

### How do I send an SMS through Jentic with the Telnyx API?

Search for 'send an SMS message' in Jentic to find the Telnyx messages endpoint. Load the operation schema, then execute with from (your Telnyx number), to (recipient), and text (message body). Install with pip install jentic and use the search-load-execute flow. Jentic injects the bearer token automatically. Get started with Jentic One, the self-hosted execution layer.

### Does Telnyx support 10DLC messaging compliance?

Yes. Telnyx provides API endpoints for brand registration, campaign submission, and number-to-campaign assignment. Create a messaging profile, register your brand, submit a campaign for carrier approval, and assign numbers to the profile. The API covers the full 10DLC compliance lifecycle.

### Can I send faxes through the Telnyx API?

Yes. POST to /faxes with the to number, from number, and media URL of the document to fax. The API returns a fax ID for status tracking. Retrieve fax status and received faxes via GET /faxes/{id}. Supports PDF and TIFF formats.

### Can I limit what my agent is allowed to do with the Telnyx API?

Yes. Because you run Jentic One yourself, your own rules decide which Telnyx operations and credentials your agent may use, so you can allow only what a task needs. Since the Telnyx API puts the call control id in the URL path, such as /calls/{call_control_id}/actions/answer, a rule can pin the agent to a single call so it can answer that call or start its AI assistant and nothing else. Operations like sending messages via POST /messages or ordering phone numbers stay out of reach unless you explicitly add them.