Twilio Network Traversal Service

Twilio’s Network Traversal Service is a globally distributed STUN/TURN service that helps you deploy more reliable peer-to-peer communications applications. You can use this service in your WebRTC and VoIP applications for traversal and relay around NAT/firewalls, so that your users make a successful connection every time.

If you're new to STUN/TURN and ICE, check out the Frequently Asked Questions. If you want to start using Twilio's Network Traversal Service immediately, here's what you need to do.

Using Network Traversal Service in a WebRTC application

Using Network Traversal Service in a WebRTC application is as easy as requesting a token and passing it to your RTCPeerConnection constructor.

First, make a request from your web server to retrieve a Network Traversal Service Token and pass it to your WebRTC application.

Important: You'll need to use your Twilio AccountSid and AuthToken to get a Network Traversal Service Token. You should only make this request from your server and not the client browser to keep your Twilio account credentials safe.
Generate NTS Token
  • C#
  • curl
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
SDK Version:
  • 4.x
  • 5.x
Response Format:
  • json
  • xml
SDK Version:
  • 6.x
  • 7.x
SDK Version:
  • 2.x
  • 3.x
SDK Version:
  • 4.x
  • 5.x
SDK Version:
  • 5.x
  • 6.x
SDK Version:
  • 4.x
  • 5.x
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var token = twilio.CreateToken();
    
    Console.WriteLine(token.Username);
  }
}
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$authToken = "your_auth_token";
$client = new Services_Twilio($sid, $authToken);

$token = $client->account->tokens->create();
echo $token->username;
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

token = @client.account.tokens.create()
puts token.username
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tokens \
    -u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Token;

public class Example {
  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACCOUNT_SID";
  public static final String AUTH_TOKEN = "AUTH_TOKEN";

  public static void main(String[] args) {
    // Initialize the client
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Token token = Token.creator().create();

    System.out.println(token.getUsername());
  }
}
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account;

public class Example
{
    public static void Main(string[] args)
    {
        // Find your Account SID and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";

        TwilioClient.Init(accountSid, authToken);

        var token = TokenResource.Create();

        Console.WriteLine(token.Username);
    }
}
<?php
// NOTE: This example uses the next generation Twilio helper library - for more
// information on how to download and install this version, visit
// https://www.twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';

use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";

// Initialize the client
$client = new Client($sid, $token);

//Creates a token
$token = $client->tokens->create();

echo $token->username;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

token = client.tokens.create()
print(token.username)
# Download the Ruby helper library from twilio.com/docs/libraries/ruby
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new(account_sid, auth_token)

token = @client.account.tokens.create

puts token.username
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.TokenFactory;
import com.twilio.sdk.resource.instance.Token;
import com.twilio.sdk.resource.list.TokenList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    TokenFactory tokenFactory = client.getAccount().getTokenFactory();
    Token token = tokenFactory.create();
    System.out.println(token.getUsername());
  }
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import Client

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

token = client.tokens.create()
print(token.username)
// Download the Node helper library from twilio.com/docs/node/install
// These are your accountSid and authToken from https://www.twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

const client = require('twilio')(accountSid, authToken);

client.api.accounts('ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa').tokens
  .create({})
  .then((token) => console.log(token.username));
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.tokens.create({}, function(err, token) {
    process.stdout.write(token.username);
});
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tokens.json \
    -u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"
Show Output
  • JSON
  • XML
{
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "date_created": "Mon, 17 Nov 2014 23:55:19 +0000",
    "date_updated": "Mon, 17 Nov 2014 23:55:19 +0000",
    "ice_servers": [
        {
            "url": "stun:global.stun.twilio.com:3478?transport=udp"
        },
        {
            "credential": "M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=",
            "url": "turn:global.turn.twilio.com:3478?transport=udp",
            "username": "b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f"
        }
    ],
    "password": "M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=",
    "registrars": null,
    "ttl": "86400",
    "username": "b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f"
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
  <Token>
    <Username>b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f</Username>
    <Password>M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=</Password>
    <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
    <Ttl>86400</Ttl>
    <IceServers>
      <IceServer>
        <Url>stun:global.stun.twilio.com:3478?transport=udp</Url>
      </IceServer>
      <IceServer>
        <Url>turn:global.turn.twilio.com:3478?transport=udp</Url>
        <Username>b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f</Username>
        <Credential>M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=</Credential>
      </IceServer>
    </IceServers>
    <Registrars/>
    <DateCreated>Mon, 17 Nov 2014 23:42:45 +0000</DateCreated>
    <DateUpdated>Mon, 17 Nov 2014 23:42:45 +0000</DateUpdated>
  </Token>
</TwilioResponse>
Generate NTS Token

Next, include the "ice_servers" property in the RTCConfiguration object you pass to the RTCPeerConnection constructor when setting up a call, as shown below (where ICE_SERVERS is the contents of the "ice_servers" property returned in the response above):

// Here's an example in javascript
myIceServers = ICE_SERVERS;
var configuration = { iceServers: myIceServers };
var pc = new RTCPeerConnection(configuration);

From this point forward, exchange SDP offer/answers as you normally would. Congrats, you've now used Network Traversal Service to setup a connection!

If the browser you're using supports Trickle ICE, you'll also want to handle the RTCPeerConnection's onIceCandidate event to pass any new ICE candidates to the connected peer:

// Here's an example in javascript
pc.onicecandidate = function (evt) {
  if (evt.candidate) {
    // send the candidate to the other party via your signaling channel
  }
};

That's all there is to it! If you need more help, check out the Frequently Asked Questions, or contact Twilio support at help@twilio.com.

Using Network Traversal Service in a VoIP client

Important: In order to use Network Traversal Service in a VoIP client, you'll need to be able to make an HTTP request from your VoIP client or another application at least once every 24 hours to retrieve a new ephemeral token.

To use Network Traversal Service with a VoIP Client you'll do the following:

  1. Retrieve a Network Traversal Service Token.
  2. Retrieve the STUN and TURN URLs from the returned data, along with the username and credential values.
  3. Configure your VoIP client with these values.

Network Traversal Service Tokens are good for a maximum and default value of one day. You can reduce the token expiration time by using the Ttl parameter when you request the token. Find out more in the Network Traversal Service Token documentation here.

1 / 1
Loading Code Samples...
SDK Version:
  • 4.x
  • 5.x
Response Format:
  • json
  • xml
SDK Version:
  • 6.x
  • 7.x
SDK Version:
  • 2.x
  • 3.x
SDK Version:
  • 4.x
  • 5.x
SDK Version:
  • 5.x
  • 6.x
SDK Version:
  • 4.x
  • 5.x
Format:
  • JSON
  • XML
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var token = twilio.CreateToken();
    
    Console.WriteLine(token.Username);
  }
}
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$authToken = "your_auth_token";
$client = new Services_Twilio($sid, $authToken);

