​

Telnyx Development — Full Documentation

Account setup, authentication, API fundamentals, SDKs, CLI, MCP servers, and integration guides. Complete page content for the Development section of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this section: https://developers.telnyx.com/development/llms-txt.md

​

Account setup

​

Create Account

Source: https://developers.telnyx.com/docs/account-setup/create-account.md

​

Account creation steps

​

Need help?

• Review the Account Setup FAQ
• Contact our support team through the Mission Control Portal
• Join the Telnyx Slack community for developer support

​

Account Signup

Source: https://developers.telnyx.com/docs/account-setup/signup.md

• Domain age
• Domain reputation
• Host reputation
• IP reputation
• Signup origin
• reCAPTCHA verification

• Successfully validating a legitimate mobile number
• Successfully passing Know Your Customer (KYC) documentation verification

​

Account Levels Overview

Source: https://developers.telnyx.com/docs/account-setup/levels-and-capabilities.md

• Level 1 / Level 2 account framework
• Pretrial-Trial-Paid-Verified-Enterprise (PTPVE) framework

• V2 APIs
• S3 Compatible Storage APIs

​

Pretrial Account

Source: https://developers.telnyx.com/docs/account-setup/levels-and-capabilities/pretrial.md

​

Testing credit

​

Access

• Full access to AI Suite (AI Assistant, Inference, Cloud Storage) except otherwise specified below.
• Telnyx reserves the right to modify limitations without notification.

​

Numbers

​

Number searching

• Full number display limited to USA local numbers only.
• All other numbers will be shown redacted (e.g., +49351xxxxxxx).
• No access to other APIs or features in this category.

​

Number reservation

• No access to APIs or features in this category.

​

Number ordering

• Limited to 1 USA local number per pretrial account lifetime.
• No access to global numbers.
• No port out is allowed on this number.
• This number will be reclaimed within 30 days of purchase if the account has not upgraded.
• No access to other APIs or features in this category.

​

Number porting

• No access to APIs or features in this category.

​

Bundles

• No access to APIs or features in this category.

​

Messaging

• Limited to 1 messaging profile at any one time.
• Outbound: Limited to long code sending, destination limited to verified number, and capped at 10 messages a day.
• Inbound: Limited to receiving from the verified number.
• No access to other APIs or features in this category.

​

Verify

• No access to APIs or features in this category.

​

Voice

​

General limits

• Limited to 1 TeXML Application at any one time.
• Limited to 1 outbound voice profile at any one time.
• Outbound limited to dialing only the verified phone number.
• Inbound limited to receiving from the verified phone number.
• Limited to 2 concurrent outbound calls.
• Limited to a maximum of 10 minutes per call.

​

Programmable Voice

• All machine-generated voices are prepended with: “This is an automated call generated on the Telnyx platform, please report any abuse to fraud@telnyx.com”.
• This applies to:
  • /v2/calls
  • /v2/calls/:call_control_id/actions/transfer
  • /v2/calls/:call_control_id/actions/gather_using_audio
  • /v2/calls/:call_control_id/actions/gather_using_speak
  • /v2/calls/:call_control_id/actions/playback_start
  • /v2/calls/:call_control_id/actions/speak
  • /v2/calls/:call_control_id/actions/gather_using_ai
  • /v2/calls/:call_control_id/actions/ai_assistant_start
  • TeXML verb Play
  • TeXML verb Say
  • TeXML verb AIGather
• Limited to a maximum of 10 outbound calls a day.

​

Call Control Applications

• No access to APIs or features in this category.

​

Microsoft Operator Connect

• No access to APIs or features in this category.

​

Microsoft Direct Routing

• No access to APIs or features in this category.

​

Zoom Phone Provider Exchange

• No access to APIs or features in this category.

​

LRN / Number Lookup

• No access to APIs or features in this category.

​

Cloud Storage

• Limited to non-public policy or ACL on buckets or objects.
• Limited to 5 minutes of TTL on pre-signed URLs.
• Limited to the documented free tier of used capacity across all buckets and regions.

​

Wireless

• No access to APIs or features in this category.

​

Account features

​

Organizations and sub-users

• No access to APIs or features in this category.

​

ManagED Accounts

• No access to APIs or features in this category.

​

Payment methods

• No access to APIs or features in this category. Credit is not required — AI credits are provided.

​

Billing groups

• No access to APIs or features in this category.

​

API keys

• Limited to 1 API key at any one time.
• No access to other APIs or features in this category.

​

DDoS mitigation

• No access to APIs or features in this category.

​

Trial Account

Source: https://developers.telnyx.com/docs/account-setup/levels-and-capabilities/trial.md

​

Testing credit

​

Access

• Full access except otherwise specified below.
• Telnyx reserves the right to modify limitations without notification.

​

Numbers

​

Verified numbers

• Limited to 1 verified number at any one time.
• Limited to 10 changes per trial account lifetime.
• Limited to 15 delivery attempts regardless of conversion outcome per trial account lifetime.

​

Number searching

• Full number display limited to local numbers of the account’s country of origin.
• All other numbers will be shown redacted (e.g., +49351xxxxxxx).
• No access to other APIs or features in this category.

​

Number reservation

• No access to APIs or features in this category.

