Twilio
Download:
twilio-documentation.zip

Calls Resource

A Call 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, or during a call via the <Dial> verb

Base Resource URI

/2008-08-01/Accounts/{YourAccountSid}/Calls

Calls Segment

A single call may contain multiple call "Segments", each represented as a Call element. For example, if a person dials your application, that's one call record. Then, if your application <Dial>s another phone number, a new related call segment is created. Both have the same Sid, but different CallSegmentSids. For the initial Call, the CallSegmentSid is empty.

Resource Properties

A resource is represented by the following properties:

Call Resource Properties
Property Description
Sid A 34 character string that uniquely identifies this resource.
CallSegmentSid A 34 character string that uniquely identifies a portion of a phone call. For example, if you use the <Dial> verb during a call, you've created a new call segment. CallSegmentSid is an empty string for the initial call.
DateCreated The date that this resource was created, given in RFC 2822 format.
DateUpdated The date that this resource was last updated, given in RFC 2822 format.
AccountSid The 34 character id of the Account this Call is associated with. (Your account!)
Called The phone number of the telephone that received this Call. For incoming calls, it's one of your Twilio phone numbers. For outgoing calls, it's the person that you called. Always presented as a 10 digit number, with no "decoration" (like dashes, parentheses, etc.)
Caller The Caller ID of the telephone that made this Call. For incoming calls, it's the person who called your Twilio phone number. For outgoing calls, it's the Caller you specified for the call. Always presented as a 10 digit number, with no "decoration" (like dashes, parentheses, etc.)
PhoneNumberSid If the call was inbound, this is the Sid of the IncomingPhoneNumber that received the call. If the call was outgoing, it is the Sid of the OutgoingCallerId from which the call was placed.
Status An integer representing the status of the call. 0 = Not Yet Dialed, 1 = In Progress, 2 = Complete, 3 = Failed - Busy, 4 = Failed - Application Error, 5 = Failed - No Answer
StartTime The timestamp of the start of the call, given in RFC 2822 format. If the call has not yet been dialed, this field will be empty.
EndTime The timestamp of the end of the call, given in RFC 2822 format. If the call did not complete successfully, this field will be empty.
Duration Duration is the length of the call in seconds. This value is only populated for successfully completed calls. This will be an empty value for calls that are currently ongoing, that were busy, failed, or were not answered.
Price The charge for this call in USD. Populated after the call is completed. Note, this value may not be immediately available. In a trial account, this value is not populated, since the call was free!
Flags A bitwise field for storing extra information about a call. Possible values are: 1 means the call was inbound, 2 means the call was initiated by the API, 4 means the call segment was initiated by a Dial verb. These values may be OR'd together. For example, if you initiated a call via the API, the flags would equal 2. Then, if during that call you used the verb to call another person, the second call segment would have Flag equal 6, indicating the the call was originally API initiated, and then the segment was Dial initiated.

Call List Resource

HTTP Methods

Returns a list of phone calls made by your account Each is represented by a <Call> element, under a <Calls> list element that includes paging information. The list is sorted by DateUpdated, with newest calls first. Example:

GET /2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/Calls HTTP/1.1

<TwilioResponse>  
    <Calls page="0" numpages="1" pagesize="50" total="38" start="0" end="37">  
        <Call>  
            <Sid>CA42ed11f93dc08b952027ffbc406d0868</Sid>  
            <DateCreated>Sat, 07 Feb 2009 13:15:19 -0800</DateCreated>
            <DateUpdated>Sat, 07 Feb 2009 13:15:19 -0800</DateUpdated>
            <CallSegmentSid/>  
            <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>  
            <Called>4159633717</Called>  
            <Caller>4156767925</Caller>  
            <PhoneNumberSid>PN01234567890123456789012345678900</PhoneNumberSid>  
            <Status>2</Status>  
            <StartTime>Thu, 03 Apr 2008 04:36:33 -0400</StartTime>  
            <EndTime>Thu, 03 Apr 2008 04:36:47 -0400</EndTime>  
            <Duration>14</Duration>  
            <Price/>  
            <Flags>1</Flags>  
        </Call>  
        <Call>  
            <Sid>CA751e8fa0a0105cf26a0d7a9775fb4bfb</Sid>  
            <DateCreated>Sat, 07 Feb 2009 13:15:19 -0800</DateCreated>
            <DateUpdated>Sat, 07 Feb 2009 13:15:19 -0800</DateUpdated>
            <CallSegmentSid/>  
            <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>  
            <Called>2064287985</Called>  
            <Caller>4156767925</Caller>  
            <PhoneNumberSid>PNd59c2ba27ef48264773edb90476d1674</PhoneNumberSid>  
            <Status>2</Status>  
            <StartTime>Thu, 03 Apr 2008 01:37:05 -0400</StartTime>  
            <EndTime>Thu, 03 Apr 2008 01:37:40 -0400</EndTime>  
            <Duration>35</Duration>  
            <Price/>  
            <Flags>1</Flags>  
        </Call>  
        ... 
    </Calls> 
