twilio

# Twilio Access the Twilio API with managed OAuth authentication. Send SMS messages, make voice calls, manage phone numbers, and work with Twilio resources. ## Quick Start ```bash # List all accounts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/twilio/2010-04-01/Accounts.json') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/twilio/2010-04-01/Accounts/{AccountSid}/{resource}.json ``` The gateway proxies requests to `api.twilio.com` and automatically injects your OAuth token. **Important:** Most Twilio endpoints require your Account SID in the path. You can get your Account SID from the `/Accounts.json` endpoint. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Twilio OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=twilio&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'twilio'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "ebe566b1-3eaf-4926-bc92-0d8d47445f12", "status": "ACTIVE", "creation_time": "2026-02-09T23:18:44.243582Z", "last_updated_time": "2026-02-09T23:19:55.176687Z", "url": "https://connect.maton.ai/?session_token=...", "app": "twilio", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Twilio connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/twilio/2010-04-01/Accounts.json') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'ebe566b1-3eaf-4926-bc92-0d8d47445f12') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Accounts #### List Accounts ```bash GET /twilio/2010-04-01/Accounts.json ``` **Response:** ```json { "accounts": [ { "sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "friendly_name": "My first Twilio account", "status": "active", "date_created": "Mon, 09 Feb 2026 20:19:55 +0000", "date_updated": "Mon, 09 Feb 2026 20:20:05 +0000" } ] } ``` #### Get Account ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}.json ``` ### Messages (SMS/MMS) #### List Messages ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Messages.json ``` **Query Parameters:** - `PageSize` - Number of results per page (default: 50) - `To` - Filter by recipient phone number - `From` - Filter by sender phone number - `DateSent` - Filter by date sent **Response:** ```json { "messages": [ { "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "body": "Hello!", "from": "+15551234567", "to": "+15559876543", "status": "delivered", "date_sent": "Mon, 09 Feb 2026 21:00:00 +0000" } ], "page": 0, "page_size": 50 } ``` #### Get Message ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json ``` #### Send Message ```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Messages.json Content-Type: application/x-www-form-urlencoded To=+15559876543&From=+15551234567&Body=Hello%20from%20Twilio! ``` **Required Parameters:** - `To` - Recipient phone number (E.164 format) - `From` - Twilio phone number or messaging service SID - `Body` - Message text (max 1600 characters) **Optional Parameters:** - `MessagingServiceSid` - Use instead of From for message routing - `MediaUrl` - URL of media to send (MMS) - `StatusCallback` - Webhook URL for status updates **Response:** ```json { "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "body": "Hello from Twilio!", "from": "+15551234567", "to": "+15559876543", "status": "queued", "date_created": "Mon, 09 Feb 2026 21:00:00 +0000" } ``` #### Update Message (Redact) ```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json Content-Type: application/x-www-form-urlencoded Body= ``` Setting Body to empty string redacts the message content. #### Delete Message ```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json ``` Returns 204 No Content on success. ### Calls (Voice) #### List Calls ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Calls.json ``` **Query Parameters:** - `PageSize` - Results per page - `Status` - Filter by status (queued, ringing, in-progress, completed, etc.) - `To` - Filter by recipient - `From` - Filter by caller **Response:** ```json { "calls": [ { "sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "from": "+15551234567", "to": "+15559876543", "status": "completed", "duration": "60", "direction": "outbound-api" } ], "page": 0, "page_size": 50 } ``` #### Get Call ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json ``` #### Make Call ```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Calls.json Content-Type: application/x-www-form-urlencoded To=+15559876543&From=+15551234567&Url=https://example.com/twiml ``` **Required Parameters:** - `To` - Recipient phone number - `From` - Twilio phone number - `Url` - TwiML application URL **Optional Parameters:** - `StatusCallback` - Webhook URL for call status updates - `StatusCallbackEvent` - Events to receive (initiated, ringing, answered, completed) - `Timeout` - Seconds to wait for answer (default: 60) - `Record` - Set to true to record the call #### Update Call ```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json Content-Type: application/x-www-form-urlencoded Status=completed ``` Use `Status=completed` to end an in-progress call. #### Delete Call ```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json ``` ### Phone Numbers #### List Incoming Phone Numbers ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json ``` **Response:** ```json { "incoming_phone_numbers": [ { "sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "phone_number": "+15551234567", "friendly_name": "My Number", "capabilities": { "voice": true, "sms": true, "mms": true } } ] } ``` #### Get Phone Number ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json ``` #### Update Phone Number ```bash POST /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json Content-Type: application/x-www-form-urlencoded FriendlyName=Updated%20Name&VoiceUrl=https://example.com/voice ``` #### Delete Phone Number ```bash DELETE /twilio/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.json ``` ### Applications #### List Applications ```bash GET /twilio/2010-04-01/Accounts/{AccountSid}/Applications.json ``` **Response:** ```json { "applications": [ { "sid": "APxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "friendly_name": "My App", "voice_url": "https://example.com/voice",