​

Number ordering

• Limited to 1 local number of the account’s country of origin per trial account lifetime.
• Successful number activation is subject to inventory availability, sufficient account balance, and local jurisdiction documentation rules.
• This number will be reclaimed within 30 days of purchase if the account has not upgraded.
• No port out is allowed on this number.
• No access to other APIs or features in this category.

​

Number porting

• Limited to 50 portability check attempts per trial account lifetime.
• No access to other APIs or features in this category.
• Users do not have proprietary rights to their trial telephone number, and Telnyx reserves the right to make reasonable changes to them with reasonable notice. Users cannot port out their trial number.

​

Bundles

• No access to APIs or features in this category.

​

Messaging

• Limited to 1 messaging profile at any one time.
• Outbound: Limited to long code sending, destination limited to verified number, and capped at 100 messages a day.
• Inbound: Limited to receiving from the verified number.
• No access to other APIs or features in this category.

​

Verify

• Limited to 1 verified profile at any one time.
• Only SMS is allowed.
• Destination limited to verified number.
• Limited to a max of 50 verifications a day.
• No access to other APIs or features in this category.

​

Voice

​

General limits

• Limited to 1 instance per connection type at any one time.
• Limited to 1 outbound voice profile at any one time.
• Outbound limited to dialing only the verified phone number.
• Inbound limited to receiving from the verified phone number.
• Limited to 2 concurrent outbound calls across all connection instances.
• Limited to a maximum of 10 minutes per call.

​

Programmable Voice

• All machine-generated voices are prepended with: “This is an automated call generated on the Telnyx platform, please report any abuse to fraud@telnyx.com”.
• This applies to:
  • /v2/calls
  • /v2/calls/:call_control_id/actions/transfer
  • /v2/calls/:call_control_id/actions/gather_using_audio
  • /v2/calls/:call_control_id/actions/gather_using_speak
  • /v2/calls/:call_control_id/actions/playback_start
  • /v2/calls/:call_control_id/actions/speak
  • /v2/calls/:call_control_id/actions/gather_using_ai
  • /v2/calls/:call_control_id/actions/ai_assistant_start
  • TeXML verb Play
  • TeXML verb Say
  • TeXML verb AIGather
• Limited to a maximum of 100 outbound calls a day.
• Limited to 10 outbound calls per hour.

​

Microsoft Operator Connect

• No access to APIs or features in this category.

​

Microsoft Direct Routing

• No access to APIs or features in this category.

​

Zoom Phone Provider Exchange

• No access to APIs or features in this category.

​

LRN / Number Lookup

• No access to APIs or features in this category.

​

Cloud Storage

• Limited to non-public policy or ACL on buckets or objects.
• Limited to 5 minutes of TTL on pre-signed URLs.
• Limited to the documented free tier of used capacity across all buckets and regions.

​

Wireless

• No access to physical SIM registration.
• No access to eSIM purchase.

​

Account features

​

Organizations and sub-users

• No access to APIs or features in this category.

​

ManagED Accounts

• No access to APIs or features in this category.

​

Payment methods

• Limited to credit cards.

​

Billing groups

• No access to APIs or features in this category.

​

API keys

• Limited to 1 API key at any one time.
• No access to other APIs or features in this category.

​

DDoS mitigation

• No access to APIs or features in this category.

​

Using Your Trial Account

Source: https://developers.telnyx.com/docs/account-setup/using-trial-account.md

• SIP Trunking
• Programmable Voice
• TeXML

​

Paid Account

Source: https://developers.telnyx.com/docs/account-setup/levels-and-capabilities/paid.md

​

Access

• Full access except otherwise specified below.
• Telnyx reserves the right to modify limitations without notification.

​

Numbers

​

Number searching

• No access to number blocks.

​

Number ordering

• Limited to local numbers whose country code matches the account’s country of origin.

​

Number porting

• No access to LRN migration.

​

Messaging

• No access to 10DLC.
• No access to Toll-Free verification.
• No access to hosted messaging.

​

Voice

​

General limits

• Limited set of outbound destination country codes.
• Limited to 5 concurrent outbound calls across all connection types.

​

Programmable Voice

• All machine-generated voices are prepended with: “This is an automated call generated on the Telnyx platform, please report any abuse to fraud@telnyx.com”.
• This applies to:
  • /v2/calls
  • /v2/calls/:call_control_id/actions/transfer
  • /v2/calls/:call_control_id/actions/gather_using_audio
  • /v2/calls/:call_control_id/actions/gather_using_speak
  • /v2/calls/:call_control_id/actions/playback_start
  • /v2/calls/:call_control_id/actions/speak
  • /v2/calls/:call_control_id/actions/gather_using_ai
  • /v2/calls/:call_control_id/actions/ai_assistant_start
  • TeXML verb Play
  • TeXML verb Say
  • TeXML verb AIGather
• Limited to a maximum of 100 outbound calls a day.
• Limited to 10 outbound calls per hour.

​

Cloud Storage

• Limited to non-public policy or ACL on buckets or objects.
• Limited to 5 minutes of TTL on pre-signed URLs.

​

Account features

​

ManagED Accounts

• No access to APIs or features in this category.

​

Payment methods

• Credit card
• PayPal