$token = $client->account->tokens->create();
echo $token->username;
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

token = @client.account.tokens.create()
puts token.username
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tokens \
    -u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Token;

public class Example {
  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACCOUNT_SID";
  public static final String AUTH_TOKEN = "AUTH_TOKEN";

  public static void main(String[] args) {
    // Initialize the client
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Token token = Token.creator().create();

    System.out.println(token.getUsername());
  }
}
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account;

public class Example
{
    public static void Main(string[] args)
    {
        // Find your Account SID and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";

        TwilioClient.Init(accountSid, authToken);

        var token = TokenResource.Create();

        Console.WriteLine(token.Username);
    }
}
<?php
// NOTE: This example uses the next generation Twilio helper library - for more
// information on how to download and install this version, visit
// https://www.twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php';

use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";

// Initialize the client
$client = new Client($sid, $token);

//Creates a token
$token = $client->tokens->create();

echo $token->username;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

token = client.tokens.create()
print(token.username)
# Download the Ruby helper library from twilio.com/docs/libraries/ruby
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new(account_sid, auth_token)

token = @client.account.tokens.create

puts token.username
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.TokenFactory;
import com.twilio.sdk.resource.instance.Token;
import com.twilio.sdk.resource.list.TokenList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    TokenFactory tokenFactory = client.getAccount().getTokenFactory();
    Token token = tokenFactory.create();
    System.out.println(token.getUsername());
  }
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import Client

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
client = Client(account_sid, auth_token)

token = client.tokens.create()
print(token.username)
// Download the Node helper library from twilio.com/docs/node/install
// These are your accountSid and authToken from https://www.twilio.com/console
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

const client = require('twilio')(accountSid, authToken);

client.api.accounts('ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa').tokens
  .create({})
  .then((token) => console.log(token.username));
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.tokens.create({}, function(err, token) {
    process.stdout.write(token.username);
});
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Tokens.json \
    -u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"
{
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "date_created": "Mon, 17 Nov 2014 23:55:19 +0000",
    "date_updated": "Mon, 17 Nov 2014 23:55:19 +0000",
    "ice_servers": [
        {
            "url": "stun:global.stun.twilio.com:3478?transport=udp"
        },
        {
            "credential": "M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=",
            "url": "turn:global.turn.twilio.com:3478?transport=udp",
            "username": "b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f"
        }
    ],
    "password": "M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=",
    "registrars": null,
    "ttl": "86400",
    "username": "b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f"
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
  <Token>
    <Username>b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f</Username>
    <Password>M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=</Password>
    <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
    <Ttl>86400</Ttl>
    <IceServers>
      <IceServer>
        <Url>stun:global.stun.twilio.com:3478?transport=udp</Url>
      </IceServer>
      <IceServer>
        <Url>turn:global.turn.twilio.com:3478?transport=udp</Url>
        <Username>b759d275ddc641cd379f329882abe3c0618c8afdfc5e24be1b4d59482244240f</Username>
        <Credential>M87Dd74GbNfyrAydvEKiDR43go52fo6ldoJBHB6gim0=</Credential>
      </IceServer>
    </IceServers>
    <Registrars/>
    <DateCreated>Mon, 17 Nov 2014 23:42:45 +0000</DateCreated>
    <DateUpdated>Mon, 17 Nov 2014 23:42:45 +0000</DateUpdated>
  </Token>
</TwilioResponse>