Summary: Configuration | Message Processors
org.mule.modules

mule-module-twilio

1.1
Namespacehttp://www.mulesoft.org/schema/mule/twilio
Schema Locationhttp://www.mulesoft.org/schema/mule/twilio/1.0/mule-twilio.xsd
Version1.0
Minimum Mule Version3.2

Module Overview

You can use your master Twilio Account credentials (AccountSid and AuthToken) to access Twilio's REST API for your master account as well as any of your subaccounts. You may also use a subaccount's AccountSid and AuthToken to access the resources of that subaccount. You can not use a subaccount's credentials to access the resources of your master Twilio account or any other subaccounts.

Summary

Configuration
<twilio:config>
Configure an instance of this module
Message Processors
<twilio:add-incoming-phone-number-by-area-code>
Adds a new phone number to your account.
<twilio:add-incoming-phone-number-by-phone-number>
Adds a new phone number to your account.
<twilio:add-new-caller-id>
Adds a new CallerID to your account.
<twilio:change-call-state>
Modify the state of a live call.
<twilio:create-application>
Creates a new application within your account.
<twilio:create-sub-account>
Creates a new subaccount.
<twilio:delete-application>
Delete this application.
<twilio:delete-incoming-phone-number>
Release this phone number from your account.
<twilio:delete-notification>
Deletes the notification identified by {NotificationSid} from an account's log.
<twilio:delete-outgoing-caller-id>
Deletes the caller ID from the account.
<twilio:delete-participant>
Kick this participant from the conference.
<twilio:delete-recording>
Deletes a recording from your account.
<twilio:exchange-phone-numbers-between-subaccounts>
Trasfers a number between two subaccounts.
<twilio:get-account-details>
Returns a representation of an account.
<twilio:get-all-accounts-details>
Retrieve a list of the Account resources belonging to the account used to make the API request.
<twilio:get-all-applications>
Returns a list of Application resource representations, each representing an application within your account.
<twilio:get-all-notifications>
Returns a list of notifications generated for an account.
<twilio:get-all-outgoing-caller-ids>
Returns a list of OutgoingCallerId resource representations, each representing a Caller ID number valid for an account.
<twilio:get-all-sms-messages>
Returns a list of SMS messages associated with your account.
<twilio:get-application>
Returns an application resource matching the given application sid.
<twilio:get-available-phone-numbers>
Returns a list of local AvailablePhoneNumber resource representations that match the specified filters, each representing a phone number that is currently available for provisioning within your account.
<twilio:get-available-phone-numbers-advanced-seach>
Returns a list of local AvailablePhoneNumber resource representations that match the specified filters, each representing a phone number that is currently available for provisioning within your account.
<twilio:get-available-toll-free-numbers>
Returns a list of toll-free AvailablePhoneNumber elements that match the specified filters, each representing a phone number that is currently available for provisioning within your account.
<twilio:get-call>
Returns the single Call resource identified by the given call sid.
<twilio:get-calls>
Returns a list of phone calls made to and from the account identified by the given account sid.
<twilio:get-conference>
Returns a representation of the conference identified by the given conference id.
<twilio:get-conferences>
Returns a list of conferences within an account.
<twilio:get-incoming-phone-numbers>
Returns a list of IncomingPhoneNumber resource representations, each representing a phone number given to your account.
<twilio:get-incoming-phone-numbers-by-incoming-phone-number-sid>
Returns an incoming phone numbers matching the given query filters.
<twilio:get-notification>
Return a notificaction resource for the given notification sid.
<twilio:get-notifications-by-call-sid>
Returns a list of notifications generated for an account.
<twilio:get-outgoing-caller-id-by-outgoing-caller-id-sid>
Returns an outgoing caller id instance matching the given filters.
<twilio:get-participant>
Returns a representation of this participant.
<twilio:get-participants>
Returns the list of participants in the conference identified by the given conference sid.
<twilio:get-recording>
Returns one of several representations depending on the given recording type.
<twilio:get-recordings>
Returns a list of Recording resource representations, each representing a recording generated during the course of a phone call.
<twilio:get-sandbox>
Returns the Sandbox resource associated with the account identified by {YourAccountSid}.
<twilio:get-sms-message>
Returns a single SMS message specified by the provided SMS message sid.
<twilio:get-sub-account-by-account-sid>
Subaccounts in Twilio are just accounts that are "owned" by another account.
<twilio:get-sub-account-by-friendly-name>
Subaccounts in Twilio are just accounts that are "owned" by another account.
<twilio:get-transcription-by-transcription-sid>
Returns a single Transcription resource representation identified by the given transcription sid.
<twilio:get-transcriptions>
Returns a set of Transcription resource representations that includes paging information, sorted by 'DateUpdated', with most recent transcripts first.
<twilio:make-call>
Initiates a call using the given paramaters.
<twilio:send-sms-message>
Send an outgoing SMS message.
<twilio:update-account>
Allows you to modify the properties of an account.
<twilio:update-application>
Tries to update the application's properties, and returns the updated resource representation if successful.
<twilio:update-incoming-phone-numbers>
Tries to update the incoming phone number's properties, and returns the updated resource representation if successful.
<twilio:update-outgoing-caller-id-by-outgoing-caller-id-sid>
Updates the caller id, and returns the updated resource if successful.
<twilio:update-participant-status>
Updates the participant status.
<twilio:update-sandbox>
You can POST to the Sandbox resource to update the TwiML voice and SMS URLs associated with the sandbox number.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:twilio="http://www.mulesoft.org/schema/mule/twilio"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/twilio
               http://www.mulesoft.org/schema/mule/twilio/1.0/mule-twilio.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necesary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