​

DDoS mitigation

• No access to APIs or features in this category.

​

Verified Account

Source: https://developers.telnyx.com/docs/account-setup/levels-and-capabilities/verified.md

​

Access

• Full access except otherwise specified below.
• Telnyx reserves the right to modify limitations without notification.

​

Numbers

​

Number searching

• No access to number blocks.

​

Number ordering

• No access to number blocks.

​

Number porting

• No access to LRN migration.

​

Account features

​

ManagED Accounts

• No access to APIs or features in this category.

​

Payment methods

• Credit card
• PayPal
• BTC

​

DDoS mitigation

• No access to APIs or features in this category.

​

Account Upgrade

Source: https://developers.telnyx.com/docs/account-setup/account-upgrade.md

​

Data Locality

Source: https://developers.telnyx.com/docs/account-setup/data-locality.md

​

Available regions

​

Covered data types

• Call Detail Records (CDRs)
• Message Detail Records (MDRs)
• Conference records
• Forking CDRs
• Media Storage (recordings)
• Premium AMD
• Speech-to-Text
• Verify
• Video
• WhatsApp
• Wireless

​

Selecting a region

1. Log in to the Mission Control Portal.
2. Go to Account settings > Profile.
3. Scroll to Data Storage Location and select a country from the dropdown.
4. Click Save Location.

​

APIs fundamentals

​

Create API Keys

Source: https://developers.telnyx.com/development/api-fundamentals/create-api-keys.md

​

Creating Your API Key

1. In the Mission Control Portal, click on your name in the upper right corner, and click API Keys.
2. Click the Create API Key button.

3. In the Create API Key dialog, add a descriptive tag (e.g., “Voice API Development”, “SMS Production”, etc.) and choose your expiration settings.

4. Click Create.

​

Important: Save Your API Key Securely

​

Storing Your API Key

• Never commit API keys to version control (Git, SVN, etc.).
• Use environment variables in your applications.
• Rotate keys regularly for production applications.
• Use separate keys for development and production.

export TELNYX_API_KEY="YOUR_API_KEY"

​

Using Your API Key

​

REST API

curl -X GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/endpoint"

​

SDKs

// Node.js
const telnyx = require('telnyx')('YOUR_API_KEY');

// Python
import telnyx
telnyx.api_key = "YOUR_API_KEY"

// Ruby
Telnyx.api_key = "YOUR_API_KEY"

​

API Authentication

Source: https://developers.telnyx.com/development/api-fundamentals/authentication.md

​

API Keys

​

Overview

​

Security Best Practices

• Keep API Keys secure: Never share API Keys in publicly accessible areas such as GitHub, client-side code, or logs
• Use environment variables: Store API Keys in environment variables or secure configuration files
• Rotate keys regularly: Periodically generate new API Keys and deactivate old ones
• Use least privilege: If available, use API Keys with minimal required permissions

​

Managing API Keys

​

Authentication Methods

​

Bearer Token Authentication

curl -X GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/endpoint"

​

SDK Authentication

// Node.js SDK
const telnyx = require('telnyx')('YOUR_API_KEY');

// Python SDK
import telnyx
telnyx.api_key = "YOUR_API_KEY"

// Ruby SDK
Telnyx.api_key = "YOUR_API_KEY"

​

Common Authentication Patterns

​

RESTful APIs

• Voice API: Bearer token in Authorization header
• Messaging API: Bearer token in Authorization header
• Cloud Storage: AWS Signature Version 4 or Bearer token
• IoT APIs: Bearer token in Authorization header

​

Real-time Connections

• WebRTC: JWT tokens for client authentication
• WebSocket connections: Bearer token during connection establishment

​

Error Handling

​

Authentication Errors

• 401 Unauthorized: Invalid or missing API Key
• 403 Forbidden: Valid API Key but insufficient permissions
• 429 Too Many Requests: Rate limit exceeded

​

Debugging Authentication Issues

1. Verify API Key format: Ensure the key is correctly formatted and complete
2. Check headers: Confirm the Authorization header is properly set
3. Validate permissions: Ensure your API Key has the required permissions for the resource
4. Test with curl: Use curl to isolate authentication issues from SDK problems

​

Environment-Specific Considerations

​

Development vs Production

• Use separate API Keys for development and production environments
• Never use production API Keys in development or testing
• Consider using restricted API Keys for development

​

Regional Considerations

​

Account Management

​

Account Levels and Access

​

Next Steps

• API Reliability & Retries - Handle authentication failures gracefully
• Webhook Security - Secure your webhook endpoints
• SDKs & Tools - Language-specific authentication setup

​

HTTP Patterns

Source: https://developers.telnyx.com/development/api-fundamentals/request-response.md

​

HTTP Methods

​

GET - Retrieve Resources

GET /v2/messaging_profiles
GET /v2/calls/{call_id}
GET /v2/storage/buckets

​

POST - Create Resources

POST /v2/calls          # Make a phone call
POST /v2/messages       # Send a message
POST /v2/storage/objects # Upload a file

​

PATCH - Update Resources

PATCH /v2/messaging_profiles/{id} # Update profile
PATCH /v2/phone_numbers/{id}      # Update phone number settings

​

DELETE - Remove Resources

