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

# Twilio REST API

Send and receive SMS and MMS messages, initiate and control voice calls, manage phone numbers, and handle conference calls across 180+ countries. Provides programmable communication building blocks including call recordings, transcriptions, SIP trunking, and queue management. Supports both domestic and international messaging with media attachments and delivery status callbacks.

## For AI agents

Send SMS/MMS messages, make voice calls, purchase phone numbers, and manage call recordings programmatically across 180+ countries.

## Scope

Does not handle email delivery, push notifications, or video - use for SMS, voice calls, and phone number management only.

## Capabilities

- Send SMS and MMS messages to mobile numbers worldwide with delivery status tracking
- Initiate outbound voice calls with TwiML-based call flow control and recording
- Purchase and configure phone numbers across 180+ countries with local, mobile, and toll-free options
- Record and transcribe voice calls with configurable recording channels and formats
- Bridge multiple call participants into conference rooms with mute and hold controls
- Manage SIP domains and credential lists for enterprise voice infrastructure
- Queue incoming calls with position announcements and custom hold music

## Use cases

### AI Agent SMS Notifications

AI agents send SMS notifications through Jentic by searching for the send message operation, loading the schema, and executing with To, From, and Body fields. Jentic handles Basic auth credential injection from your Jentic One instance so agents never handle Account SID or Auth Token directly. A single POST to /2010-04-01/Accounts/{AccountSid}/Messages.json delivers the message with optional media URLs and status callback.

Example prompt: Send an SMS to +15551234567 from +15559876543 with body 'Your order has shipped' and verify the message SID is returned in the response

### Automated Voice Calls

Trigger outbound voice calls for appointment reminders, security alerts, or customer callbacks. The API initiates the call and directs it to a TwiML document that defines the call flow - text-to-speech greetings, menu options, recordings, or forwarding. Status callbacks report call progress from initiated through completed, enabling retry logic for unanswered calls.

Example prompt: Initiate a voice call to +15551234567 using a TwiML URL that plays a text-to-speech appointment reminder and check the call status via GET /2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json

### Phone Number Provisioning

Search and purchase local, mobile, or toll-free phone numbers in 180+ countries for SMS and voice capabilities. Filter available numbers by area code, country, and capabilities (SMS, MMS, voice, fax). Purchased numbers are immediately available for sending and receiving messages or calls, with configurable webhook URLs for inbound traffic routing.

Example prompt: Search for available toll-free numbers in the US via GET /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/US/TollFree.json and purchase the first result

### Call Recording and Transcription

Record voice calls for compliance, quality assurance, or training purposes. Recordings can capture both legs of a call or a single channel. Completed recordings are accessible via the API for playback or download. Transcription converts recorded audio to text, enabling search and analysis of call content without manual review.

Example prompt: Start a recording on an active call via POST /2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json and retrieve the completed recording URI

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /2010-04-01/Accounts/{AccountSid}/Messages.json | Send an SMS or MMS message |
| GET | /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json | Retrieve a message by SID |
| POST | /2010-04-01/Accounts/{AccountSid}/Calls.json | Initiate an outbound voice call |
| GET | /2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json | Get call details and status |
| POST | /2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json | Start recording a call |
| GET | /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json | Search available local phone numbers |
| GET | /2010-04-01/Accounts/{AccountSid}/Balance.json | Get current account balance |
| POST | /2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants/{CallSid}.json | Update a conference participant |

## Key resources

- **Messages** — Send, retrieve, and list SMS and MMS messages with delivery tracking
- **Calls** — Initiate, monitor, and control voice calls with recording and transcription
- **Available Phone Numbers** — Search purchasable phone numbers by country, type, and capability
- **Recordings** — Access and manage call recordings and transcriptions
- **Conferences** — Create and manage multi-party conference calls with participant controls
- **Accounts** — Manage account settings, subaccounts, and usage balance

## Why Jentic

- **Setup:** Wiring Twilio REST API by hand means learning its basic auth with Account SID and Auth Token, threading the account SID through every path, and handling errors and retries across messages, calls, and conferences yourself. Through Jentic you install once, import Twilio REST API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Twilio REST API puts the message or call SID in the URL path (/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json), so a rule can pin your agent to one call or message: it can read that resource and its recordings and nothing else. You choose the operations it may call, so placing new calls or sending messages are not included unless you add them.
- **Credential handling:** Your Twilio Account SID and Auth Token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an SMS message' or 'place a phone call', and Jentic returns the matching Twilio REST API operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Telnyx API** — Telnyx offers comparable SMS, voice, and number management with per-minute billing and carrier-grade SIP
- **Plivo SMS API** — Plivo provides SMS and voice APIs with competitive international pricing to 200+ countries
- **Vonage SMS API** — Vonage (Nexmo) provides SMS delivery with delivery receipts and inbound messaging support
- **Twilio SendGrid Mail API** — SendGrid adds transactional email delivery alongside Twilio SMS and voice

## FAQ

### What authentication does the Twilio REST API use?

The Twilio REST API uses HTTP Basic authentication with your Account SID as the username and Auth Token as the password. Through Jentic, these credentials are stored encrypted in your Jentic One instance and injected automatically into the Basic auth header, so agents never handle the raw Account SID or Auth Token.

### Can I send MMS messages with images through the Twilio API?

Yes. Include a MediaUrl parameter in your POST to /2010-04-01/Accounts/{AccountSid}/Messages.json pointing to a publicly accessible image URL. The API supports up to 10 media URLs per message for images, GIFs, and other supported MIME types.

### What are the rate limits for sending SMS with Twilio?

Long code numbers support 1 SMS per second in the US. Toll-free numbers support up to 3 messages per second. Short codes can send 30-100 messages per second depending on the carrier. The API returns HTTP 429 when limits are exceeded, and messages are queued for retry.

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

Search for 'send an SMS message' in Jentic to find the Twilio Messages endpoint. Load the operation schema, then execute with To (recipient number), From (your Twilio number), and Body (message text). Install with pip install jentic and use the search-load-execute pattern. Jentic handles Basic auth injection automatically. Get started with Jentic One, the self-hosted execution layer.

### Can I check whether an SMS was delivered?

Yes. Retrieve the message via GET /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json and check the Status field. Values include queued, sending, sent, delivered, and failed. You can also configure a StatusCallback URL in the send request to receive real-time delivery webhooks.

### How many countries does Twilio support for phone numbers?

Twilio offers phone numbers in 180+ countries. Use GET /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers.json to list supported countries, then filter by country code and number type (local, mobile, toll-free) to find available numbers for purchase.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which Twilio operations and credentials the agent may use. Because Twilio puts the call or message SID in the URL path (for example /2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json), you can pin the agent to a single call or message and let it read that resource and its recordings while blocking everything else. Since you choose the allowed operations, placing new calls or sending messages via /2010-04-01/Accounts/{AccountSid}/Messages.json stay off limits unless you explicitly add them.