Get Started

The twilio.js Library: Twilio.Connection

A Twilio.Connection object represents a call to or from Twilio. You never instantiate it directly, but it's passed to event handlers and returned when you call Twilio.Device.connect().

// Explicitly create a new outgoing connection
var connection = Twilio.Device.connect();

// or handle an incoming connection event
Twilio.Device.incoming(function(conn) {
  // conn is a Twilio.Connection object
});

Method Reference

The following is a list of methods available on a Twilio.Connection object. The .accept() and .disconnect() methods behave similarly to jQuery's click method. When passed a function, these methods register that function as a handler to be called when an event occurs. Calling the method without passing a function triggers that event handler.

.accept( [audioConstraints] )

Accepts an incoming connection.

This will begin establishing the media session to this device. The connection status will be set to connecting while the media session for the call is setup. The connection status will change to open once the media session is established.

Twilio.Device.incoming(function(conn) {
  conn.accept();
});

You can optionally specify an audioConstraints object to change the behavior of the local media stream during this call. You can use this to select a specific microphone, or turn off features like auto-gain control. Each web browser implements a different set of MediaTrackConstraints which may be used as audioConstraints, so consult your browser's implementation of getUserMedia for further details.

var audioConstraints = {
  optional: [{ sourceId: 'XXX' }]
};

Twilio.Device.incoming(function(conn) {
  conn.accept(audioConstraints);
});

.accept( handler(connection) )

Register a handler function to be called when this connection object has finished connecting and changes its state to open.

The handler function receives the Twilio.Connection object as its sole argument.

.reject()

Reject a pending connection. This will cause a hangup to be issued from the client session to the dialing party. If multiple client sessions are active the pending connection will be rejected for all of them.

.ignore()

Ignore a pending connection. This will stop the Client device from playing the incoming sound and set the connection state to closed, but will not send a hangup message to the dialing party. The incoming call will keep ringing until another Client with the same name answers the call, or the call times out.

.disconnect( handler(connection) )

Register a handler function to be called when this connection is closed.

The handler function receives the Twilio.Connection object as its sole argument.

var connection = Twilio.Device.connect();

connection.disconnect(function(conn) {
  console.log("the call has ended");
});

.disconnect()

Close this connection.

.error( handler(error) )

Register a handler function to be called when any device error occurs during the lifetime of this connection. These may be errors in your request, your capability token, connection errors, or other application errors. See the Twilio Client error code reference for more information. Using the error handler is a great way to debug your application and help catch mistakes in your code!

The handler function receives an error object as an argument. The error object may include the following properties:

Property Description
message A string describing the error.
code A numeric error code described in the Twilio Client error code reference.
info A copy of the Flash info object produced by the events around the flash.net.NetConnection object.
connection A reference to the Twilio.Connection object that was active when the error occurred.

.mute(bool)

Mutes or unmutes the current connection based on the boolean parameter you provide. true mutes the connection by ending audio gathered from the user's microphone, false unmutes the connection.

.mute( handler(boolean, connection) )

Register a handler function to be called when a connection is muted or unmuted.

The handler function receives a boolean indicating whether the connection is now muted (true) or not (false), and the Twilio.Connection object that was muted or unmuted.

.isMuted()

Returns a boolean indicating whether the connection is muted.

.sendDigits( digits )

Play DTMF tones. The digits parameter is a string and can contain the characters 0-9, #, and *. If you're familiar with TwiML, you can think of the sendDigits method as the sendDigits attribute in the <Number> noun.

.status()

Return the status of this connection. The status will be one of the following strings:

Status value Description
"pending" The connection is incoming and hasn't yet been established.
"connecting" The connection is transitioning to open status.
"open" The connection has been established.
"closed" The connection has been disconnected.

Property Reference

.parameters

.parameters contains details about the call, such as who is calling and what was dialed. The meaning of these parameters matches those in the Twilio Voice request parameters.

Incoming .parameters

On incoming connections, the following parameters are included:

Parameter Description
CallSid A unique identifier for this call, generated by Twilio.
AccountSid Your Twilio account ID. It is 34 characters long, and always starts with the letters AC.
From The phone number or client identifier of the party that initiated the call. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 (E.164 format). Client identifiers begin with the client: URI scheme; for example, for a call from a client named 'tommy', the From parameter will be client:tommy.
To The phone number or client identifier of the called party. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 ( E.164 format). Client identifiers begin with the client: URI scheme; for example, for a call to a client named 'jenny', the To parameter will be client:jenny.
ApiVersion The version of the Twilio API used to handle this call. For incoming calls, this is determined by the API version set on the called number. For outgoing calls, this is the API version used by the outgoing call's REST API request.
Outgoing .parameters

On outgoing connections, the following parameters are included:

Parameter Description
CallSid A unique identifier for this call, generated by Twilio.

Deprecated Methods

The following methods have been deprecated and will be removed in a future release of twilio.js. Calling these methods will generate a deprecation warning unless the warnings parameter is set to false when calling Twilio.Device.setup().

.mute()

Stop capturing audio from the microphone for this connection. This method has been replaced by .mute(bool).

.unmute()

Resume capturing audio from the microphone for this connection. This method has been replaced by .mute(bool).