DELETE /v2/messaging_profiles/{id}     # Delete messaging profile
DELETE /v2/telephony_credentials/{id}  # Delete telephony credential

​

Request Format

​

Content-Type Headers

Content-Type: application/json

Content-Type: multipart/form-data
Content-Type: application/x-www-form-urlencoded

​

Request Structure

curl -X POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+1234567890",
    "from": "+0987654321",
    "text": "Hello World"
  }' \
  "https://api.telnyx.com/v2/messages"

​

Response Format

​

Standard Response Structure

{
  "data": {
    "id": "resource_id",
    "record_type": "resource_type",
    // ... resource properties
  },
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 5,
    "total_results": 100
  }
}

​

Success Responses

• 200 OK: Request successful, data returned
• 201 Created: Resource successfully created
• 202 Accepted: Request accepted, processing asynchronously
• 204 No Content: Request successful, no data to return

​

Error Responses

{
  "errors": [
    {
      "code": "10001",
      "title": "Invalid parameter",
      "detail": "The 'to' field is required",
      "source": {
        "pointer": "/data/attributes/to"
      }
    }
  ]
}

​

Telnyx API Error Codes

• 10xxx codes: Parameter validation errors
• 20xxx codes: Authentication and authorization errors
• 30xxx codes: Resource not found or unavailable errors
• 40xxx codes: Rate limiting and quota errors
• 50xxx codes: Server-side errors

​

HTTP Status Codes

​

Client Errors (4xx)

• 400 Bad Request: Invalid request format or parameters
• 401 Unauthorized: Authentication failed
• 403 Forbidden: Authentication succeeded but access denied
• 404 Not Found: Resource doesn’t exist
• 422 Unprocessable Entity: Valid request format but logical errors
• 429 Too Many Requests: Rate limit exceeded

​

Server Errors (5xx)

• 500 Internal Server Error: Unexpected server error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Service temporarily unavailable
• 504 Gateway Timeout: Request timeout

​

Common Headers

​

Request Headers

Authorization: Bearer YOUR_API_KEY    # Authentication
Content-Type: application/json       # Request format
Accept: application/json             # Expected response format
User-Agent: YourApp/1.0             # Client identification

​

Response Headers

Content-Type: application/json      # Response format
X-RateLimit-Limit: 100             # Rate limit maximum
X-RateLimit-Remaining: 75          # Remaining requests
X-RateLimit-Reset: 1640995200      # Rate limit reset time

​

Pagination

​

Request Parameters

GET /v2/messages?page[number]=2&page[size]=50

​

Response Metadata

{
  "data": [...],
  "meta": {
    "page_number": 2,
    "page_size": 50,
    "total_pages": 10,
    "total_results": 500
  }
}

​

Filtering and Sorting

​

Common Filter Patterns

# Filter by date range
GET /v2/messages?filter[created_at][gte]=2023-01-01

# Filter by status
GET /v2/calls?filter[status]=completed

# Sort results
GET /v2/messages?sort=created_at
GET /v2/calls?sort=-created_at  # Descending order

​

Best Practices

​

Request Optimization

• Use appropriate HTTP methods: Don’t use POST for retrieving data
• Include relevant headers: Specify Content-Type and Accept headers
• Validate input: Check parameters before sending requests
• Handle timeouts: Set appropriate timeout values

​

Response Handling

• Check status codes: Don’t assume all responses are successful
• Parse error messages: Use error details for troubleshooting
• Handle edge cases: Account for empty results and partial failures
• Log appropriately: Log errors but avoid logging sensitive data

​

Next Steps

• API Reliability & Retries - Handle failed requests
• Webhook Fundamentals - Receive asynchronous notifications
• API Glossary - Reference for API terminology

​

API error codes

Source: https://developers.telnyx.com/development/api-fundamentals/api-errors.md

​

Rate Limiting

Source: https://developers.telnyx.com/development/api-fundamentals/reliability/rate-limiting.md

​

Rate Limit Headers

​

Rate Limit Response

​

HTTP Status Code

​

Response Body

{
  "errors": [
    {
      "code": "10011",
      "title": "Too many requests",
      "detail": "You have exceeded the maximum number of allowed requests."
    }
  ]
}

​

Handling Rate Limits

​

Best Practices

1. Monitor Headers: Always check the rate limit headers in API responses
2. Implement Backoff: Use exponential backoff when receiving 429 responses
3. Cache Results: Cache API responses when possible to reduce request frequency
4. Distribute Load: Spread requests across multiple time windows

​

Over Your Rate Limit?

​

Product-Specific Rate Limits

• Messaging: See Rate Limiting and Message Encoding for messaging-specific limits
• 10DLC: See 10DLC rate limits for campaign-specific limits
• Voice API: Standard API rate limits apply to call control endpoints
• Cloud Storage: Rate limits apply to S3-compatible operations

​

API Reliability & Retries

Source: https://developers.telnyx.com/development/api-fundamentals/reliability/command-retries.md

​

Common Reliability Challenges

• 5XX Errors: Server errors (500, 501, 503, 504) that indicate temporary service issues
• Network Timeouts: Requests that don’t complete within expected timeframes
• Duplicate Responses: Identical responses that may occasionally be delivered