TypeNameDefault ValueDescription
xs:string name Optional. Give a name to this configuration so it can be later referenced.
xs:string accountSid The account sid to be used to connect to Twilio.
xs:string authToken The authentication token to be used to connect to Twilio

Message Processors

<twilio:add-incoming-phone-number-by-area-code>

Adds a new phone number to your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452. If successful, Twilio responds with a representation of the new phone number that was assigned to your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
areaCode The area code in which you'd like a new incoming phone number. Any three digit, US area code is valid. Twilio will provision a random phone number within this area code for you.
friendlyName Optional. A human readable description of the new incoming phone number. Maximum 64 characters. Defaults to a formatted version of the number.
voiceUrl Optional. The URL that Twilio should request when somebody dials the new phone number.
voiceMethod Optional. The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.
voice-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML at Url.
status-callback-flow-ref Optional. A flow that Twilio will request to pass status parameters (such as call ended) to your application.
voiceCallerIdLookup Optional. Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. Defaults to false.
voiceApplicationSid Optional. The 34 character sid of the application Twilio should use to handle phone calls to the new number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to the phone number.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
sms-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
smsApplicationSid Optional. The 34 character sid of the application Twilio should use to handle SMSs sent to the new number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, Twilio responds with a representation of the new phone number that was assigned to your account.

<twilio:add-incoming-phone-number-by-phone-number>

Adds a new phone number to your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452. If successful, Twilio responds with a representation of the new phone number that was assigned to your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
phoneNumber The phone number you want to purchase. The number should be formated starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'.
friendlyName Optional. A human readable description of the new incoming phone number. Maximum 64 characters. Defaults to a formatted version of the number.
voiceUrl Optional. The URL that Twilio should request when somebody dials the new phone number.
voiceMethod Optional. The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.
voice-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML at Url.
status-callback-flow-ref Optional. A flow that Twilio will request to pass status parameters (such as call ended) to your application.
voiceCallerIdLookup Optional. Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. Defaults to false.
voiceApplicationSid Optional. The 34 character sid of the application Twilio should use to handle phone calls to the new number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to the phone number.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
sms-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
smsApplicationSid Optional. The 34 character sid of the application Twilio should use to handle SMSs sent to the new number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, Twilio responds with a representation of the new phone number that was assigned to your account.

<twilio:add-new-caller-id>

Adds a new CallerID to your account. After making this request, Twilio will return to you a validation code and Twilio will dial the phone number given to perform validation. The code returned must be entered via the phone before the CallerID will be added to your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
phoneNumber The phone number to verify. Should be formatted with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212, 415-555-1212.
friendlyName Optional. A human readable description for the new caller ID with maximum length 64 characters. Defaults to a nicely formatted version of the number.
callDelay Optional. The number of seconds, between 0 and 60, to delay before initiating the validation call. Defaults to 0.
extension Optional. Digits to dial after connecting the validation call.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a validation request (see validation request propertie)

<twilio:change-call-state>

Modify the state of a live call. Returns the call representation.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
callSid The call sid to modify
url Optional. A valid URL that returns TwiML. Twilio will immediately redirect the call to the new TwiML.
method Optional. The HTTP method Twilio should use when requesting the above URL. Defaults to POST.
status Optional. Either canceled or completed. Specifying canceled will attempt to hangup 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.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the call representation

