TwiML™ Voice: <Conversation>
<Conversation> allows Twilio Frontline customers using Voice functionality to customize call behavior.
Frontline's default behavior handles call routing to and from a Frontline worker, as well as creating new Conversations and assigning workers to those new Conversations. If you already like Frontline's default behavior for your use case, you don't need to use <Conversation>.
<Connect><Conversation> allows you to:
- execute other Voice TwiML instructions before connecting a customer and a Frontline worker
- configure in-call behavior
- configure call behavior after a participant leaves the call or when an error occurs
<Conversation> is a TwiML noun that must be nested within the <Connect> verb.
If you want to use <Conversation>, you will first need to configure your Frontline instance in your Twilio Console.
You should read through the Advanced Voice Configuration page before using <Connect><Conversation>.
Configure call behavior with <Connect><Conversation>
<Connect><Conversation> allows you to modify call behavior before, during, and after a call between a Frontline worker and customer.
Read the subsections below to learn how to use <Connect><Conversation> to meet your use case's needs.
Modify call behavior before connecting to Frontline
If you want Twilio to execute TwiML instructions before connecting a Frontline worker and customer, you should first direct calls to that set of TwiML instructions. When appropriate, you should then give Twilio <Connect><Conversation> TwiML instructions. Some ways you can do this include:
- using <Connect><Conversation> in the same TwiML document as the initial instructions
- providing <Connect><Conversation> in response to Twilio's request to an
action
URL (like in <Gather>) - updating the TwiML of the call with the Call Resource
Modify call behavior during a Frontline Voice call
<Conversation> provides attributes that allow you to modify some call and Frontline Conversation behavior. The table below shows the behaviors you can modify and the associated <Conversation> attributes. Click on an attribute to jump to its section on this page.
Behavior | Attributes that modify behavior |
Recording |
recordingStatusCallback |
Autocreating Frontline Conversations | |
Inbound call timeout | inboundTimeout |
Monitoring call and <Connect><Conversation> session status |
Modify call behavior after a <Connect><Conversation> session ends
If you want to customize the behavior of a Frontline Voice call after one party hangs up or when an error occurs, you should use <Connect>'s action attribute. After a <Connect><Conversation> session ends, Twilio will send a request to the action
URL and expect a new set of TwiML instructions.
This will require you to set up a separate TwiML endpoint that can dynamically generate TwiML based on the information Twilio sends to the action URL. You should decide how you want to handle each type of Result
value (and/or any other values within the request from Twilio) and then create and return the appropriate TwiML.
<Connect> attributes
<Conversation> is a TwiML noun that is nested within the <Connect> verb. <Connect>'s action
and method
attributes allow you to execute a new set of TwiML instructions for a call after the <Connect><Conversation> session ends.
Attribute name | Allowed values | Default values |
action |
Relative or absolute URL | current document URL |
method |
GET , POST |
POST |
action
The action
attribute takes an absolute or relative URL as a value. After a <Connect><Conversation> session ends, Twilio will send an HTTP request to this action
URL and will expect a new set of TwiML instructions in the response. If you do not provide an action
attribute, Twilio will request TwiML from the current TwiML document.
This HTTP request's body will contain the information about the result of the <Connect><Conversation> session, along with Twilio's standard request parameters. See Twilio's request to the action URL section below for more information on the shape of this request body.
A <Connect><Conversation> session ends (and thereby triggers Twilio's HTTP request to the action
URL) in the following ways:
- one or both of the parties on the call hangs up
- the new call is incomplete, meaning there is no answer or some error occurs when connecting the two parties
- the attempt to autocreate a new Conversation fails
- a new Conversation is created, but no worker is assigned before the timeout that was set in the routingAssignmentTimeout attribute
- an invalid Conversation SID is used when attempting to look up an existing Conversation
- an inbound call comes in without an existing Conversation and your Frontline instance has disabled inbound Conversation autocreation
- an internal error occurs
The reason a <Connect><Conversation> ends is included in the Result
property in the body of Twilio's request to your action
URL.
Twilio's request to the action URL
The request body of Twilio's request to the action
URL contains some properties that provide information about the <Connect><Conversation> session, along with Twilio's standard request parameters. These <Connect><Conversation>-related properties are listed below.
Property | Description |
Result |
The result of the <Conversation> session. Possible values are:
|
WorkerInitiated |
A Boolean that indicates whether the call was initiated by a Frontline worker. The value is true for outbound calls initiated by a Frontline worker. The value is false when the call was not initiated by a Frontline worker. |
DialCallStatus |
This indicates the outcome of the attempt to connect (or "Dial") the caller with the intended recipient. Possible values are:
|
DialCallSid |
The Call SID of the new call leg that is created when connecting the two Participants |
DialCallDuration |
The duration, in seconds, of the new call leg that is created when connecting the two Participants |
RecordingSid |
The Recording SID of the Call Recording (if applicable) |
RecordingDuration |
The duration, in seconds, of the Call Recording (if applicable) |
RecordingUrl |
The URL of the Call Recording. This parameter is included only if the The Recording file may not yet be accessible at the moment the |
Without an action
URL and without subsequent TwiML instructions after <Connect><Conversation>, Twilio will re-request the URL that hosts the TwiML you just executed. This is probably not the behavior you want, as it will cause Twilio to keep looping on the <Connect><Conversation> instructions.
Responding to Twilio's request to the action URL
Your application should dynamically provide new TwiML instructions based on the result of the <Connect><Conversation> session. This may involve checking the values of the Result
, WorkerInitiated
, and DialCallStatus
properties in Twilio's request to your action
URL.
The example scenario below illustrates how you can handle Twilio's request to the action
URL in order to execute another set of TwiML instructions.
Example: Prompting a customer to leave a voicemail
- A customer calls your Frontline number, which is configured with the following TwiML instructions:
<Response> <Connect action="https://example.com/myActionUrl"> <Conversation serviceInstanceSid="ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" inboundTimeout="20"/> </Connect> </Response>
- Twilio finds the matching Conversation and dials the appropriate Frontline worker.
- The Frontline worker does not answer within 20 seconds, so the <Connect><Conversation> session ends and Twilio sends a request to your
action
URLhttps://example.com/myActionUrl
. - Your endpoint at
https://example.com/myActionUrl
checks that the request contains aResult
value ofno-answer
, and then responds to Twilio with the following TwiML instructions that prompt the caller to leave a voicemail:
<Response> <Say> Sorry, your personal advisor is not available right now. Please leave a message after the tone. Thank you! </Say> <Record recordingStatusCallback="https://example.com/myVoicemailRecordingStatusEndpoint" /> </Response>
Note: Since the recording in this example is started by <Record> TwiML (rather than <Conversation>'srecord
attribute), the details about this recording are sent to the <Record> verb'srecordingStatusCallback
URL.
method
This optional <Connect> attribute indicates the HTTP request method to be used when Twilio sends a request to the action
URL.
If you don't specify a method attribute in <Connect>, POST
is used by default.
The allowed values are POST
and GET
.
<Conversation> attributes
The table below lists all of the <Conversation> attributes and the allowed values for each. Click on an attribute to learn more.
All attributes are optional except serviceInstanceSid
.
Attribute | Allowed values |
default: n/a |
Your Frontline Conversation Service SID. This attribute is required. |
default: |
true , false |
default: |
an integer |
default: |
an integer |
default: |
|
default: |
|
default: n/a |
an absolute URL |
default: |
GET , POST |
default: |
|
default: n/a |
a relative or absolute URL |
default: |
GET , POST |
default: |
|
serviceInstanceSid
required
The serviceInstanceSid
<Conversation> attribute indicates your Frontline Conversation Service's SID. This tells Twilio in which Conversation Service a Frontline Conversation should be created or found.
Find your Frontline Conversation Service SID in your Console:
- Go to Explore Products and pin Conversations to the sidebar.
- In the left navigation, click on Conversations > Manage > Services and find Frontline Service. The SID is listed next to it.
inboundAutocreation
When Twilio executes <Conversation> TwiML for inbound calls (from a customer towards your Frontline instance), Twilio will check to see if a Conversation already exists between the caller and the number that the caller dialed.
For an inbound call, if no Conversation is found and the inboundAutocreation
attribute is set to true
, Twilio will create a new Conversation with the caller as a Participant.
For an inbound call, if no Conversation is found and the inboundAutocreation
attribute is set to false
, the call will be rejected and Twilio's request to the action
URL will contain a Result
property with the value "no-existing-conversation"
.
This attribute is the equivalent of the Autocreate a Conversation setting for incoming messages on the Integration page of your Messaging Service in the Console.
The default value of the inboundAutocreation
attribute is true
.
routingAssignmentTimeout
When Twilio executes <Conversation> TwiML for inbound calls (from a customer towards your Frontline instance), Twilio will check to see if an existing Conversation exists between the caller and the number that the caller dialed.
For an inbound call in which no Conversation is found and the inboundAutocreation
attribute is set to true
, Twilio will create a new Conversation with the caller as a Participant and then will wait for your Frontline instance to assign a Frontline worker via Pool routing or Custom routing.
By default, Twilio will wait 5 seconds for a Frontline worker Participant to be added to the Conversation.
If no Frontline worker Participant is added before the timeout, the <Conversation> session will end and Twilio's request to the action
URL will contain a Result
property with the value "no-other-participants"
.
In the event that the Result
value is "no-other-participants"
, you should check that your Frontline routing is set up properly.
This result means that the Conversation that was created is unusable, since no Frontline worker is associated with that customer. You can programmatically delete the Conversation via the API or you can use the Console.
You will also want to consider what TwiML you want Twilio to execute in this case (maybe <Say> an error message or a <Say> prompting the customer to leave a message followed by a <Record>).
inboundTimeout
The inboundTimeout
attribute is the number of seconds a <Conversation> session will wait for a Frontline worker to answer a call from a customer.
The default inboundTimeout
value is 60
.
Request to <Connect>'s action URL after timeout
After the inboundTimeout
period has passed, the URL specified in <Connect>'s action
attribute will receive a request containing a Result
parameter with a value of dialed-call-incomplete
. The request will also contain a DialCallStatus
parameter with a value of no-answer
.
Request to the statusCallback URL after timeout
If you provided a URL in <Conversation>'s statusCallback
attribute and you've included call-completed
in <Conversation>'s statusCallbackEvent
parameter, that URL will receive a request with a Status
parameter with a value of call-completed
.
This doesn't necessarily mean the call ended, but rather means that that particular leg of the call (that connected the Frontline worker and the customer) is complete. More details about why/how the call leg ended can be found in the request to the action URL in the DialCallStatus
property.
record
The record
attribute allows you to record both parties in a call within the <Conversation> session. Recordings are available to be saved in mono-channel or dual-channel format.
The default value is do-not-record
.
The allowed values are as follows:
do-not-record
record-from-answer
record-from-answer-dual
record-from-ringing
record-from-ringing-dual
true
false
For backward compatibility, true
is an alias for record-from-answer
and false
is an alias for do-not-record
.
Learn more about Recordings on the Recording Resource page.
Mono-channel recordings
For mono-channel recordings, audio from both parties in a call are mixed down into a single channel in a single recording file.
To enable mono-channel recordings, you can choose one of the following values for <Conversation>'s record
attribute:
record-from-answer
: the recording will start as soon as the call is answeredrecord-from-ringing
: the recording will start when the call starts ringing, before the recipient answers the call
Dual-channel recordings
For dual-channel recordings, audio from both parties in a call are contained in separate channels within a single recording file.
For dual-channel recordings, you can choose one of the following values for <Conversation>'s record
attribute:
record-from-answer-dual
: the recording will start as soon as the call is answeredrecord-from-ringing-dual
: the recording will start when the call starts ringing, before the recipient answers the call
trim
The trim
attribute allows you to trim leading and trailing silence from your recording's audio files. This attribute is only valid when recording is enabled.
The default value is do-not-trim
.
The allowed values are as follows:
do-not-trim
: Audio recordings will contain leading and trailing silence.trim-silence
: Audio recordings will not contain leading and trailing silence.
Trimming a file may cause the duration of the recording to be slightly less than the duration of the call.
recordingStatusCallback
The recordingStatusCallback
attribute takes an absolute URL value. This is where Twilio will send a GET or POST request when a Recording is available to access.
Request to recordingStatusCallback
Twilio will send the following properties in the body of the request to the recordingStatusCallback
URL:
Property | Description |
AccountSid |
The unique identifier for the Twilio account associated with this Recording |
CallSid |
The unique identifier for the Call associated with this Recording |
RecordingSid |
The unique identifier for the Recording |
RecordingUrl |
The URL of the Recording. |
RecordingStatus |
The status of the Recording. Possible values are completed and failed . |
RecordingDuration |
The length of the Recording in seconds. |
RecordingChannels |
The number of channels in the final Recording audio file. Possible values are 1 and 2 . |
RecordingSource |
The initiation method used to create the Recording. |
Learn more about Recordings on the Recording Resource page.
recordingStatusCallbackMethod
The recordingStatusCallbackMethod
indicates which HTTP method Twilio will use when sending a request to the recordingStatusCallback
URL.
Allowed values are GET
and POST
.
The default method is POST
.
recordingStatusCallbackEvent
The recordingStatusCallbackEvent
attribute allows you to specify which Recording statuses should trigger a request to the recordingStatusCallback
URL.
The default value is completed
.
The allowed values are as follows:
in-progress
: the Recording has started, but is not yet available to accesscompleted
: the Recording is complete and available for you to accessabsent
: the Recording is absent and inaccessible
To specify more than one value, separate each with a space.
statusCallback
The statusCallback
attribute takes a value of a relative or absolute URL. This URL is where Twilio will send HTTP requests upon the occurrence of an event specified in the statusCallbackEvent
attribute. These HTTP requests provide you with information about the current state of the call between the Frontline worker and customer that was created by the <Connect><Conversation> session.
Request to the statusCallback URL
The body of the request from Twilio to your statusCallback
URL contains the following properties:
Property | Description |
AccountSid |
The unique identifier for the Twilio account associated with this <Connect><Conversation> session. |
ConversationSid |
The unique identifier for the Conversation associated with this <Connect><Conversation> session. |
DialCallSid |
The unique identifer for the Call leg that connects the Frontline worker and customer. |
WorkerInitiated |
Indicates whether the <Connect><Conversation> was initiated by a Frontline worker or not. |
Status |
The status of the <Connect><Conversation> session. |
SequenceNumber |
The SequenceNumber is an integer that indicates the order in which Each session's first Although requests to the |
Timestamp |
The timestamp for the moment the request to the The Timestamp is UTC in RFC 2822 format (e.g. |
CallbackSource |
Indicates the source of the request to the The value will always be |
statusCallbackMethod
The statusCallbackMethod
indicates which HTTP method Twilio will use when sending a request to the statusCallback
URL.
Allowed values are GET
and POST
.
The default method is POST
.
statusCallbackEvent
The statusCallbackEvent
attribute indicates which call statuses should trigger a request to the statusCallback
URL. These events are associated with the call leg that connects the Frontline worker Participant and the customer Participant.
The default value is call-completed
.
The possible values are as follows:
call-initiated
: the call to the other Participant has startedcall-ringing
: the call to the other Participant has started ringingcall-in-progress
: the call to the other Participant has been answeredcall-completed
: the call to the other Participant has been completed. Note: This event does not indicate whether the call was successful (answered, busy, no answer, etc.). For accurate information on the result of the call, check the request to <Connect>'s action URL.
To specify more than one value, separate each with a space.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.