​

Best Practices for API Reliability

​

Retry Strategies

• Retry on 5XX Errors: If your application receives a 500-level error, implement exponential backoff and retry
• Timeout Handling: If your application fails to receive an HTTP response within a reasonable timeframe (typically 500ms-5s depending on the operation), retry the request
• Maximum Retry Attempts: Implement a maximum retry limit (typically 3-5 attempts) to avoid infinite loops

​

Error Handling Patterns

• Exponential Backoff: Increase wait time between retries (e.g., 1s, 2s, 4s, 8s)
• Circuit Breaker: Temporarily stop making requests if error rates exceed thresholds
• Graceful Degradation: Design your application to continue functioning even when some API calls fail

​

Webhook Fundamentals

Source: https://developers.telnyx.com/development/api-fundamentals/webhooks/receiving-webhooks.md

​

Universal Webhook Behavior

• Primary/Failover URLs: Webhooks are delivered to the primary URL specified in your application configuration. If that URL doesn’t respond successfully, the webhook is sent to the failover URL (if configured)
• Response Requirements: Your endpoint must return a 2xx HTTP status code to indicate successful receipt
• Retry Logic: Failed webhook deliveries are automatically retried with exponential backoff

​

Webhook Setup Options

​

Option A: Local Development with ngrok (Recommended for Testing)

1. Install ngrok following our ngrok setup guide.
2. Start your local webhook server (see example below).
3. Create a tunnel: ngrok http 3000.
4. Use the provided HTTPS URL (e.g., https://abc123.ngrok.io/webhooks).

​

Option B: Quick Testing with webhook.site

1. Visit webhook.site.
2. Copy your unique URL.
3. Use this for initial testing (note: this won’t allow you to respond to webhooks).

​

Option C: Production Deployment

• AWS Lambda with API Gateway.
• Google Cloud Functions.
• Heroku.
• DigitalOcean App Platform.

​

Webhook Delivery Characteristics

• Does not guarantee delivery order: Webhooks may arrive out of sequence
• Implements automatic retries: Failed deliveries are retried with exponential backoff
• Delivers concurrently: Multiple webhooks may arrive simultaneously

• Out-of-order webhooks: Events may not arrive in chronological order
• Simultaneous webhooks: Multiple events may be delivered at the same time
• Duplicate webhooks: The same event may be delivered more than once

​

Handling Duplicate Events

• Use idempotency keys: Include unique identifiers in your API requests (such as command_id, idempotency_key, etc.)
• Implement deduplication: Track processed webhook IDs to avoid duplicate processing
• Design idempotent operations: Ensure that processing the same event multiple times has no adverse effects

​

Webhook Payload Structure

• Event ID: Unique identifier for the webhook event
• Timestamp: When the event occurred
• Resource IDs: Identifiers that correlate the webhook with your resources (calls, messages, etc.)
• Event Type: Describes what action triggered the webhook

​

Security & Protocols

​

HTTP and HTTPS

• Unsecure (HTTP) URLs are allowed for webhooks.
• If HTTPS (TLS) is used, the certificate will be validated.

​

Event type naming

• resource.created
• resource.updated
• resource.deleted

• message.created
• message.deleted
• message.delivered
• message.received
• porting_sub_request.ported
• porting_sub_request.closed

​

Webhook Structure

​

Voice API top-level structure

{
  "call_leg_id": "e97d8d4c-1a25-11cd-bc67-02620a0f6d42",
  "call_session_id": "e97da4f0-1a25-11bd-909f-02620a0f6d642",
  "event_timestamp": "2019-11-10T22:25:27.521992Z",
  "metadata": {
    "attempt": 1,
    "delivered_to": "https://www.example.com/callback",
    "event": {
      "event_type": "call.initiated",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "occurred_at": "2019-11-10T22:25:27.521992Z",
      "payload": {
        ...
      },
      "record_type": "event"
    },
    "status": "delivered"
  },
  "name": "call.initiated",
  "organization_id": null,
  "type": "webhook",
  "user_id": "901dbc74-1597-4d15-aad2-xxxxxxxxxxxx"
}

​

Messaging top-level structure

{
"data": {
   "event_type": "message.finalized",
   "id": "4ef8c3a6-4195-4389-b3a6-38e3cb9eb4ae",
   "occurred_at": "2019-11-10T22:30:14.148+00:00",
   "payload": {
     ...
   },
   "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://www.example.com/messaging"
  }
}

​

Example: Receiving a Webhook

{
  "data": {
    "record_type": "event",
    "event_type": "call.initiated",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "call_leg_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "from": "+1-202-555-0133",
      "to": "+12025550131",
      "direction": "incoming",
      "state": "parked"
    }
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "http://example.com/webhooks"
  }
}

Note: After pasting the above content, Kindly check and remove any new line added

​

Full Voice API example