<twilio:create-application>

Creates a new application within your account. If successful, Twilio responds with a representation of the new application.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
friendlyName A human readable description of the new application. Maximum 64 characters.
apiVersion Optional. Requests to this application's URLs will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01. Defaults to your account's default API version.
voiceUrl Optional. The URL that Twilio should request when somebody dials a phone number assigned to this application
voiceMethod Optional. The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.
voice-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML at Url.
status-callback-flow-ref Optional. A flow that Twilio will request to pass status parameters (such as call ended) to your application.
voiceCallerIdLookup Optional. Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. Defaults to false.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to a phone number assigned to this application.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
sms-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
sms-status-callback-flow-ref Optional. Twilio will make a POST request to this flow to pass status parameters (such as sent or failed) to your application if you specify this application's Sid as the ApplicationSid on an outgoing SMS request.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, Twilio responds with a representation of the new application.

<twilio:create-sub-account>

Creates a new subaccount.

Subaccounts in Twilio are just accounts that are "owned" by another account. Using a subaccount you can segment each of your customers' use of Twilio and keep it separate from all the rest, allowing you to easily manage the activity and resources of each customer independently.

For instance, if you are running a hosted service that relies on Twilio you can create a Twilio subaccount for each customer that signs up. Then if a customer closes his or her account with your service, you can simply deactivate the associated Twilio subaccount.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
friendlyName Optional. A human readable description of the new subaccount, up to 64 characters. Defaults to "SubAccount Created at {YYYY-MM-DD HH:MM meridiam}".
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the account

<twilio:delete-application>

Delete this application. If this application's sid is assigned to any IncomingPhoneNumber resources as a VoiceApplicationSid or SmsApplicationSid it will be removed.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
applicationSid The application sid to use
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If succesful, Twilio will return an HTTP 204 response with no body.

<twilio:delete-incoming-phone-number>

Release this phone number from your account. Twilio will no longer answer calls to this number, and you will stop being billed the monthly phone number fee. The phone number will eventually be recycled and potentially given to another customer, so use with care.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
incomingPhoneNumberSid The incoming phone number sid to delete
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • if succesful, returns an HTTP 204 response with no body.

<twilio:delete-notification>

Deletes the notification identified by {NotificationSid} from an account's log.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
notificationSid The notification sid to use
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, returns HTTP status 204 (No Content) with no body.

<twilio:delete-outgoing-caller-id>

Deletes the caller ID from the account. Returns an HTTP 204 response if successful, with no body.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
outgoingCallerIdSid The outgoing caller id sid to delete
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • an HTTP 204 response if successful, with no body.

<twilio:delete-participant>

Kick this participant from the conference. Returns HTTP 204 (No Content), with no body, if the participant was successfuly booted from the conference.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
conferenceSid The conference sid to use
callSid The call sid to use
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • Returns HTTP 204 (No Content), with no body, if the participant was successfuly booted from the conference.

<twilio:delete-recording>

Deletes a recording from your account. If successful, returns HTTP 204 (No Content) with no body.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
recordingSid The recording sid to use.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, returns HTTP 204 (No Content) with no body.

<twilio:exchange-phone-numbers-between-subaccounts>

Trasfers a number between two subaccounts.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSidFrom Optional. The account sid from where to get the number, leave empty to use
accountSid
incomingPhoneNumberSid The incoming phone number sid to transfer
accountSidTo The account sid where to transfer the phone number.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • an incoming phone number instance.

<twilio:get-account-details>

Returns a representation of an account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid for which to get the details, leave empty to use to use
accountSid
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the account

<twilio:get-all-accounts-details>

Retrieve a list of the Account resources belonging to the account used to make the API request. This list will include that Account as well.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountStatus Optional. Only return Account resources with the given status. Can be closed, suspended or active.
friendlyName Optional. Only return the Account resources with friendly names that exactly match this name.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of the Account resources belonging to the account used to make the API request. This list will include that Account as well.

<twilio:get-all-applications>

Returns a list of Application resource representations, each representing an application within your account. The list includes paging information.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
friendlyName Optional. Only return the Application resources with friendly names that exactly match this name.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of Application resource representations

<twilio:get-all-notifications>

