TwiML™ Voice: <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.

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

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

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
7
});
8

9
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
4
      </Connect>
5
</Response>

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

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect({
5
    action: 'https://example.com/yourActionUrl'
6
});
7
connect.conversation({
8
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect action="https://example.com/yourActionUrl">
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
4
    </Connect>
5
</Response>

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: Result

Description:

The result of the <Conversation> session. Possible values are:

• "session-success" The customer and Frontline worker were successfully connected with a Voice call and at least one party hung up.
• "dialed-call-incomplete" The attempt to dial the other party was unsuccessful, either due to an error or no answer.
• "failed-create-conversation" Given that the inboundAutocreation attribute for <Conversation> is true, Twilio will attempt to create a new Conversation for inbound calls from customers who are not yet part of a Conversation. If the creation of this new Conversation is unsuccessful, the "failed-create-conversation" value is returned.
• "no-other-participants" Given that the inboundAutocreation attribute for <Conversation> is true, Twilio will create a new Conversation with the customer as one of the Participants and then attempt to add a Frontline worker as the other Participant. If no worker is assigned before the timeout, "no-other-participants" is returned. The timeout is 5 seconds by default, but can be modified using the routingAssignmentTimeout <Conversation> attribute.
• "invalid-conversation" This error occurs for outbound calls in which the Conversation SID sent by the Frontline App is invalid.
• "no-existing-conversation" Given that the inboundAutocreation attribute for <Conversation> is false, this error arises when a caller that is not a Participant in an existing Conversation attempts to make an inbound call to your Frontline instance. The call is rejected and "no-existing-conversation" is returned.
• "internal-error" This error occurs when some internal condition caused the <Conversation> session to be unsuccessful.

Property: WorkerInitiated

Description:

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.

Property: DialCallStatus

Description:

This indicates the outcome of the attempt to connect (or "Dial") the caller with the intended recipient. Possible values are:

• "completed" The intended recipient answered the call and the two Participants were connected successfully.
• "busy" Twilio received a busy signal when trying to connect to the intended recipient.
• "no-answer" The intended recipient did not answer the call before the timeout period ended.
• "failed" Twilio was unable to route the call to the intended recipient. This is often caused by attempting to call a properly-formatted but non-existent phone number.
• "canceled" The call was canceled via the REST API before it was answered.

Property: DialCallSid

Description:

The Call SID of the new call leg that is created when connecting the two Participants

Property: DialCallDuration

Description:

The duration, in seconds, of the new call leg that is created when connecting the two Participants

Property: RecordingSid

Description:

The Recording SID of the Call Recording (if applicable)

Property: RecordingDuration

Description:

The duration, in seconds, of the Call Recording (if applicable)

Property: RecordingUrl

Description:

The URL of the Call Recording. This parameter is included only if the record <Conversation> attribute is used. This parameter is not included for Recordings initiated in other ways. The Recording file may not yet be accessible at the moment the action callback is received. Use the recordingStatusCallback <Conversation> attribute to be notified when the recording is available.

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:

   Copy code block

   1
   <Response>
   2
     <Connect action="https://example.com/myActionUrl">
   3
       <Conversation serviceInstanceSid="ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" inboundTimeout="20"/>
   4
     </Connect>
   5
   </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:

   Copy code block

   1
   <Response>
   2
     <Say>
   3
     Sorry, your personal advisor is not available right now. Please leave a message after the tone. Thank you!
   4
     </Say>
   5
     <Record recordingStatusCallback="https://example.com/myVoicemailRecordingStatusEndpoint" />
   6
   </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.

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect({
5
    action: 'https://example.com/yourActionUrl',
6
    method: 'GET'
7
});
8
connect.conversation({
9
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
10
});
11

12
console.log(response.toString());

1
<Response>
2
    <Connect action="https://example.com/yourActionUrl" method="GET">
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
4
    </Connect>
5
</Response>

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.

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
7
});
8

9
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
4
      </Connect>
5
</Response>

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    inboundAutocreation: true
8
});
9

10
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" inboundAutocreation="true" />
4
    </Connect>
5
</Response>

back to attributes list

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

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    inboundAutocreation: true,
8
    routingAssignmentTimeout: '10'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" inboundAutocreation="true" routingAssignmentTimeout="10" />
4
    </Connect>
5
</Response>

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    inboundTimeout: '10'
8
});
9

10
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" inboundTimeout="10"/>
4
    </Connect>
5
</Response>

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.

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

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    record: 'record-from-answer'
8
});
9

10
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" record="record-from-answer"/>
4
    </Connect>
5
</Response>

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

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

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    record: 'record-from-answer',
8
    trim: 'trim-silence'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" record="record-from-answer" trim="trim-silence"/>
4
    </Connect>
5
</Response>

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    record: 'record-from-answer',
8
    recordingStatusCallback: 'https://example.com/yourRecordingStatusCallback'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect>
3
      <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" record="record-from-answer" recordingStatusCallback="https://example.com/yourRecordingStatusCallback"/>
4
    </Connect>
5
  </Response>

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

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    record: 'record-from-answer',
8
    recordingStatusCallback: 'https://example.com/yourRecordingStatusCallback',
9
    recordingStatusCallbackMethod: 'GET'
10
});
11

12
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" record="record-from-answer" recordingStatusCallback="https://example.com/yourRecordingStatusCallback" recordingStatusCallbackMethod="GET"/>
4
    </Connect>
5
</Response>

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    record: 'record-from-answer',
8
    recordingStatusCallback: 'https://example.com/yourRecordingStatusCallback',
9
    recordingStatusCallbackEvent: 'in-progress completed'
10
});
11

12
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" record="record-from-answer" recordingStatusCallback="https://example.com/yourRecordingStatusCallback" recordingStatusCallbackEvent="in-progress completed"/>
4
    </Connect>
5
</Response>

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    statusCallback: 'https://example.com/yourStatusCallback'
8
});
9

10
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" statusCallback="https://example.com/yourStatusCallback"/>
4
      </Connect>
5
</Response>

The body of the request from Twilio to your statusCallback URL contains the following properties:

back to attributes list

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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    statusCallback: 'https://example.com/yourStatusCallback',
8
    statusCallbackMethod: 'GET'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" statusCallback="https://example.com/yourStatusCallback" statusCallbackMethod="GET" />
4
      </Connect>
5
</Response>

back to attributes list

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-answered: 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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const connect = response.connect();
5
connect.conversation({
6
    serviceInstanceSid: 'ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
7
    statusCallback: 'https://example.com/yourStatusCallback',
8
    statusCallbackEvent: 'call-initiated call-ringing call-answered call-completed'
9
});
10

11
console.log(response.toString());

1
<Response>
2
    <Connect>
3
        <Conversation serviceInstanceSid="ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" statusCallback="https://example.com/yourStatusCallback" statusCallbackEvent="call-initiated call-ringing call-answered call-completed"/>
4
      </Connect>
5
</Response>

back to attributes list

The url attribute allows you to specify a URL that will return a TwiML response to be run on the called party's end, after they answer, but before the parties are connected.

You can use this TwiML to privately <Play> or <Say> information to the called party. You could also provide a chance to decline the phone call using <Gather> and <Hangup>.