{
  "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
  "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
  "event_timestamp": "2019-11-10T22:26:27.521992Z",
  "metadata": {
    "attempt": 1,
    "delivered_to": "https://www.example.com/callback",
    "event": {
      "event_type": "call.answered",
      "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
      "occurred_at": "2019-11-10T22:26:27.521992Z",
      "payload": {
        "call_control_id": "v2:F5_vIJVqrosogeY_2L_JhCEHd2Dh-x4xz7tROTbh34tg6Zsk4JJc-w",
        "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
        "client_state": null,
        "connection_id": "7267xxxxxxxxxxxxxx",
        "from": "+8005550199",
        "start_time": "2019-11-10T22:26:26.521992Z",
        "to": "+8005550100"
      },
      "record_type": "event"
    },
    "status": "delivered"
  },
  "name": "call.answered",
  "organization_id": null,
  "type": "webhook",
  "user_id": "901dbc74-1597-4d15-aad2-xxxxxxxxxxxx"
}

​

Responding to a webhook

​

Retries

​

Best practices

​

Webhook signing

Base64.encode64("#{timestamp}|#{payload}")

​

Parameters & Field Names

Source: https://developers.telnyx.com/development/api-fundamentals/data-standards/parameters-fields.md

​

Data Types

​

Booleans

​

Date-times

• YYYY-MM-DDThh:mm:ss.fffZ
• YYYY-MM-DDThh:mm:ssZ
• YYYY-MM-DDThh:mmZ
• The above with -00, -0000, or -00:00 instead of the Z timezone identifier.

​

Times (no date portion)

​

Durations

• millis
• secs
• hours
• days
• weeks
• months
• years

​

Time zones

​

Date Literals

​

HTTP Headers

​

Naming Conventions

​

Enums and string literals

​

Country codes

​

Phone numbers

​

City names

​

Address Format

{
  "street_address": "311 W Superior St",
  "extended_address": "Suite 504",
  "locality": "Chicago",
  "administrative_area": "IL"
  "country_code": "US",
  "postal_code": "60654"
}

​

U.S. addresses

​

Pagination

​

Example

​

Example Response

HEADERS

Total-Pages:13

{
  "meta": {
    "total_pages": 13,
    "total_results": 26,
    "page_number": 3,
    "page_size": 2
  },
  "data": [
    {
      "record_type": "phone_number",
      "id": "4567890987",
      "phone_number": "+18005550100",
      "purchased_at": "2015-05-22T14:56:29.000Z",
      ...
    },
    {
      "record_type": "phone_number",
      "id": "44568890987",
      "phone_number": "+18005550199",
      "purchased_at": "2015-05-22T14:56:29.000Z",
      ...
    }
  ]
}

​

Sorting

​

Example

GET /connections?sort=name HTTP/1.1

​

Multiple Sort Fields

GET /connections?sort[]=name&sort[]=created_at HTTP/1.1

GET /connections?sort[]=-created_at&sort[]=name HTTP/1.1

​

Filtering

GET /phone_numbers?filter[tag]=tag_one HTTP/1.1

GET /phone_numbers?filter[tag][]=tag_one&filter[tag][]=tag_two HTTP/1.1

GET /comments?filter[tag]=tag_one,tag_two HTTP/1.1

GET /comments?filter[author]=null HTTP/1.1

​

Filtering on values of nested or related objects

{
  "id": "d460a653-8ee6-4061-ae9a-5b8a52539fb4",
  "phone_number": "18005550199",
  "record_type": "phone_number",
  ...
  "voice": {
    "e911_address_id" : "",
    "connection_name" : false,
    "inbound_call_recording_channels" : "single",
    ...
  }
}

GET /phone_numbers?filter[voice.connection_name]=conn_one HTTP/1.1

GET /regions?filter[voice.connection_id]=d460a653-8pp6-4061-ae9a-5b8a57339fb4 HTTP/1.1

{
  "id": "d460a653-8pp6-4061-ae9a-5b8a57339fb4",
  "name": "conn_one",
  "record_type": "connection",
  ...
}

GET /connections?filter[name]=conn_one HTTP/1.1

​

Complex filters

• eq
• ne
• gt
• gte
• lt
• lte
• starts_with
• ends_with
• contains

GET /phone_numbers?filter[purchased_at][lt]=2018-02-21 HTTP/1.1

GET /phone_numbers?filter[purchased_at][eq]=2018-02-21 HTTP/1.1

GET /phone_numbers?filter[purchased_at]=2018-02-21 HTTP/1.1

GET /phone_numbers?filter[voice.connection_name][contains]=conn HTTP/1.1

​

Server-side SDKs

​

Node.js

Source: https://developers.telnyx.com/development/sdk/node.md

​

Python

Source: https://developers.telnyx.com/development/sdk/python.md

​

PHP

Source: https://developers.telnyx.com/development/sdk/php.md

<?php
require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Credentials\CredentialProvider;
use Aws\Exception\AwsException;

$telnyxAPIKey = getenv('TELNYX_API_KEY');
if (!$telnyxAPIKey) {
  die('TELNYX_API_KEY environment variable not set');
}

$region = 'us-central-1';
$endpoint = "https://{$region}.telnyxcloudstorage.com";

// 1. Initializing the AWS client with specific options
$s3Client = new S3Client([
  'region'  => $region,
  'version' => 'latest',
  'endpoint' => $endpoint,
  'credentials' => [
      'key'  => $telnyxAPIKey,
      'secret' => $telnyxAPIKey,
  ],
  'use_path_style_endpoint' => true
]);

