Skip to main content

Voice SDK Quick Start

In 10 minutes we'll...

Configure your Telnyx Portal account and make a test call using our Voice SDK.

Steps to configure your portal account look like this:

  1. Sign up for a Telnyx Account.
  2. Create a Credential Connection to configure how you connect your calls.
  3. Create an Outbound Voice Profile to configure your outbound call settings and assign it to your Credential Connection.
  4. Grab your API key
  5. Create a new on-demand credential and generate a token
  6. Authenticate to the Telnyx WebRTC platform and place a call

Sign up for a Telnyx Mission Control Portal Account

If you don't have an account head to telnyx.com/sign-up to sign up for free. It’ll give you access to our Mission Control Portal where you can buy phone numbers, set up and manage Call Control Applications, and more.

Create a SIP connection using credentials

You'll need a SIP connection to make a test call.

In this example we'll set up the SIP connection using credentials:

  1. From the portal, navigate to the SIP Trunking on the left
  2. Click the "Add SIP Connection"
  3. Enter the name you wish to have for your SIP Connection.
  4. Select "Credentials" as the "Connection Type".
  5. A username and password will automatically be generated. You can ignore it for now.
  6. Copy/paste the Connection ID somewhere as we'll need to use it later.
  7. Click Save and Finish Editing

Create a SIP connection

Enable Receiving SIP URI Calls

By default a SIP connection cannot receive inbound from a SIP destination/URI. Since we're going to a make a test call, later, to SIP destination we must turn this setting on.

To enable receiving calls from a SIP URI:

  1. In the portal go to SIP connections
  2. Find your SIP connection in the table and click the Inbound Options button.
  3. Change the Receive SIP URI Calls option from Disabled to Only from my Connections.

Enabled receiving inbound calls from a SIP destination

Create an Outbound Voice Profile

To place a test call we need to setup an outbound voice profile.

Notes

  • An outbound voice profile let's you configure how your traffic is routed outbound from Telnyx, what type of traffic you're routing, how it's billed / which rate deck to use, and setup international destinations.
  1. Select Outbound Voice Profiles on the left-hand navigation menu,
  2. Click Add New Profile
  3. Give it a name
  4. Add the SIP connection we just created, above as an associated connection
  5. The defaults for Traffic Type and Allow Destinations should be fine.

Note
You may not have to click save for the changes to your profile to update.

Creating an Outbound Voice Profile

Grab your API Key

You need an API key so you can interact with our API, in a bit.

To create an API key:

  1. Navigate to API Keys section and
  2. Click Create an API Key button
  3. Copy your API key so you can reference it later.

Creating a token

There's two ways to authenticate to place a call you can either use credentials or a token. In this example, we're going to use a token.

To authenticate with using a token we need to create an on demand credential, first.

Create an on demand credential

Notes:

  • An on demand credential a bit different than the credentials for the SIP connection we created above because they can expire.
  • An on demand credential belongs to a SIP connection so they inherit any changes made to the SIP connection that owns them.
  • This makes sharing/managing user access to a SIP connection very easy.

To create an on demand credential we need to grab the connection id of the SIP connection we created earlier.

You should have it written down somewhere if not you can retreive it by:

  1. In the portal click SIP connections
  2. Click the SIP connection is created earlier
  3. Copy the Connection ID

Now, let's use the API to execute the follow command.

Request

curl -X POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"connection_id": "<your connection ID>"
}' \
https://api.telnyx.com/v2/telephony_credentials

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

Example Response

{
"data": {
"id": "68f28076-119e-440d-bb69-9a8d359857c2",
"name": "2020-08-05 13:42:22.991499Z",
"record_type": "credential",
"resource_id": "connection:1431843891430033126",
"sip_password": "570067b6e4d7495db417e150a81380d9",
"sip_username": "gencredbcXbCt2uEOaD6e2VN2Bs3b2HDlQVW2v3CJFTQ6Xes9",
"created_at": "2020-08-05T13:42:22.992Z",
"expires_at": null,
"updated_at": "2020-08-05T13:42:22.992Z",
"user_id": "14c31d6d-aa05-4598-bef8-5acd2197f0c1"
}
}

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

Notes:

  • By default, on demand credentials will not expire. You can set an expiration date by using the API
  • The randomly generated sip_username can be used to receive SIP calls using <sip_username>@sip.telnyx.com as the destination

Create a token

Using a token to authenicate is important for security reasons so you don't pass credentials in plain text. Token's by default expire in 24hrs.

You'll need the credential_id from the previous step.

Run this command:

curl -X POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{}' \
https://api.telnyx.com/v2/telephony_credentials/<credential_id>/token

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

Example Response

# nosemgrep: generic.secrets.security.detected-jwt-token.detected-jwt-token
eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZWxueXhfdGVsZXBob255IiwiZXhwIjoxNTk2NzIxMzg1LCJpYXQiOjE1OTY2MzQ5ODUsImlzcyI6InRlbG55eF90ZWxlcGhvbnkiLCJqdGkiOiJkYmNkZTkzNi04NjdmLTRjMzctYWI1ZS00MGYzY2Q3ODJjZGEiLCJuYmYiOjE1OTY2MzQ5ODQsInN1YiI6IjY4ZjI4MDc2LTExOWUtNDQwZC1iYjY5LTlhOGQzNTk4NTdjMiIsInRlbF90b2tlbiI6IlN4N0tPQU9DblcxUGxIcXVxSEdMT29mTVRiRHJtM1pJM3Bnb1dXX0hkNHNMbmVQUHZXZXh2WXpVQWFLY2pxQ0d2amhfbTQ0S3MwMXFpaEpOMXVMOG95d2Rxdm13ZUExTzZjRlR2UF9jT0J3Skp3bjdZYmJYV3diYW9RR3VabzFNazJIS2dVYjlxQndTVDJxSUZ6dzkwa29CIiwidHlwIjoiYWNjZXNzIn0.ogJujxfbCktNxZ5eeyslLzZylswNqZW4OwLKrkehlb6w-tpbgJ-Ywfgy4Eirmi_BaZ_ThPlgTua0G1jafqFGRw

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

Notes:

  • The response is a JWT (JSON Web Token) that expires in 24h
  • The token is associated with the on demand credential, and is rendered invalid if the credential expires or is deleted

Let's make a test call

We built a demo app using the Voice SDK for Javascript in order to showcase the power of the SDK.

Connect to our servers

With the token we've generated in the previous step we can authenticate and provide the Caller ID Name, Caller ID Number,and Client State fields.

Now, click Connect.

You should see a log message indicating that the client has 'registered`. You can now place a call to any number available in your Outbound Voice Profile, or to a SIP destination.

webrtc_client_w_clientstate

How does the Client State field work?:

  • The Client state field that is sent to any backend application where a webhook is configured to POST to.
  • To configure webhooks go to: Connections > Basic Options > Events > Webhook URL
  • It is base64 encoded in our demo application

Open the demo in another browser tab

Create a new on demand credential and token from the steps above, this will represent the user you are trying to call.

Authenicate using the newly created token

  1. Choose token authenication
  2. Click Connect
  3. You should see a registered message in the wsMessages window, like above.

Make a call

  1. Input the sip desination of the newly created credential which should look like this: gencreda08xijXyfuNIKbIpANEClYCl3E2avcn5l3PXAW****@sip.telnyx.com
  2. Click Call
  3. You should receive an incoming call in the second browser tab

Next Steps

Check out Telnyx WebRTC SDKs, available for both Javascript and React:

On this page