Tasks

Collect Call Digits

Collects the digits a caller types on their phone's keypad during a phone call. Useful for menus like "press 1 for support", and for numbers like a customer or account number.

Run this task on an answered phone call (see Answer Call), in the same action as the voice notification that tells the assistant to ask the question. From then on, Stubber records the keys the caller presses. When the caller is done, the stub gets one _update_from_call with call_data.event set to digits and everything the caller typed in call_data.digits.

The task doesn't wait for the caller: it returns straight away with collecting, and the assistant carries on talking meanwhile.

The caller is done when they:

• press #, which isn't part of the digits
• have typed max_digits digits, when you set it
• stop typing for a few seconds, or don't start typing in time

Keys the caller presses while nothing is being collected are ignored, so only the answer to the question ends up in the digits.

# Basic usage

Run it together with a voice notification that asks the question, eg:

# Parameters

# calluuid

required

string

The id of the call, from call_data.calluuid of the incoming call event. Save it on the stub when the call comes in, so later actions can use it. The call must be answered.

# name

optional

string

A name for the question, eg menu or customer_number. It comes back in call_data.name of the digits event, so you can tell the answers to different questions apart.

# terminator

optional

string

The key that ends the entry: #, or none to only end on max_digits or a timeout. Use none for one key menus, together with max_digits: 1.

Default: #

# max_digits

optional

number

The entry ends as soon as the caller has typed this many digits, from 1 to 64.

Default: no limit

# first_digit_timeout_ms

optional

number

How long the caller has to start typing, in milliseconds, from 1000 to 120000. It counts from when the task runs, so it includes the time the assistant takes to ask the question.

Default: 15000

# inter_digit_timeout_ms

optional

number

The longest pause between two keys, in milliseconds, from 1000 to 120000. A caller who pauses longer is taken to be done.

Default: 5000

# Result

The digits themselves follow later, in a digits event on _update_from_call:

        "call_data": {
  "event": "digits",
  "calluuid": "238e63a5-e071-47d9-bac2-360b77fc5991",
  "sipconnectionuuid": "161bc664-3c90-4a1e-ba07-6d1f5438dfe4",
  "name": "customer_number",
  "digits": "100234",
  "ended_by": "terminator"
}

      

# Errors

These are conceptual errors.

# Things to know

• One question at a time. Running the task again while digits are being collected starts a new collection. The earlier one ends without an event.
• The digits event goes to this stub, the one that ran the task, even when the call came in on another stub.
• Hanging up. When the caller hangs up during a collection, no digits event follows. The stub hears about the end of the call from _update_from_voice.
• Only digits. * and the A–D keys are ignored, and so is # when terminator is none.
• The assistant can't hear the keys. Tell it what was typed with a voice notification once the digits event arrives. Also tell it to wait quietly while the caller types.
• Phone system. Keypad presses must reach Stubber as RFC 2833 (RFC 4733) events, the default on 3CX and Asterisk. On Asterisk the extension's dtmf_mode must be rfc4733 or auto, not inband or info.

# Examples

# A menu, then a customer number

The caller presses 1, 2 or 3 to choose support, billing or cancellations, then types their customer number. Save calluuid on the stub when the call comes in, eg as stub.data.calluuid.

1. After answering the call, collect one key for the menu, and have the assistant ask:

2. On the menu answer (call_data.name = 'menu'), save the choice and ask for the customer number when it was 1, 2 or 3:

For any other key, or no_input, run the menu collection and question again, eg up to two times, and then let the assistant ask out loud instead.

3. On the customer number (call_data.name = 'customer_number'), look the customer up and tell the assistant:

When ended_by is no_input, or digits is too short, ask once more, then fall back to asking out loud.