Returns a list of notifications generated for an account. The list includes paging information and is sorted by DateUpdated, with most recent notifications first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
log Optional. An integer log level corresponding to the type of notification: 0 is ERROR, 1 is WARNING.
messageDate Optional. Only show notifications for this date. Should be formatted as YYYY-MM-DD. You can also specify inequality, such as MessageDate<=YYYY-MM-DD for messages logged at or before midnight on a date, and MessageDate>=YYYY-MM-DD for messages logged at or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of notifications generated for an account

<twilio:get-all-outgoing-caller-ids>

Returns a list of OutgoingCallerId resource representations, each representing a Caller ID number valid for an account. The list includes paging information.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
phoneNumber Optional. Only show the caller id resource that exactly matches this phone number.
friendlyName Optional. Only show the caller id resource that exactly matches this name.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of OutgoingCallerId resource representations

<twilio:get-all-sms-messages>

Returns a list of SMS messages associated with your account. The list includes paging information and is sorted by DateSent, with most recent messages first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
to Optional. Only show SMS messages to this phone number.
from Optional. Only show SMS messages from this phone number.
dateSent Optional. Only show SMS messages sent on this date, given as YYYY-MM-DD. Example: DateSent=2009-07-06. You can also specify inequality, such as DateSent<=YYYY-MM-DD for SMS messages that were sent on or before midnight on a date, and DateSent>=YYYY-MM-DD for SMS messages sent on or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of SMS messages associated with your account

<twilio:get-application>

Returns an application resource matching the given application sid.

An Application instance resource represents an application that you have created with Twilio. An application inside of Twilio is just a set of URLs and other configuration data that tells Twilio how to behave when one of your Twilio numbers receives a call or SMS message.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
applicationSid The application sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • an application resource matching the given application sid.

<twilio:get-available-phone-numbers>

Returns a list of local AvailablePhoneNumber resource representations that match the specified filters, each representing a phone number that is currently available for provisioning within your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
isoCountryCode A country code in ISO 3166-1 alpha-2 format (e.g. 'US' for United States, 'CA' for Canada).
areaCode Optional. Find phone numbers in the specified Area Code. Only available for North American numbers.
contains Optional. A pattern to match phone numbers on. Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit.
inRegion Optional. Limit results to a particular region (i.e. State/Province). Given a phone number, search within the same Region as that number.
inPostalCode Optional. Limit results to a particular postal code. Given a phone number, search within the same postal code as that number.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of local AvailablePhoneNumber resource representations that match the specified filters

<twilio:get-available-phone-numbers-advanced-seach>

Returns a list of local AvailablePhoneNumber resource representations that match the specified filters, each representing a phone number that is currently available for provisioning within your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
isoCountryCode A country code in ISO 3166-1 alpha-2 format (e.g. 'US' for United States, 'CA' for Canada).
areaCode Optional. Find phone numbers in the specified Area Code. Only available for North American numbers.
contains Optional. A pattern to match phone numbers on. Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit.
inRegion Optional. Limit results to a particular region (i.e. State/Province). Given a phone number, search within the same Region as that number.
inPostalCode Optional. Limit results to a particular postal code. Given a phone number, search within the same postal code as that number.
nearLatLong Optional. Given a latitude/longitude pair lat,long find geographically close numbers within Distance miles.
nearPhoneNumber Optional. Given a phone number, find a geographically close number within Distance miles. Distance defaults to 25 miles.
inLata Optional. Limit results to a specific Local access and transport area (LATA). Given a phone number, search within the same LATA as that number.
inRateCenter Optional. Limit results to a specific rate center, or given a phone number search within the same rate center as that number. Requires InLata to be set as well.
distance Optional. Specifies the search radius for a Near- query in miles. If not specified this defaults to 25 miles.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of local AvailablePhoneNumber resource representations that match the specified filters

<twilio:get-available-toll-free-numbers>

Returns a list of toll-free AvailablePhoneNumber elements that match the specified filters, each representing a phone number that is currently available for provisioning within your account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
isoCountryCode A country code in ISO 3166-1 alpha-2 format (e.g. 'US' for United States, 'CA' for Canada).
contains Optional. A pattern to match phone numbers on. Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of toll-free AvailablePhoneNumber elements that match the specified filters

<twilio:get-call>

Returns the single Call resource identified by the given call sid.

A Call instance resource represents a connection between a telephone and Twilio. This may be inbound, when a person calls your application, or outbound, when your application initiates the call, either via the REST API (see Making Calls) or during a call via the TwiML verb. The Calls list resource represents the set of phone calls made to and from an account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
callSid The call sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the single Call resource identified by the given call sid.