$bucketName = "test-bucket-" . $region . '-' . date('H-i') . '-' . rand(0, 1000000);
echo "Generated bucket name: " . $bucketName . PHP_EOL;

// 2. Create a bucket
try {
  $s3Client->createBucket([
      'Bucket' => $bucketName
  ]);
  echo "Created bucket: {$bucketName}" . PHP_EOL;
} catch (AwsException $e) {
  die("Unable to create bucket: " . $e->getMessage());
}

// 3. Upload two objects with random data
for ($i = 0; $i < 2; $i++) {
  $content = random_bytes(1024 * 32); // 32KB of random data
  $objName = "{$i}.txt";
  try {
      $s3Client->putObject([
          'Bucket' => $bucketName,
          'Key'  => $objName,
          'Body'   => $content
      ]);
      echo "Uploaded file ({$objName}) to bucket: {$bucketName}" . PHP_EOL;
  } catch (AwsException $e) {
      die("Unable to upload file ({$objName}): " . $e->getMessage());
  }
}

// 4. List objects in the bucket
try {
  $result = $s3Client->listObjects([
      'Bucket' => $bucketName
  ]);
  foreach ($result['Contents'] as $item) {
      echo "Listed object: " . $item['Key'] . PHP_EOL;
  }
} catch (AwsException $e) {
  die("Unable to list objects: " . $e->getMessage());
}

// 5. Download the first object
try {
  $result = $s3Client->getObject([
      'Bucket' => $bucketName,
      'Key'  => '1.txt'
  ]);
  $data = $result['Body']->getContents();
  echo "Downloaded file size: " . strlen($data) . PHP_EOL;
} catch (AwsException $e) {
  die("Unable to download object: " . $e->getMessage());
}

// 6. Create a presigned URL for the first file
$url = "https://api.telnyx.com/v2/storage/buckets/{$bucketName}/1.txt/presigned_url";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['TTL' => 30]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $telnyxAPIKey,
  'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpcode != 200) {
  die("Unexpected status code: {$httpcode} | response: {$response}");
}

$presignedData = json_decode($response, true);
$presignedURL = $presignedData['data']['presigned_url'];
echo "Generated presigned URL: {$presignedURL}" . PHP_EOL;

