Working with Twilio calls

Overview

The following operations are available for working with calls, recordings and transcriptions. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with calls , recording  and transcription, see Sample configuration.

Operation details

This section provides further details on the operations related to calls.

get a call 

<twilioRest.getNewCall>
    <to>{$ctx:to}</to>
    <from>{$ctx:from}</from>
    <url>{$ctx:url}</url>
    <method>{$ctx:method}</method>
    <fallbackUrl>{$ctx:fallbackUrl}</fallbackUrl>
    <fallbackMethod>{$ctx:fallbackMethod}</fallbackMethod>
    <statusCallback>{$ctx:statusCallback}</statusCallback>
    <statusCallbackMethod>{$ctx:statusCallbackMethod}</statusCallbackMethod>
    <sendDigits>{$ctx:sendDigits}</sendDigits>
    <ifMachine>{$ctx:ifMachine}</ifMachine>
    <timeout>{$ctx:timeout}</timeout>
    <record>{$ctx:record}</record>
</twilioRest.getNewCall>

To make a call, use twilioRest.getNewCall and specify the following properties. For more information on formatting phone numbers, see http://www.twilio.com/docs/api/rest/making-calls#post-parameters-required.

Properties

• to: The phone number, SIP address, or client identifier to call. For more information on SIP, see http://www.twilio.com/docs/sip.
• from: The phone number or client identifier to use as the caller ID. If using a phone number, it must be a Twilio number or a verified outgoing caller ID for your account.
• applicationSid: The 34-character string that uniquely identifies the application that defines the properties to use for making the call. If you use this property, the following voice properties will be ignored, because they are already defined by the application: url, method, fallbackUrl, fallbackMethod, statusCallback, and statusCallbackMethod.
• url: The fully qualified URL that should be consulted when the call connects. This property is ignored if you specify an applicationSid.
• method: Optional. The HTTP method, GET or POST, to use when connecting to the URL. Defaults to POST. This property is ignored if you specify an applicationSid.
• fallbackUrl: Optional. A URL that Twilio will request if an error occurs when requests are made to the URL.This property is ignored if you specify an applicationSid.
• fallbackMethod: Optional. The HTTP method, either GET or POST, that should be used to request the fallback URL. Defaults to POST. This property is ignored if you specify an applicationSid.
• statusCallback: Optional. The URL that Twilio will request when the call ends to notify your application. This property is ignored if you specify an applicationSid.
• statusCallbackMethod: Optional. The HTTP method, either GET or POST, that should be used to request the status callback URL. Defaults to POST. This property is ignored if you specify an applicationSid.

• sendDigits: Optional. A string of keys to dial after connecting to the number. Valid digits in the string include: any digit (0-9), %23 (the URL-encoded version of #), *, and w (to insert a half-second pause). For example, if you are connecting to a company phone number and want to pause for one second, dial extension 1234, and then the pound key, use <sendDigits>ww1234%23</sendDigits>. 

• ifMachine: Optional. Specifies whether Twilio should try to determine whether a machine (like voicemail) or a human has answered the call. Possible values are Continue and Hangup. For more information, see http://www.twilio.com/docs/api/rest/making-calls#handling-outcomes-answering-machines.
• timeout: Optional. The integer number of seconds that Twilio should allow the phone to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail.
• record: Optional. Specifies whether to record the call. If true, the entire call is recorded, and the recording URL is sent to the status callback URL. Defaults to false.

Sample request

Following is a sample REST/JSON request that can be handled by the getNewCall operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"to":"+447891063180",
	"from":"+442033229574",
	"url":"http://demo.twilio.com/docs/voice.xml",
	"method":"POST",
	"fallbackUrl":"http://demo.twilio.com/docs/voicefallback.xml",
	"fallbackMethod":"POST",
	"statusCallback":"http://demo.twilio.com/docs/statuscallback.xml",
	"statusCallbackMethod":"GET",
	"sendDigits":"1234",
	"ifMachine":"Continue",
	"timeout":"60",
	"record":"false"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/making-calls

Getting a list of calls 

<twilioRest.getCallList>
    <to>{$ctx:to}</to>
    <from>{$ctx:from}</from>
    <status>{$ctx:status}</status>
    <startTime>{$ctx:startTime}</startTime>
    <parentCallSid>{$ctx:parentCallSid}</parentCallSid>
</twilioRest.getCallList>

To get a list of calls, use twilioRest.getCallList and specify the following properties.

Properties

• to: Optional. Only get calls made to this phone number, SIP address, or client identifier.

• from: Optional. Only get calls made from this phone number or client identifier.

• status: Optional. Only get calls currently in this status. May be queued, ringing, in-progress, canceled, completed, failed, busy, or no-answer.

• startTime: Optional. Only get calls that started on this date, given as YYYY-MM-DD. Also supports inequalities, such as <=YYYY-MM-DD for calls that started at or before midnight on a date, and >=YYYY-MM-DD for calls that started at or after midnight on a date.

• parentCallSid: Optional. Only get calls spawned by the call with this SID.

Related Twilio documentation

http://www.twilio.com/docs/api/rest/call

Sample request

Following is a sample REST/JSON request that can be handled by the getCallList operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"to":"+447891063180",
	"from":"+442033229574",
	"status":"completed",
	"startTime":"2015-08-20",
	"parentCallSid":""

}