<twilio:get-calls>

Returns a list of phone calls made to and from the account identified by the given account sid. The list includes paging information and is sorted by DateUpdated with most-recent calls first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
to Optional. Only show calls to this phone number.
from Optional. Only show calls from this phone number.
status Optional. Only show calls currently in this status. May be queued, ringing, in-progress, completed, failed, busy, or no-answer.
startTime Optional. Only show calls that started on this date, given as YYYY-MM-DD. Also supports inequalities, such as StartTime<=YYYY-MM-DD for calls that started at or before midnight on a date, and StartTime>=YYYY-MM-DD for calls that started at or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of phone calls made to and from the account identified by the given account sid

<twilio:get-conference>

Returns a representation of the conference identified by the given conference id.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
conferenceSid The conference sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the conference identified by the given conference id.

<twilio:get-conferences>

Returns a list of conferences within an account. The list includes paging information and is sorted by DateUpdated, with most recent conferences first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
status Optional. Only show conferences currently in with this status. May be init, in-progress, or completed.
friendlyName Optional. List conferences who's FriendlyName is the exact match of this string.
dateCreated Optional. Only show conferences that started on this date, given as YYYY-MM-DD. You can also specify inequality, such as DateCreated<=YYYY-MM-DD for conferences that started at or before midnight on a date, and DateCreated>=YYYY-MM-DD for conferences that started at or after midnight on a date.
dateUpdated Optional. Only show conferences that were last updated on this date, given as YYYY-MM-DD. You can also specify inequality, such as DateUpdated<=YYYY-MM-DD for conferences that were last updated at or before midnight on a date, and DateUpdated>=YYYY-MM-DD for conferences that were updated at or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of conferences within an account

<twilio:get-incoming-phone-numbers>

Returns a list of IncomingPhoneNumber resource representations, each representing a phone number given to your account. The list includes paging information.

An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio or ported to Twilio.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
phoneNumber Optional. Only show the incoming phone number resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit.
friendlyName Optional. Only show the incoming phone number resources with friendly names that exactly match this name.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of IncomingPhoneNumber resource representations

<twilio:get-incoming-phone-numbers-by-incoming-phone-number-sid>

Returns an incoming phone numbers matching the given query filters.

An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio or ported to Twilio.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
incomingPhoneNumberSid The incoming phone number sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • an incoming phone number matching the given incoming phone number sid

<twilio:get-notification>

Return a notificaction resource for the given notification sid.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use in the query
notificationSid The notification sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a notificaction resource for the given notification sid.

<twilio:get-notifications-by-call-sid>

Returns a list of notifications generated for an account. The list includes paging information and is sorted by DateUpdated, with most recent notifications first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
callSid The call sid to use in the query
log Optional. An integer log level corresponding to the type of notification: 0 is ERROR, 1 is WARNING.
messageDate Optional. Only show notifications for this date. Should be formatted as YYYY-MM-DD. You can also specify inequality, such as MessageDate<=YYYY-MM-DD for messages logged at or before midnight on a date, and MessageDate>=YYYY-MM-DD for messages logged at or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of notifications generated for an account for the given call sid.

<twilio:get-outgoing-caller-id-by-outgoing-caller-id-sid>

Returns an outgoing caller id instance matching the given filters.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
outgoingCallerIdSid The outgoing caller id sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • an outgoing caller id instance matching the given filters.

<twilio:get-participant>

Returns a representation of this participant.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
conferenceSid The conference sid to use in the query
callSid The call sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of this participant.

<twilio:get-participants>

Returns the list of participants in the conference identified by the given conference sid.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
conferenceSid The conference sid to use in the query
muted Optional. Only show participants that are muted or unmuted. Either true or false.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • he list of participants in the conference identified by the given conference sid.

<twilio:get-recording>

Returns one of several representations depending on the given recording type.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
recordingSid The recording sid to use in the query
recordingType The recording type to use
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a recording representation.

<twilio:get-recordings>

Returns a list of Recording resource representations, each representing a recording generated during the course of a phone call. The list includes paging information.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
callSid Optional. Show only recordings made during the call given by this sid.
dateCreated Optional. Only show recordings created on the given date. Should be formatted as YYYY-MM-DD. You can also specify inequality, such as DateCreated<=YYYY-MM-DD for recordings generated at or before midnight on a date, and DateCreated>=YYYY-MM-DD for recordings generated at or after midnight on a date.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a list of Recording resource representations.

