commands-voice.md

copyright	lastupdated	subcollection
years 2020, 2021	2021-02-04	assistant

{:shortdesc: .shortdesc} {:new_window: target="_blank"} {:external: target="_blank" .external} {:deprecated: .deprecated} {:important: .important} {:note: .note} {:tip: .tip} {:pre: .pre} {:codeblock: .codeblock} {:screen: .screen} {:javascript: .ph data-hd-programlang='javascript'} {:java: .ph data-hd-programlang='java'} {:python: .ph data-hd-programlang='python'} {:swift: .ph data-hd-programlang='swift'}

Phone integration reference

{: #commands-voice}

Add action commands to the message context object to manage the flow of conversations with customers who interact with your assistant over the telephone. {: shortdesc}

Learn about the supported commands and reserved context variables that are used by the phone integration.

Supported commands

{: #commands-voice-actions}

Each action consists of a command property, followed by an optional parameter property to define parameters for commands that require them. The commands that are described in the following table are supported by the phone integration.

Action command	Description	Parameters
vgwActCollectDTMF	Instructs the phone integration to collect dual-tone multi-frequency signaling (DTMF) input.	dtmfTermKey: The DTMF termination key, which signals the end of DTMF input. For example, "#". dtmfCount: The number of DTMF digits to collect. dtmfMinCount: The minimum number of DTMF digits to collect when you configure your DTMF collection to accept a range of entries. dtmfMaxCount: The maximum number of DTMF digits to collect when you configure your DTMF collection to accept a range of entries. After this number of digits is collected, a conversation turn is initiated. dtmfInterDigitTimeoutCount: The amount of time in milliseconds to wait for a new DTMF digit after a DTMF digit is received. During an active DTMF collection, this timeout activates when the first DTMF collection is received. When the interdigit timeout is active, it deactivates the vgwPostResponseTimeout timer. If the dtmfInterDigitTimeoutCount parameter isn't specified, the post response timer resets after receiving each DTMF digit, and stays active until either the vgwPostResponseTimeout parameter is met or the collection is completed. dtmfIgnoreSpeech: When set to true, speech is automatically disabled on the reception of a DTMF digit until either the collection is completed or a timeout occurs. The default value is false. dtmfPauseAfterCollection: Indicates whether to disable DTMF input after DTMF collection is completed. All DTMF input is ignored until it's reenabled by the vgwActUnPauseDTMF action. The default value is false.
vgwActDisableDTMFBargeIn	Disables DTMF barge-in so that playback from the phone integration isn't interrupted when callers press keys.	No parameters.
vgwActDisableSpeechBargeIn	Disables speech barge-in so that playback from the phone integration isn't interrupted when callers speak.	No parameters.
vgwActDisableSTTDuringPlayback	Pauses speech-to-text processing before playing back audio, which prevents speech barge-in while the audio plays. After the playback transaction is completed, the phone integration resumes speech-to-text processing. If speech-to-text processing was disabled by the vgwActPauseSTT action, it does not resume after the playback transactions are completed unless it's reenabled by the vgwActUnPauseSTT action.	No parameters.
vgwActEnableDTMFBargeIn	Enables DTMF barge-in so that callers can interrupt playback from the phone integration by pressing a key.	No parameters.
vgwActEnableSpeechBargeIn	Enables speech barge-in so that callers can interrupt playback from the phone integration by speaking.	No parameters.
vgwActEnableSTTDuringPlayback	Reenables speech-to-text processing during audio playback transactions.	No parameters.
vgwActExcludeFromTTSCache	Instructs the phone integration not to cache the response from the {{site.data.keyword.texttospeechshort}} service. For example, responses that contain sensitive PHI, PII, and PCI DSS data or dynamic information such as customer names or birth dates should be excluded. This action tag must be set on the dialog node for each utterance that you don't want to cache.	No parameters.
vgwActForceNoInputTurn	Forces a new turn in the conversation without waiting for input from the caller. The phone integration sends a message request with "vgwNoInputTurn" in the text field so that you can map this request to an intent in your dialog.	No parameters.
vgwActHangup	Hangs up the call.	No parameters.
vgwActPlayText	Plays an utterance string from a list of utterances that are defined in the output.generic field. If multiple strings are defined, the utterance is chosen based on the selection_policy value.	text: An array of utterances. Optional. If not specified, the action plays a list of utterances that are configured in the output.generic field. errAudioURL: A URL to an audio file that is played if the phone integration can't contact the {{site.data.keyword.texttospeechshort}} service to complete the action. The audio file must be in WAV format.
vgwActPlayUrl	Plays an audio file as soon as the included text is played back, such as for playing music on hold (MOH) or common one-time utterances. If no text is included, the audio is played immediately. The file must be single channel (mono), PCM-encoded, and have a 8,000 Hz sampling rate with 16 bits per sample.	url: The URL to play. Required. playURLInLoop: Optionally set to Yes or No to indicate whether to play the URL in a loop. The default value is No.
vgwActPauseDTMF	Disables DTMF input. All DTMF input is ignored until it's reenabled by the vgwActUnPauseDTMF action.	No supported parameters.
vgwActPauseSTT	Pauses speech-to-text processing until it's reenabled by the vgwActUnPauseSTT action. If recording is enabled and speech-to-text processing is paused, the audio from the caller isn't captured.	participants: For SIPREC sessions, a comma-separated list of participants that the action is applied to. If the participants list isn't provided, the action is applied to all participants or SIPREC streams.
vgwActSendSIPInfo	Send UUI data in a SIP INFO request.	sipHeaders: A paired list of SIP Header names and values, which is added to the SIP INFO request in name/value format. The list can't contain the system header fields such as From, To, or Contact. Well-known header fields must be provided in the correct format to avoid parsing issues. Malformed headers can't be added to the message. messageBody: Optional. A body that is attached to the SIP INFO request. When present, a mandatory header, Content-Type, must be provided in the sipHeaders list. If Content-Type isn't included, a default value of application/text is inserted.
vgwActSendSMS	Enables the assistant to send an SMS message to the user.	message: An SMS message that is sent to the user. Required. mediaURL: An array of publicly accessible URLs of the media to be sent to the user. Optional. tenantPhoneNumber : The phone number that is associated with the tenant. The format of the number must match the format of the number that is required by the SMS provider. If no value is provided, the tenant ID from the voice configuration for the active call is sent. Optional. userPhoneNumber: The phone number to send an SMS message to. The format of the number must match the format of the number that is required by the SMS provider. If no value is provided, the voice caller's phone number from an incoming SIP INVITE request (from header) is used. Optional.
vgwActSetDisambiguationConfig	Applies configuration settings to the disambiguation list.	prefixText: the text that will be prepended to each choice that is displayed in the disambiguation list. matchWord: An array of utterances. Used to match Speech to Text utterances to each choice in the list. disableSpeech: Optionally set to true or false to indicate whether to disable speech recognition when disambiguation is triggered. The default value is false.
vgwActSetOptionsConfig	Applies configuration settings to the options response type.	prefixText: the text that will be prepended to each label in an option response. matchWord: An array of utterances. Used to match Speech to Text utterances to each option in the list. disableSpeech: Optionally set to true or false to indicate whether to disable speech recognition when the option response type is triggered. The default value is false.
vgwActSetSTTConfig	Applies a set of parameters for the phone integration to pass to the {{site.data.keyword.speechtotextshort}} service. {{site.data.keyword.conversationshort}} dynamically defines the parameters based on the call.	Parameters are transparently passed as JSON properties to the {{site.data.keyword.speechtotextshort}} service. config: Parameters for the {{site.data.keyword.speechtotextshort}} service when using narrowband audio, such as: model: Specifies the language model to use, such as en-US_NarrowbandModel. profanity_filter: Specifies whether to filter out curse words. The options are true or false. smart_formatting: Specifies whether to apply formatting rules that direct the service to convert strings such as dates and times into more conventional representations, so they are easier to understand. The options are true or false. customization_id: Specifies the ID of a custom language model to apply, such as 81d3630-ba58-11e7-aa4b-41bcd3f6f24d. acoustic-customization_id: Specifies the ID of a custom acoustic model to apply, such as e4766090-ba51-11e7-be33-99bd3ac8fa93. . broadbandConfig: Parameters for the {{site.data.keyword.speechtotextshort}} service when broadband audio is enabled. Required only when bandPreference is set to broadband. At minimum, the language model must be defined on the model property. bandPreference: Defines which audio band to prefer when negotiating audio codecs in the session. Set to broadband to use broadband audio when possible. The default value is narrowband. confidenceScoreThreshold: Confidence threshold of messages from the {{site.data.keyword.speechtotextshort}} service. Messages with a confidence score that are under the threshold are not sent to the assistat. The default value of 0 means that all responses are used. The recommended values are between 0 and 1. echoSuppression: Indicates whether to suppress results from {{site.data.keyword.speechtotextshort}} that might occur from an echo of {{site.data.keyword.texttospeechshort}} synthesis. bargeInResume: Set to true to resume playing back audio after barge-in if the confidence score of the final utterance is lower than the threshold specified by the confidenceScoreThreshold property. connectionTimeout: Time in seconds that the integration waits to establish a socket connection with the {{site.data.keyword.speechtotextshort}} service. If the time is exceeded, the integration attempts to connect with the {{site.data.keyword.speechtotextshort}} service again. If the service still can't be reached, the call fails. requestTimeout: Time in seconds that the integration waits to establish a speech recognition session with the {{site.data.keyword.speechtotextshort}} service. If the time is exceeded, the integration attempts to connect with the {{site.data.keyword.speechtotextshort}} service again. If the service still can't be reached, the call fails. updateMethod: Optional. Specifies the update strategy to choose when setting the speech configuration. Possible values are replace, replaceOnce, merge, or mergeOnce.
vgwActSetTTSConfig	Applies a set of parameters for the phone integration to pass to the {{site.data.keyword.texttospeechshort}} service. {{site.data.keyword.conversationshort}} dynamically defines the parameters based on the call.	Parameters are passed as JSON properties to the {{site.data.keyword.texttospeechshort}} service. config: Parameters for the {{site.data.keyword.texttospeechshort}} service, such as: voice: Specifies the voice model to use, such as es-ES_LauraVoice. jitterBufferDelay: The amount of time in milliseconds to buffer before playing back audio from the {{site.data.keyword.texttospeechshort}} service. This buffer accounts for any jitter in the streaming audio. connectionTimeout: Time in seconds that the integration waits to establish a socket connection with the {{site.data.keyword.texttospeechshort}} service. If the time is exceeded, the integration attempts to connect with the {{site.data.keyword.texttospeechshort}} service again. If the service still can't be reached, the call fails. requestTimeout: Time in seconds that the integration waits to establish a speech synthesis session with the {{site.data.keyword.texttospeechshort}} service. If the time is exceeded, the integration attempts to connect with the {{site.data.keyword.texttospeechshort}} service again. If the service still can't be reached, the call fails. cacheTimeToLive: The time in hours to cache responses from the {{site.data.keyword.texttospeechshort}} service to improve playback response time. When enabled, all {{site.data.keyword.texttospeechshort}} responses are cached unless they are excluded in the dialog. updateMethod: Optional. Specifies the update strategy to choose when setting the speech configuration. Possible values are replace, replaceOnce, merge, or mergeOnce.
vgwActTransfer	Transfers the call to the defined transfer target.	acceptTransferRejectCodes: A comma-separated list of the error codes that are treated as a successful response when the phone integration processes NOTIFY requests during a call transfer. transferHeader: A custom header field that is added to the SIP REFER request. transferHeaders: A list of custom header field name and value pairs to be added to a transfer request. For example: { "Custom-Header1": "123", "Custom-Header2": "456" } transferHeaderVal: The value of the custom header field that you defined on the transferHeader parameter. transferMethod: The value that specifies how to perform a call transfer. The call transfer can be defined in one of two ways: Default: REFER HANGUP: instead of referring the call, the phone integration plays back any associated text and then hangs up the call by sending a BYE request. transferTarget: The SIP or telephone URI to transfer the call to, such as sip:12345556789\\@myhost.com or tel:+18883334444 Note: When you define SIP URIs in the {{site.data.keyword.conversationshort}} service, the @ character must be escaped with backslashes as shown. transferTargetHeader: Specifies which header field in a SIP BYE request to use in transfer target. By default, this parameter is defined as Transfer-Target, or the header field specified in the vgwTransferTargetHeader state variable. uuiData: User-to-User Information (UUI) data to send. uuiSendMethod: The method by which the UUI data is sent. The following values are supported: uuiHeader: Sends UUI data in a User-to-User header field. Default. contactHeader: Sends UUI data in a Contact header field. referToURL: Sends UUI data in a Refer-To header field. If data is sent in a Contact or Refer-To header field, the data is encoded as a URI header. If the Refer-To header value is a tel URL, the UUI data is sent as a URL parameter. If a parameter isn't specified, the phone integration uses the values of the following respective state variables, if defined: vgwTransferHeader vgwTransferHeaderVal vgwTransferTarget
vgwActUnPauseDTMF	Reenables DTMF input that was disabled by the vgwActPauseDTMF action.	No supported parameters.
vgwActUnPauseSTT	Resumes speech-to-text processing that was previously paused by the vgwActPauseSTT action.	No supported parameters.
{: caption="Table 1. Actions that you can initiate from dialog" caption-side="top"}

Reserved context variables

{: #commands-voice-context-variables}

The following table describes the context variables that have special meaning in the context of the phone integration. They should not be used for any purpose other than the documented use.

Table 2 describes the context variables that are set from your dialog. Table 3 describes the context variables that you can set by the phone integration.

Table 2. Context variables that are set by your dialog

{: #commands-voice-context-variables-set-by-dialog}

Context variable name	Expected value	Description
vgwByeCustomHeader	User-defined value	Defines a custom header in an outgoing SIP BYE message. The custom header value is defined by the vgwByeCustomHeaderVal context variables.
vgwByeCustomHeaderVal	User-defined value	Defines the value of a custom header in an outgoing SIP BYE message. The custom header is defined by the vgwByeCustomHeader context variables.
vgwConversationFailedAudioURL	User-defined value	A URL to an audio file that is played if the {{site.data.keyword.texttospeechshort}} service can't be contacted when the phone integration attempts to play back the vgwConversationFailedMessage message. Configure your dialog to set this variable on the first turn.
vgwConversationFailedMessage	Text string	Message streamed to the caller when a call is being transferred or disconnected due to a failure of one of the Watson services. Configure your dialog to set this variable on the first turn.
vgwConversationResponseTimeout	Time in ms	The amount of time in milliseconds that the phone integration waits to receive a response from {{site.data.keyword.conversationshort}}. If the time is exceeded, the phone integration tries again to contact {{site.data.keyword.conversationshort}}. If the service still can't be reached, the call fails.
vgwDisconnectCallOnNoUserInputTurnCount	User-defined value	Informs the phone integration whether to disconnect the call on consecutive post response timeouts. Determines the number of consecutive post response timeouts to allow before the call is disconnected.
vgwDisconnectCallOnTransferFailure	Yes or No	Informs the phone integration whether to disconnect the call when a call transfer fails. When set to No, the phone integration initiates a conversation turn by sending "vgwCallTransferFailed" text to {{site.data.keyword.conversationshort}}. Then, {{site.data.keyword.conversationshort}} can either disconnect the call or transfer it to a different destination as configured in the dialog.
vgwErrAudioURL	User-defined value	A URL to an audio file that is played if the {{site.data.keyword.texttospeechshort}} service can't be contacted when the phone integration attempts to play back a response. The audio file must be in WAV format.
vgwFinalUtteranceTimeout	Time in ms	The amount of time in milliseconds that the phone integration waits to receive a final utterance from the {{site.data.keyword.speechtotextshort}} service. The timeout occurs if the phone integration does not receive a final utterance within the specified time limit, even if hypotheses continue to be generated. When the timeout occurs, the phone integration sends {{site.data.keyword.conversationshort}} a text update with the word "vgwFinalUtteranceTimeout" to indicate that no final utterance was received.
vgwPostResponseTimeoutCount	Time in ms	The amount of time in milliseconds to wait for a new utterance after the response is played back to the caller. If this value is exceeded, the {{site.data.keyword.conversationshort}} receives a text update with the word "vgwPostResponseTimeout" to indicate that a timeout occurred.
vgwSessionInactivityTimeout	Time in min	Inactivity timeout interval. The timeout interval value specifies in minutes how long the phone integration allows a session to be inactive. When the timeout expires, the phone integration ends the session.
vgwTransferFailedAudioURL	User-defined value	A URL to an audio file that is played if the {{site.data.keyword.texttospeechshort}} service can't be contacted when the phone integration attempts to play back the vgwTransferFailedMessage message. Configure your dialog to set this variable on the first turn.
vgwTransferFailedMessage	Text string	If the vgwDisconnectCallOnTransferFailure parameter is set to Yes, the message that is streamed to the caller if the call transfer fails. You define this message when you set up the phone integration.
{: caption="Table 2. Voice context variables set by the dialog" caption-side="top"}

Table 3. Context variables that are set by the integration

{: #commands-voice-context-variables-set-by-integration}

Context variable name	Expected value	Description
vgwBargeInOccurred	Yes or No	Indicates whether barge-in occurred.
vgwCallTransferFailed	Yes	Indicates that the call transfer failed. When this variable is set, the text field contains the string "vgwCallTransferFailed".
vgwCallTransferred	Yes	Indicates that the call was transferred.
vgwDTMFCollectionSucceeded	Yes/No	Variable sent to the phone integration from {{site.data.keyword.conversationshort}} to indicate whether the DTMF collection succeeded or failed. When Yes, a DTMF collection succeeded, and returns the expected number of digits. When No, a DTMF collection failed to collect the specified number of digits. Even when No, all collected digits are passed to the dialog in the input string of the turn request.
vgwHangUp	Yes or No	Indicates whether the conversation session was ended.
vgwHangupReason	String	When a hangup is initiated either by the caller or because of an error, this variable is sent to {{site.data.keyword.conversationshort}} to indicate why the call was disconnected. The text in the message request that is sent to {{site.data.keyword.conversationshort}} also includes "vgwHangUp".
vgwIsOutboundCall	Yes or No	Indicates whether the call is an outbound call.
vgwIsDTMF	Yes or No	Indicates whether the input to {{site.data.keyword.conversationshort}} is dual-tone multi-frequency signaling (DTMF).
vgwNetworkWarnings	JSON array	An array of network warnings that occurred during the {{site.data.keyword.conversationshort}} turn. To send network warnings, RTCP must be enabled.
vgwReceivedOnChannel	SMS	If an utterance is received over the SMS channel, this variable presents and is set to SMS.
vgwSessionID	User-defined value	A custom session ID header pulled from the SIP INVITE request. The value represents the global session ID that is used in all the phone integration audit logs related to the session.
vgwSIPCallID	SIP Call-ID	The SIP call ID associated with the conversation session.
vgwSIPCustomInviteHeader	User-defined value	A user-defined SIP header that is pulled from the initial SIP INVITE request and passed to the {{site.data.keyword.conversationshort}} service.
vgwSIPCustomInviteHeaders	User-defined value	A user-defined list of SIP headers that are pulled from the initial SIP INVITE request and passed to the {{site.data.keyword.conversationshort}} service. For example: "vgwSIPCustomInviteHeaders": { "Custom-Header1": "123", "Custom-Header2": "456" }
vgwSIPFromURI	SIP From URI	The SIP From URI associated with the {{site.data.keyword.conversationshort}} service.
vgwSIPRequestURI	SIP Request URI	The SIP request URI that started the conversation session.
vgwSIPToURI	SIP To URI	The SIP To URI associated with the conversation session.
vgwSMSContext	String	The context extracted from the opaque data, smsOpaqueData, received from Twilio.
vgwSMSMessage	String	The SMS message received from the caller.
vgwSMSMedia	JSON array	The MMS message received from the caller. {   "vgwSMSMedia ": [     {       "mediaURL": "https://api.example.com/2015-01-01/Accounts/AC0123456789abcdef9876543210fedcba/Messages/ MM4a2645684e43ea4bc4a0f3cba7763c61/Media/MEd84f995dfafb30b0e9e5739622dec4ad",       "mediaContentType": "image/jpeg"     }   ] }
vgwSMSUserPhoneNumber	String	The phone number that the SMS message was received from.
vgwSTTProvider	String	The name of the provider that is used for the call. The context variable is set if the provider name is configured.
vgwSTTResponse	JSON object	The final response from the {{site.data.keyword.speechtotextshort}} service in JSON format, including the transcript and confidence score for the top hypothesis and any alternatives. The format matches exactly the format that is received from the {{site.data.keyword.speechtotextshort}} service: {   "result_index": 0,   "warnings": [     "Unknown arguments: continuous."   ],   "results": [     {       "final": true,       "alternatives": [         {           "transcript": "Hello world",           "confidence": 0.758         },         {           "transcript": "Hello wooled",           "confidence": 0.358         }       ]     }   ] }.
vgwTransferReason	String	Indicates the reason why a call was transferred.
vgwTTSProvider	String	The name of the provider that is used for the call. The context variable is set if the provider name is configured.
{: caption="Table 3. Voice context variables set by the integration" caption-side="top"}