メニュー

Expand
ページを評価:

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.

動作 Attributes that modify behavior
Recording

record

trim

recordingStatusCallback

recordingStatusCallbackEvent

recordingStatusCallbackMethod

Autocreating Frontline Conversations

inboundAutocreation

routingAssignmentTimeout

Inbound call timeout inboundTimeout
Monitoring call and <Connect><Conversation> session status

statusCallback

statusCallbackEvent

statusCallbackMethod

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 許容値 Default values
        action 相対または絶対 URL 現在の文書の 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.

              プロパティ 概要
              Result

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

              • "completed"

                The intented 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"

                相手が応答する前に、REST API で通話がキャンセルされた。
              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 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.

              Without an action URL and without subsequent TwiML instructions after <Connect><Conversation>, the call will end.

              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

                    default: n/a

                    Your Frontline Conversation Service SID.

                    This attribute is required.

                    inboundAutocreation

                    default: true

                    true, false

                    routingAssignmentTimeout

                    default: 5

                    an integer

                    inboundTimeout

                    default: 60

                    an integer

                    record

                    default: do-not-record

                    • record-from-answer
                    • record-from-ringing
                    • record-from-answer-dual
                    • record-from-ringing-dual
                    • true
                    • false

                    trim

                    default: do-not-trim

                    • trim-silence
                    • do-not-trim

                    recordingStatusCallback

                    default: n/a

                    an absolute URL

                    recordingStatusCallbackMethod

                    default: POST

                    GET, POST

                    recordingStatusCallbackEvent

                    default: completed absent

                    • in-progress
                    • completed
                    • absent
                    • any combination of the above separated by a space

                    statusCallback

                    default: n/a

                    a relative or absolute URL

                    statusCallbackMethod

                    default: POST

                    GET, POST

                    statusCallbackEvent

                    default: completed

                    • call-initiated
                    • call-ringing
                    • call-answered
                    • call-completed
                    • any combination of the above sparated by a space

                    serviceInstanceSid

                    必須

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

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

                                      
                                      
                                      
                                      routingAssignmentTimeout must be used with inboundAutocreation set to true

                                      Use <Conversation> with inboundAutocreation and routingAssignmentTimeout attributes

                                      routingAssignmentTimeout must be used with inboundAutocreation set to true

                                      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:

                                                              プロパティ 概要
                                                              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.

                                                              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:

                                                                                プロパティ 概要
                                                                                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 statusCallbackEvents happen within the <Connect><Conversation> session.

                                                                                Each session's first statusCallbackEvent will receive a SequenceNumber of 1. The next statusCallbackEvent will receive a SequenceNumber of 2, etc.

                                                                                Although requests to the statusCallback URL are sent in order, they are separate HTTP requests, so there is no guarantee they will arrive in the same order. The SequenceNumber allows you to see the order of the statusCallback events as they occurred within the <Connect><Conversation> session.

                                                                                Timestamp

                                                                                The timestamp for the moment the request to the statusCallback URL was created.

                                                                                The Timestamp is UTC in RFC 2822 format (e.g. Sat, 7 May 2022 00:58:19 +0000).

                                                                                CallbackSource

                                                                                Indicates the source of the request to the statusCallback URL.

                                                                                The value will always be voice-conversation-service.

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

                                                                                            
                                                                                            
                                                                                            

                                                                                            back to attributes list

                                                                                            ページを評価:

                                                                                            ヘルプが必要ですか?

                                                                                            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.

                                                                                                  
                                                                                                  
                                                                                                  

                                                                                                  フィードバックくださりありがとうございます!

                                                                                                  Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                                                  Sending your feedback...
                                                                                                  🎉 Thank you for your feedback!
                                                                                                  Something went wrong. Please try again.

                                                                                                  Thanks for your feedback!

                                                                                                  Refer us and get $10 in 3 simple steps!

                                                                                                  ステップ1

                                                                                                  Get link

                                                                                                  Get a free personal referral link here

                                                                                                  ステップ2:

                                                                                                  Give $10

                                                                                                  Your user signs up and upgrade using link

                                                                                                  ステップ3

                                                                                                  Get $10

                                                                                                  1,250 free SMSes
                                                                                                  OR 1,000 free voice mins
                                                                                                  OR 12,000 chats
                                                                                                  OR more