<twilio:get-sandbox>

Returns the Sandbox resource associated with the account identified by {YourAccountSid}. Twilio accounts upgraded prior to February 2010 may not have a Sandbox resource, and in this case you will receive a 404 (Not Found) response.

The Sandbox resource gives you programatic access to your Twilio Developer Sandbox phone number. Using this resource you can get the phone number and PIN for your sandbox, view the current voice and SMS URLs and update those URLs just like any other IncomingPhoneNumber resource on a Full Twilio Account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the Sandbox resource associated with the account identified by {YourAccountSid}. Twilio accounts upgraded prior to February 2010 may not have a Sandbox resource, and in this case you will receive a 404 (Not Found) response.

<twilio:get-sms-message>

Returns a single SMS message specified by the provided SMS message sid.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
smsMessageSid The SMS message sid to use in the query.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a single SMS message specified by the provided SMS message sid.

<twilio:get-sub-account-by-account-sid>

Subaccounts in Twilio are just accounts that are "owned" by another account. Using a subaccount you can segment each of your customers' use of Twilio and keep it separate from all the rest, allowing you to easily manage the activity and resources of each customer independently.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid The account sid to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the subaccount

<twilio:get-sub-account-by-friendly-name>

Subaccounts in Twilio are just accounts that are "owned" by another account. Using a subaccount you can segment each of your customers' use of Twilio and keep it separate from all the rest, allowing you to easily manage the activity and resources of each customer independently.

For instance, if you are running a hosted service that relies on Twilio you can create a Twilio subaccount for each customer that signs up. Then if a customer closes his or her account with your service, you can simply deactivate the associated Twilio subaccount.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
friendlyName The friendly name to use in the query
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the subaccount

<twilio:get-transcription-by-transcription-sid>

Returns a single Transcription resource representation identified by the given transcription sid.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
transcriptionSid The transcription sid to use in the query.
transcriptionFormat The transcription format of the response
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a single Transcription resource representation identified by the given transcription sid.

<twilio:get-transcriptions>

Returns a set of Transcription resource representations that includes paging information, sorted by 'DateUpdated', with most recent transcripts first.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
recordingSid Optional. The recording sid to use in the query
transcriptionFormat The transcription format for the response
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a set of Transcription resource representations

<twilio:make-call>

Initiates a call using the given paramaters. Only one of url or applicationSid parameters must be specified, not both. Returns the call representation.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
from The phone number to use as the caller id. Format with a '+' and country code e.g., +16175551212 (E.164 format). Must be a Twilio number or a valid outgoing caller id for your account.
to The number to call formatted with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212, 415-555-1212.
url Optional. The fully qualified URL that should be consulted when the call connects. Just like when you set a URL on a phone number for handling inbound calls.
applicationSid Optional. The 34 character sid of the application Twilio should use to handle this phone call. If this parameter is present, Twilio will ignore all of the voice URLs passed and use the URLs set on the application.
method Optional. The HTTP method Twilio should use when making its request to the above Url parameter's value. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML at Url. If an ApplicationSid parameter is present, this parameter is ignored.
status-callback-flow-ref Optional. A flow that Twilio will request when the call ends to notify your app. If an ApplicationSid parameter is present, this parameter is ignored.
sendDigits Optional. A string of keys to dial after connecting to the number. Valid digits in the string include: any digit (0-9), '#' and '*'. For example, if you connected to a company phone number, and wanted to dial extension 1234 and then the pound key, use SendDigits=1234#. Remember to URL-encode this string, since the '#' character has special meaning in a URL.
ifMachine Optional. Tell Twilio to try and determine if a machine (like voicemail) or a human has answered the call. Possible values are Continue and Hangup.
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.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the call representation.

<twilio:send-sms-message>

Send an outgoing SMS message. By specifying an SMS URL for your SMS enabled Twilio phone number, Twilio will make a request to your application to notify you when someone replies to a message you send.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
from A Twilio number enabled for SMS. Only phone numbers purchased from Twilio work here; you cannot (for example) spoof SMS messages from your own cell phone number.
to The destination phone number. Format with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212, 415-555-1212.
body The text of the message you want to send, limited to 160 characters.
status-callback-flow-ref Optional. A flow that Twilio will POST to when your message is processed. Twilio will POST the SmsSid as well as SmsStatus=sent or SmsStatus=failed.
applicationSid Optional. Twilio will POST SmsSid as well as SmsStatus=sent or SmsStatus=failed to the URL in the SmsStatusCallback property of this Application. If the StatusCallback parameter above is also passed, the Application's SmsStatusCallback parameter will take precedence.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the SMS message representation.