Getting a specific call 

<twilioRest.getCall>
    <callSid>{$ctx:callSid}</callSid>
</twilioRest.getCall>

To get information about a specific call, including start time, end time, and more, use twilioRest.getCall and specify the following properties.

Properties

• callSid: The identifier of the call you want to get.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"callSid":"CA921a9ca8c5bee58cc54a11ba5988dc01"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/call

Modifying a live call 

<twilioRest.modifyLiveCall>
    <callSid>{$ctx:callSid}</callSid>
    <url>{$ctx:url}</url>
    <method>{$ctx:method}</method>
    <status>{$ctx:status}</status>
    <fallbackUrl>{$ctx:fallbackUrl}</fallbackUrl>
    <fallbackMethod>{$ctx:fallbackMethod}</fallbackMethod>
    <statusCallback>{$ctx:statusCallback}</statusCallback>
    <statusCallbackMethod>{$ctx:statusCallbackMethod}</statusCallbackMethod>
</twilioRest.modifyLiveCall>

To interrupt an in-progress call and terminate it or process it using a new URL, use twilioRest.modifyLiveCall and specify the following properties.

Properties

• callSid: The identifier of the call you want to modify.

• url: The fully qualified URL where the call should be redirected.

• method: Optional. The HTTP method, GET or POST, to use when connecting to the URL. Defaults to POST.

• status: Optional. Either canceled or completed. Specifying canceled will attempt to hang up calls that are queued or ringing but not affect calls already in progress. Specifying completed will attempt to hang up a call even if it's already in progress.

• fallbackUrl: Optional. A URL that Twilio will request if an error occurs when requests are made to the URL.

• fallbackMethod: Optional. The HTTP method, either GET or POST, that should be used to request the fallback URL. Defaults to POST.

• statusCallback: Optional. The URL that Twilio will request when the call ends to notify your application.

• statusCallbackMethod: Optional. The HTTP method, either GET or POST, that should be used to request the status callback URL. Defaults to POST.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"callSid":"CA921a9ca8c5bee58cc54a11ba5988dc01",
	"url":"http://demo.twilio.com/docs/voice.xml",
	"method":"POST",
	"status":"completed"
	"fallbackUrl":"http://demo.twilio.com/docs/voicefallback.xml",
	"fallbackMethod":"POST",
	"statusCallback":"http://demo.twilio.com/docs/statuscallback.xml",
	"statusCallbackMethod":"GET"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/change-call-state

Getting a list of recordings 

<twilioRest.getRecordingList>
    <callSid>{$ctx:callSid}</callSid>
    <dateCreated>{$ctx:dateCreated}</dateCreated>
</twilioRest.getRecordingList>

To get a list of recordings, use twilioRest.getRecordingList and specify the following properties.

Properties