</TwilioResponse>

POST

Initiates a new phone call. See Making Calls for full details.

PUT

Not supported

DELETE

Not supported

URL Filtering

You may limit the list by providing certain query string parameters to the listing resource. Note, parameters are case-sensitive:

  • Called: Only show calls to this ten digit phone number.
  • Caller: Only show calls from this ten digit phone number.
  • Status: Integer between 0 and 2. Only show calls currently in this status.
  • StartTime: Only show calls that started on this date, given as YYYY-MM-DD. Example: StartTime=2009-07-06. You can also specify inequality, 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.
  • EndTime: Only show calls that ended on this date, given as YYYY-MM-DD. Example: EndTime=2009-07-06. You can also specify inequality, such as EndTime<=YYYY-MM-DD for calls that ended at or before midnight on a date, and EndTime>=YYYY-MM-DD for calls that end at or after midnight on a date.

Examples:

/2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/Calls?Status=1&StartTime=2009-07-06

Would only show in progress calls started on Jul 06th, 2009.

/2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/Calls?Status=1&StartTime>=2009-07-06

Would only show in progress calls started on or after midnight Jul 06th, 2009.

/2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/Calls?Status=1&StartTime>=2009-07-04&StartTime<=2009-07-06

Would only show in progress calls started between midnight Jul 04th, 2009 and midnight Jul 06th, 2009.

TIP! Get a CSV of your Calls

Did you know you can append a .csv to any REST resource to get a Comma Separated Values representation? Especially useful for call logs. Try this:

/2008-08-01/Accounts/{YourAccountSid}/Calls.csv

Read the Tips & Tricks Section for more about alternate representation, including CSV.

Call Instance Resource

/2008-08-01/Accounts/{YourAccountSid}/Calls/{CallSid}

This resource represents an individual phone call. For calls with multiple segments, this represents the initial phone call. Calls made via the <Dial> verb are available via the Segments subresource.

HTTP Methods

GET

Returns a single <Call> resource with the Sid provided. Example:

GET /2008-08-01/Accounts/AC309475e5fede1b49e100272a8640f438/Calls/CA42ed11f93dc08b952027ffbc406d0868 HTTP/1.1

<TwilioResponse>  
    <Call>  
        <Sid>CA42ed11f93dc08b952027ffbc406d0868</Sid>  
        <DateCreated>Sat, 07 Feb 2009 13:15:19 -0800</DateCreated>
        <DateUpdated>Sat, 07 Feb 2009 13:15:19 -0800</DateUpdated>
        <CallSegmentSid/>  
        <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>  
        <Called>4159633717</Called>  
        <Caller>4156767925</Caller> 
        <PhoneNumberSid>PN01234567890123456789012345678900</PhoneNumberSid>  
        <Status>2</Status>  
        <StartTime>Thu, 03 Apr 2008 04:36:33 -0400</StartTime>  
        <EndTime>Thu, 03 Apr 2008 04:36:47 -0400</EndTime>  
        <Duration>14</Duration>  
        <Price/>  
        <Flags>1</Flags>  
    </Call> 
</TwilioResponse>

POST

Initiates a call redirect. See Redirecting a call for full details.

PUT

Not supported

DELETE

Not supported

Call Instance Sub Resources

The Call resource supports a few sub-resources for your convenience.

Segments

/2008-08-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Segments

Returns an list of Call resources that were segments created in the same call.

A Segment Instance

/2008-08-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Segments/{CallSegmentSid}

Returns an a single Call resource for the CallSid and CallSegmentSid provided.

Recordings

/2008-08-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Recordings

Returns an list of recordings that were generated during that call. See the Recordings section for the response format.

Notifications

/2008-08-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Notifications

Returns an list of notifications that were generated during that call. See the Notifications section for the response format.