<twilio:update-account>

Allows you to modify the properties of an account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
accountStatus Optional. Alter the status of this account: use closed to irreversibly close this account, suspended to temporarily suspend it, or active to reactivate it.
friendlyName Optional. Update the human-readable description of this account.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • a representation of the account

<twilio:update-application>

Tries to update the application's properties, and returns the updated resource representation if successful.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
applicationSid The application sid to update
friendlyName Optional. A human readable description of the application, with maximum length 64 characters.
apiVersion Optional. Requests to this application's URLs will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01.
voiceUrl Optional. The URL that Twilio should request when somebody dials a phone number assigned to this application.
voiceMethod Optional. The HTTP method that should be used to request the VoiceUrl. Either GET or POST.
voice-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by VoiceUrl.
status-callback-flow-ref Optional. A flow that Twilio will request to pass status parameters (such as call ended) to your application.
voiceCallerIdLookup Optional. Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to a phone number assigned to this application.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Either GET or POST.
sms-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
sms-status-callback-flow-ref Optional. Twilio will make a POST request to this flow to pass status parameters (such as sent or failed) to your application if you specify this application's Sid as the ApplicationSid on an outgoing SMS request.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • returns the updated resource representation if successful.

<twilio:update-incoming-phone-numbers>

Tries to update the incoming phone number's properties, and returns the updated resource representation if successful.

* An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio or ported to Twilio.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
incomingPhoneNumberSid The incoming phone number sid to use
friendlyName Optional. A human readable description of the new incoming phone number resource, with maximum length 64 characters.
apiVersion Optional. Calls to this phone number will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01.
voiceUrl Optional. The URL that Twilio should request when somebody dials the new phone number.
voiceMethod Optional. The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.
voice-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML at Url.
status-callback-flow-ref Optional. A flow that Twilio will request to pass statusCallback parameters (such as call ended) to your application.
voiceCallerIdLookup Optional. Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false.
voiceApplicationSid Optional. The 34 character sid of the application Twilio should use to handle phone calls to this number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application instead.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to the phone number.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
sms-fallback-flow-ref Optional. A flow that Twilio will request if an error occurs requesting or executing the TwiML defined by sms.
smsApplicationSid Optional. The 34 character sid of the application Twilio should use to handle SMSs sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application instead.
accountSidDestination Optional. The unique 34 character id of the account to which you wish to transfer this phone number.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • if successful the updated incoming phone number instance.

<twilio:update-outgoing-caller-id-by-outgoing-caller-id-sid>

Updates the caller id, and returns the updated resource if successful.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
outgoingCallerIdSid The outgoing caller id sid to update
friendlyName A human readable description of a Caller ID, with maximum length of 64 characters. Defaults to a nicely formatted version of the phone number.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • returns the updated resource if successful.

<twilio:update-participant-status>

Updates the participant status. Returns the participant representation.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
conferenceSid The conference sid to use
callSid The call sid to use
muted Specifying true will mute the participant, while false will un-mute.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • the participant representation

<twilio:update-sandbox>

You can POST to the Sandbox resource to update the TwiML voice and SMS URLs associated with the sandbox number.

The Sandbox resource gives you programatic access to your Twilio Developer Sandbox phone number. Using this resource you can get the phone number and PIN for your sandbox, view the current voice and SMS URLs and update those URLs just like any other IncomingPhoneNumber resource on a Full Twilio Account.


XML Sample
INCLUDE_ERROR

Attributes
config-ref Optional. Specify which configuration to use.
accountSid Optional. The account sid to use, leave empty to use
accountSid
voiceUrl Optional. The URL that Twilio should request when somebody calls this sandbox.
voiceMethod Optional. The HTTP method that should be used to request the above URL. Must be either GET or POST. Defaults to POST.
smsUrl Optional. The URL that Twilio should request when somebody sends an SMS to the sandbox.
smsMethod Optional. The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
retryMax 1 Optional. Specify how many times this operation can be retried automatically
Child Elements
Return Payload
  • If successful, Twilio responds with an updated representation of the sandbox.