Getting Started with Telnyx Programmable Voice API

​

Introduction

​

Prerequisites

• A Telnyx account: Sign up if you don’t already have an account.
• API key: Obtain your API Key from the Telnyx Mission Control Portal.
• A Telnyx phone number to call from: search and order one if your account has none. Outbound calls are rejected (error D35, “Caller Origination Number is Invalid”) when from is not a number on your account.
• A Voice API application (also called a Call Control connection) with a webhook URL, and an Outbound Voice Profile attached to it. Its id is the connection_id you pass when dialing. Create one via the API or in the portal.
• Development setup: install an official SDK (pip install telnyx, npm install telnyx) or use curl.

​

Core Concepts

• Voice APl Applications: They act as the backbone for handling incoming and outgoing calls, providing a flexible framework for various use cases such as call routing and caller verification.
• Outbound Voice Profile: This component is key to configuring outbound calls, including setting up billing and controlling traffic destinations. It’s crucial for implementing features like automated outbound calling, call forwarding, and international call management and must be associated with the voice API application. Further details are available in the Outbound Voice Profile section.
• Webhooks: Webhooks in the Telnyx API provide real-time notifications about various call events to your server. They are integral for monitoring call progress, handling call outcomes, and integrating with external systems for actions like database logging or triggering additional workflows. Learn more about implementing webhooks in the Webhooks guide.

​

Requirements

• Telnyx Account and API Key
• Caller and Receiver Numbers in E.164 format (e.g., +1234567890)
• Outbound Voice Profile configured in your Telnyx account
• Voice API Application with a webhook URL set up

​

Hello World Example

curl --location 'https://api.telnyx.com/v2/calls' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YourAPIKey' \
--data '{
   "to":"+13125790015",
   "from":"+13125790968",
   "connection_id":"234423"
}'

import json
import os
from telnyx import Telnyx

client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

response = client.calls.dial(
    to="+13125790015",
    from_="+13125790968",  # a number on your Telnyx account
    connection_id="234423",  # id of your Voice API application
    webhook_url="https://example.com/webhooks/telnyx",
)

print(json.dumps(response.model_dump(), indent=2, default=str))
print(response.data.call_control_id, response.data.is_alive)

import Telnyx from 'telnyx';

const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

const response = await client.calls.dial({
  to: '+13125790015',
  from: '+13125790968', // a number on your Telnyx account
  connection_id: '234423', // id of your Voice API application
  webhook_url: 'https://example.com/webhooks/telnyx',
});

console.log(JSON.stringify(response, null, 2));
console.log(response.data.call_control_id, response.data.is_alive);

​

Next Steps

• Resources: This section offers a variety of resources to deepen your understanding of the Programmable Voice API. It includes documentation, code examples, and troubleshooting guides to enhance your skills in voice API implementation.
• Tutorials: Dive deeper into the Voice API to explore its comprehensive features. This section provides detailed information on advanced API functionalities, enabling more complex voice application development and integration.

​

Additional Resources

​

Feedback