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.

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.

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.

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.

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

1. 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>

2. Twilio finds the matching Conversation and dials the appropriate Frontline worker.
3. The Frontline worker does not answer within 20 seconds, so the <Connect><Conversation> session ends and Twilio sends a request to your action URL https://example.com/myActionUrl.
4. Your endpoint at https://example.com/myActionUrl checks that the request contains a Result value of no-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>'s record attribute), the details about this recording are sent to the <Record> verb's recordingStatusCallback 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.

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:

1. Go to Explore Products and pin Conversations to the sidebar.
2. In the left navigation, click on Conversations > Manage > Services and find Frontline Service. The SID is listed next to it.

back to attributes list

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.

back to attributes list

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".

back to attributes list

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.

back to attributes list

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 answered
• record-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 answered
• record-from-ringing-dual: the recording will start when the call starts ringing, before the recipient answers the call

back to attributes list

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.

back to attributes list

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:

Learn more about Recordings on the Recording Resource page.

back to attributes list

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.

back to attributes list

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 access
• completed: the Recording is complete and available for you to access
• absent: the Recording is absent and inaccessible

To specify more than one value, separate each with a space.

back to attributes list

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:

back to attributes list

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.

back to attributes list

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 started
• call-ringing: the call to the other Participant has started ringing
• call-in-progress: the call to the other Participant has been answered
• call-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.

back to attributes list