// 7. Download the file using the presigned URL
$ch = curl_init($presignedURL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

echo "Downloaded presigned URL data size: " . strlen($result) . PHP_EOL;
?>

​

Java

Source: https://developers.telnyx.com/development/sdk/java.md

​

Add Dependency

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>s3</artifactId>
  <version>2.20.0</version> <!--  Or any 2.x version -->
</dependency>

​

Create S3 Bucket

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;

public class CreateBucket {

  public static void main(String[] args) {
      String bucketName = "--your-bucket-name--";
      Region region = Region.US_EAST_1;
      String telnyxUrl = "https://us-central-1.telnyxcloudstorage.com";
      String telnyxApiKey = "-- api key --";

      // Create an S3 client
      S3Client s3 = S3Client.builder()
              .region(region)
              .endpointOverride(URI.create(telnyxUrl))
                // Only perform CRC checks `when_required`
                .requestChecksumCalculation(RequestChecksumCalculation.WHEN_REQUIRED)
                .responseChecksumValidation(ResponseChecksumValidation.WHEN_REQUIRED)
              .credentialsProvider(
                      StaticCredentialsProvider.create(AwsBasicCredentials.create(telnyxApiKey, "does not matter")))
              .build();

      // create bucket
      CreateBucketRequest createBucketRequest = CreateBucketRequest.builder()
              .bucket(bucketName)
              .build();

      s3.createBucket(createBucketRequest);
      System.out.println("Bucket created successfully: " + bucketName);

      // Close the S3 client
      s3.close();
  }

}

​

Upload an Object

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;

import java.net.URI;
import java.nio.file.Paths;

public class UploadObjectToS3 {

  public static void main(String[] args) {
      String bucketName = "--your-bucket-name--";
      String keyName = "your-object-key";
      String filePath = "--path to file for upload--";

      Region region = Region.US_EAST_1;
      String telnyxUrl = "https://us-central-1.telnyxcloudstorage.com";
      String telnyxApiKey = "--your api key --";

      // Create an S3 client
      S3Client s3 = S3Client.builder()
              .region(region)
              .endpointOverride(URI.create(telnyxUrl))
              .credentialsProvider(
                      StaticCredentialsProvider.create(AwsBasicCredentials.create(telnyxApiKey, "does not matter")))
              .build();

      // upload object
      PutObjectRequest putObjectRequest = PutObjectRequest.builder()
              .bucket(bucketName)
              .key(keyName)
              .build();

      // Upload the file to S3
      s3.putObject(putObjectRequest, RequestBody.fromFile(Paths.get(filePath)));

      // Close the S3 client
      s3.close();
  }

}

​

List Objects

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
import software.amazon.awssdk.services.s3.model.S3Object;

import java.net.URI;

public class ListObjects {

  public static void main(String[] args) {
      String bucketName = "--your-bucket-name--";
      Region region = Region.US_EAST_1;
      String telnyxUrl = "https://us-central-1.telnyxcloudstorage.com";
      String telnyxApiKey = "--your api key --";

      // Create an S3 client
      S3Client s3 = S3Client.builder()
              .region(region)
              .endpointOverride(URI.create(telnyxUrl))
              .credentialsProvider(
                      StaticCredentialsProvider.create(AwsBasicCredentials.create(telnyxApiKey, "does not matter")))
              .build();
      // Create a ListObjectsV2Request
      ListObjectsV2Request listObjectsRequest = ListObjectsV2Request.builder()
              .bucket(bucketName)
              .build();

      // Get the list of objects in the bucket
      ListObjectsV2Response listObjectsResponse = s3.listObjectsV2(listObjectsRequest);

      for (S3Object s3Object : listObjectsResponse.contents()) {
          System.out.println( s3Object.key());
      }

      // Close the S3 client
      s3.close();
  }

}

​

Download Object

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.core.ResponseBytes;
import software.amazon.awssdk.core.sync.ResponseTransformer;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.net.URI;

public class DownloadObject {

  public static void main(String[] args) throws IOException {
      String bucketName = "--your-bucket-name--";
      Region region = Region.US_EAST_1;
      String telnyxUrl = "https://us-central-1.telnyxcloudstorage.com";
      String telnyxApiKey = "--your api key --";
      String keyName = "your-object-key";

      S3Client s3 = S3Client.builder()
              .region(region)
              .endpointOverride(URI.create(telnyxUrl))
              .credentialsProvider(
                      StaticCredentialsProvider.create(AwsBasicCredentials.create(telnyxApiKey, "does not matter")))
              .build();

      // Create a GetObjectRequest
      GetObjectRequest getObjectRequest = GetObjectRequest.builder()
              .bucket(bucketName)
              .key(keyName)
              .build();

      // Download the object and transform the response to a byte array
      ResponseBytes<GetObjectResponse> objectBytes = s3.getObject(getObjectRequest, ResponseTransformer.toBytes());

      // Write the file to the specified path
      File downloadedFile = new File("-- path to where to save the file --");
      try (FileOutputStream fos = new FileOutputStream(downloadedFile)) {
          fos.write(objectBytes.asByteArray());
          System.out.println("File downloaded successfully to -- path to where to save the file --");
      }

      // Close the S3 client
      s3.close();
  }

}

​

Generate Presigned URLs for Upload and Download

<dependency>
      <groupId>com.squareup.okhttp3</groupId>
      <artifactId>okhttp</artifactId>
      <version>4.9.2</version>
</dependency>
<dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.8.7</version>
</dependency>

import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import okhttp3.*;

import java.io.IOException;
import java.util.Map;

public class GeneratePresignedURLAndDownloadObject {

  public static void main(String[] args) throws IOException {
      OkHttpClient httpClient = new OkHttpClient();
      Gson gson = new Gson();

      String presignedUrlRequestJson = gson.toJson(Map.of("TTL", 30));
      RequestBody presignedUrlRequestBody = RequestBody.create(MediaType.parse("application/json"), presignedUrlRequestJson);

      Request presignedUrlRequest = new Request.Builder()
              .url("https://api.telnyx.com/v2/storage/buckets/-- name of the bucket --/--name of the object--/presigned_url")
              .header("Authorization", "Bearer --your api key---")
              .post(presignedUrlRequestBody)
              .build();

      try (Response response = httpClient.newCall(presignedUrlRequest).execute()) {
          if (!response.isSuccessful()) {
              throw new IOException("Failed to create presigned URL: " + response);
          }
          String responseBody = response.body().string();
          Map<String, Object> responseBodyMap = gson.fromJson(responseBody, new TypeToken<Map<String, Object>>() {}.getType());
          String presignedUrl = ((Map<String, String>) responseBodyMap.get("data")).get("presigned_url");

          System.out.println("Presigned URL: " + presignedUrl);

          // 6. Download the file using the presigned URL
          Request downloadRequest = new Request.Builder()
                  .url(presignedUrl)
                  .build();

          try (Response downloadResponse = httpClient.newCall(downloadRequest).execute()) {
              if (!downloadResponse.isSuccessful()) {
                  throw new IOException("Failed to download file using presigned URL: " + downloadResponse);
              }
              System.out.println("Downloaded via presigned URL: " + downloadResponse.body().string());
          }
      }
  }
}

​

Ruby

Source: https://developers.telnyx.com/development/sdk/ruby.md

​

Go

Source: https://developers.telnyx.com/development/sdk/golang.md

​

Telnyx CLI

​

Overview

Source: https://developers.telnyx.com/development/cli.md

​

When to Use the CLI vs the API

​

Features

​

Quick Example

# Set your API key
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx

# List your phone numbers
telnyx phone-numbers list

# Search for available phone numbers
telnyx available-phone-numbers list --filter.country-code US

# Send an SMS
telnyx messages send --from +15551234567 --to +15559876543 --text "Hello from CLI!"

# Check your balance
telnyx balance retrieve

​

Installation

go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest

​

Documentation

​

Resources

​

Install

Source: https://developers.telnyx.com/development/cli/getting-started/install.md

​

Installation

go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest

​

Add to PATH

# Check your Go bin path
go env GOPATH

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

​

Verify Installation

telnyx --version

telnyx version 0.1.0

​

Update