Receiving DTMF digits notification

VoiceAI Connect can send a notification to the bot when the user presses a DTMF (dual tone multi frequency) digit at the phone's dialpad.

The behavior of VoiceAI Connect can be set to one of the following:

Disabled - By default, no event is sent to the bot in case a digit was pressed.
Pass immediately - A separate event is sent to the bot immediately for each digit pressed.
Digits collection - Digits are collected and a single event is sent to the bot with all the collected digits. The digit collection stops according to the number of digits, to a terminating key, like the pound (#) key, or to a configurable timeout. This option can simplify the bot logic needed for handling sequences of digits (e.g., the user is requested to enter his ID number).

For Google Dialogflow CX, DTMF digits are natively supported, so the digits collection can be done by the bot framework.

How do I use it?

Event format

VoiceAI Connect sends DTMF digits to the bot as DTMF event. The syntax of the event depends on the bot framework:

AudioCodes Bot API

This message is sent as a DTMF event with the digits as the value of the event.

Example:

{
    "type": "event",
    "name": "DTMF",
    "value": "123"
}

Microsoft Bot Framework

This message is sent as a DTMF event with the digits as the value of the event.

Example:

{
    "type": "event",
    "name": "DTMF",
    "value": "123"
}

Microsoft Copilot Studio

By default, DTMF is sent as text to the Copilot Studio bot to change the default behavior see sendDTMFAsText

Example:

{
  "type": "message",
  "text": "123"
}

Activity example:

{
  "sessionParams": {
    "sendDTMF": true,
    "dtmfCollect": true,
    "dtmfCollectSubmitDigit": "*"
  }
}

Microsoft Copilot Studio legacy

Currently, DTMF is sent as text to the Copilot Studio legacy bot.

Example:

{
  "type": "message",
  "text": "123"
}

Activity example:

[Activity
  type = event,
  name = config
  channelData = ${json(`{
    "sessionParams": {
      "sendDTMF": true,
      "dtmfCollect": true,
      "dtmfCollectSubmitDigit": "*"
      }
    }
  `)}
]

Dialogflow CX

DTMF events are sent according to the Dialogflow CX specification.

Dialogflow ES

This message is sent as a DTMF event with the digits in the value event parameter.

Example:

{
    "queryInput": {
        "event": {
            "languageCode": "en-US",
            "name": "DTMF",
            "parameters": {
                "value": "123"
            }
        }
    }
}

The digits can be used when generating the response text, by using a syntax such as this:

#DTMF.value

Event properties

The following table lists the additional fields that can be passed with the DTMF event:

Field	Type	Description
`participant`	String	Indicates the identifier of the participant ("callee" or "caller") that pressed the DTMF. Example: { "id": "1e0d5b55-19b9-48a2-8ab0-cc6022d489a9", "language": "en-US", "name": "DTMF", "parameters": { "participant": "callee" }, "timestamp": "2024-03-06T09:17:05.695Z", "type": "event", "value": "4" } Note: The feature is applicable only to Agent assist calls. VoiceAI Connect Enterprise supports this feature from Version 3.20 and later.

Field

Type

Description

participant

String

Indicates the identifier of the participant ("callee" or "caller") that pressed the DTMF.

Example:

{
  "id": "1e0d5b55-19b9-48a2-8ab0-cc6022d489a9",
  "language": "en-US",
  "name": "DTMF",
  "parameters": {
    "participant": "callee"
  },
  "timestamp": "2024-03-06T09:17:05.695Z",
  "type": "event",
  "value": "4"
}

Note: The feature is applicable only to Agent assist calls.

VoiceAI Connect Enterprise supports this feature from Version 3.20 and later.

Configuration

To enable the feature, you should set the sendDTMF parameter to true.

Parameters can be set on configuration or dynamically by the bot as explained in Changing call settings.

The following bot parameters can be used to control basic DTMF behavior:

Parameter	Type	Description
`sendDTMF`	Boolean	Enables the sending of DTMF events to the bot. true: Enabled false: (Default) Disabled For Live Hub, the parameter is also controllable from the number configuration page. However, since Dialogflow CX determines if DTMF is enabled/disabled, this parameter is not relevant for Live Hub bots that are Dialogflow CX.
`sendDTMFAsText`	Boolean	Enables the sending of DTMF as text messages to the bot. true: Enabled false: (Default) Disabled Note: For Microsoft Copilot Studio (or Copilot Studio legacy) bot, the default is `true`.
`googleSendDTMF`	Boolean	Deprecated. Equivalent to `sendDTMF` parameter.
`bargeInOnDTMF`	Boolean	Enables barge-in on DTMF. true: (Default) Enabled. When the bot is playing a response to the user (playback of bot message), the user can "barge-in" (interrupt) with a DTMF digit. This terminates the bot response, allowing the bot to listen to and process the digits sent from the user. false: Disabled. VoiceAI Connect doesn't expect DTMF input from the user until the bot has finished playing its response to the user. In other words, the user can't "barge-in" until the bot message response has finished playing. Note: If you enable this feature (i.e., bargeInOnDTMF configured to true), you also need to enable the sending of DTMF digits (see the sendDTMF parameter). Currently, this parameter is not supported by Azure (when the speech-to-text is performed by the bot framework).

Digits collection

By default, if sendDTMF is enabled, VoiceAI Connect sends each digit on a separate event to the bot. If the bot is expecting a sequence of digits, this might prove difficult for the bot to implement the logic of collecting the digits.

To overcome this, digits collection can be enabled, which delays sending of the event to the bot until all the desired digits are collected. After all the digits are collected at the VoiceAI Connect, a single DTMF event is sent to the bot containing all the collected digits.

To enable digits collection, set dtmfCollect parameter to true, and use the following parameters to control the behavior:

Parameter	Type	Description
dtmfCollect	Boolean	Enables the DTMF digit collection. true: Enabled. VoiceAI Connect first collects all the DTMF digits entered by the user, and only then sends them all together to the bot. false: (Default) Disabled. As VoiceAI Connect receives a DTMF digit entered by the user, it sends that single digit to the bot. In other words, it sends each DTMF digit one at a time to the bot. Note: When enabled, you can configure additional settings using the following parameters: dtmfCollectInterDigitTimeoutMS, dtmfCollectMaxDigits, and dtmfCollectSubmitDigit. If the sendDTMF parameter is configured to false (default), incoming DTMF digits are ignored by VoiceAI Connect even if the dtmfCollect parameter is configured to true. DTMF collection is not applicable to Dialogflow CX bots, as it is performed by the bot framework.
dtmfCollectInterDigitTimeoutMS	Number	Defines the timeout (in milliseconds) that VoiceAI Connect waits for the user to press another digit before it sends all the digits to the bot. If the timeout expires since the last digit entered by the user, VoiceAI Connect sends all the collected digits to the bot (as a DTMF message), without waiting for the maximum number of expected digits or for the "submit" digit. The timeout is triggered after the user enters the first DTMF digit and is reset after each digit. The valid value range is 0 to unlimited. The default is 2000. Note: The parameter is applicable only when the dtmfCollect parameter is configured to true. Once VoiceAI Connect sends all the DTMF digits to the bot, any additional DTMF digits entered by the user is ignored by VoiceAI Connect until the bot responds to the DTMF event message.
dtmfCollectMaxDigits	Number	Defines the maximum number of DTMF digits that VoiceAI Connect expects to receive from the user. Once VoiceAI Connect receives and collects this number of digits entered by the user, it immediately sends all the digits to the bot (as a DTMF message), without waiting for the timeout to expire or for the "submit" digit. The valid value range is 0 (disabled) to unlimited. The default is 5. If configured to 0, the DTMF collection and sending method is according to dtmfCollectInterDigitTimeoutMS or dtmfCollectSubmitDigit. Note: The parameter is applicable only when the dtmfCollect parameter is configured to true. Once VoiceAI Connect sends all the DTMF digits to the bot, any additional DTMF digits entered by the user is ignored by VoiceAI Connect until the bot responds to the DTMF event message.
dtmfCollectSubmitDigit	String	Defines a special DTMF "submit" digit that when received from the user, VoiceAI Connect immediately sends all the collected digits to the bot (as a DTMF message), without waiting for the timeout to expire or for the maximum number of expected digits. The valid value is any symbol on a phone keypad. The default is # (pound key). If you want to disable this parameter, configure it to "" (empty string). Note: The parameter is applicable only when the dtmfCollect parameter is configured to true. VoiceAI Connect doesn't include this "submit" digit in the DTMF event message sent to the bot. Once VoiceAI Connect sends all the DTMF digits to the bot, any additional DTMF digits entered by the user is ignored the VoiceAI Connect until the bot responds to the DTMF event message.