• callSid: Optional. Only get recordings made during the call given by this SID.

• dateCreated: Optional. Only get recordings created on this date, given as YYYY-MM-DD. Also supports inequalities, such as <=YYYY-MM-DD for recordings generated at or before midnight on a date, and >=YYYY-MM-DD for recordings generated at or after midnight on a date.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"callSid":"CA921a9ca8c5bee58cc54a11ba5988dc01",
	"dateCreated":"2015-08-26"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/recording#list

Getting a specific recording 

<twilioRest.getRecording>
    <recordingSid>{$ctx:recordingSid}</recordingSid>
</twilioRest.getRecording>

To get information about a specific recording, including date created, duration, and more, use twilioRest.getRecording and specify the following properties.

Properties

• recordingSid: The identifier of the recording you want to get.

Sample request

Following is a sample REST/JSON request that can be handled by the getRecording operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"recordingSid":"RE557ce644e5ab84fa21cc21112e22c485"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/recording

Deleting a recording 

<twilioRest.deleteRecording>
    <recordingSid>{$ctx:recordingSid}</recordingSid>
</twilioRest.deleteRecording>

To delete a specific recording, use twilioRest.deleteRecording and specify the following properties. Once the recording is deleted, you will no longer be billed for those minutes. If successful, returns HTTP 204 (No Content) with no body.

Properties

• recordingSid: The identifier of the recording you want to delete.

Sample request

Following is a sample REST/JSON request that can be handled by the deleteRecording operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"recordingSid":"RE557ce644e5ab84fa21cc21112e22c485"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/recording

Getting a list of transcriptions 

<twilioRest.getTranscriptionList/>

To get a list of transcriptions generated from your account, including information such as status and paging information for each transcription, use twilioRest.getTranscriptionList.

Sample request

Following is a sample REST/JSON request that can be handled by the getTranscriptionList operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/transcription#list

Getting a specific transcription 

<twilioRest.getTranscription>
    <transcriptionSid>{$ctx:transcriptionSid}</transcriptionSid>
</twilioRest.getTranscription>

To get information about a specific transcription, including date created, status, and more, use twilioRest.getTranscription and specify the following properties.

Properties

• transcriptionSid: The identifier of the transcription you want to get.

Sample request

Following is a sample REST/JSON request that can be handled by the getTranscription operation.

{
	"accountSid":"AC3c4055d0dd73aab7b5b1b26c0794e9c6",
	"authToken":"cdd1fdb143d482a05e4f1f6fdb195395",
	"apiUrl":"https://api.twilio.com",
	"apiVersion":"2010-04-01",
	"transcriptionSid":"RE557ce644e5ab84fa21cc21112e22c485"
}

Related Twilio documentation

http://www.twilio.com/docs/api/rest/transcription

Sample configuration

Following is a sample proxy service that illustrates how to connect to TwilioRest with the init operation and use the getCall operation. The sample request for this proxy can be found in getCall sample request. You can use this sample as a template for using other operations in this category.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="twilioRest"
       transports="https,http" statistics="disable" trace="disable"
       startOnLoad="true">
    <target>
        <inSequence onError="faultHandlerSeq">
            <property name="accountSid" expression="//accountSid/text()"/>
            <property name="authToken" expression="//authToken/text()"/>
            <property name="apiUrl" expression="//apiUrl/text()"/>
            <property name="apiVersion" expression="//apiVersion/text()"/>
            <property name="callSid" expression="//callSid/text()"/>      
            <twilioRest.init>
                <accountSid>{$ctx:accountSid}</accountSid>
                <authToken>{$ctx:authToken}</authToken>
                <apiUrl>{$ctx:apiUrl}</apiUrl>
                <apiVersion>{$ctx:apiVersion}</apiVersion>
            </twilioRest.init>
            <twilioRest.getCall>
                <callSid>{$ctx:callSid}</callSid>
            </twilioRest.getCall>          
            <respond/>
        </inSequence>
        <outSequence>
            <log/>
            <send/>
        </outSequence>
    </target>
    <description/>
</proxy>