Play a prompt and collect digits or speech over REST

Voiceprompt playback and input collection on a live call

Speak a prompt into a live call from your own backend, stop it early, and collect keypad digits or speech, with the result delivered to your webhook.

restdtmfspeech

The claim

Prompting a caller and reading their answer is usually written into the call’s document. The same two operations exist as REST commands. A process that holds the call id can run them on a call it did not set up. The vendored REST spec, tools/openapi/rest.json, is the authority for the shapes.

Why it holds

calling.play requires control_id and play, an ordered list of items. Each item has a type, one of audio, tts, silence or ringtone, and params. A tts item requires text; an audio item requires url.
calling.play.stop requires control_id, the id you gave the play.
calling.play.volume requires control_id and volume, a dB adjustment the spec bounds to “between -40 and 40”. The recipe refuses anything outside it.
calling.collect requires control_id and, in the spec’s words, “at least one of digits or speech”. digits requires max. Results are “delivered asynchronously via the status_url webhook”, so the recipe refuses a collect with no status URL before it is sent.
start_input_timers defaults to false, and then initial_timeout does not start counting. Both collects send true. Send false instead when the prompt is still playing, and start the clock yourself with calling.collect.start_input_timers for the same control_id.

The verifier proves the six requests and the refusal. The spec is the authority for what the platform does with them.

How it works

def say(call_id, text, control_id=PLAY_ID, status_url=None):
    item = {"type": "tts", "params": {"text": text}}
    params = {"control_id": control_id, "play": [item]}
    if status_url:
        params["status_url"] = status_url
    return client.calling.play(call_id, **params)

def ask_digits(call_id, status_url, max_digits=10, control_id=COLLECT_ID):
    _needs_status_url(status_url)
    digits = {"max": max_digits, "terminators": "#", "digit_timeout": 5}
    return client.calling.collect(call_id, control_id=control_id, digits=digits,
                                  initial_timeout=10, start_input_timers=True,
                                  status_url=status_url)

What the platform receives for ask_digits:

{"command": "calling.collect",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"control_id": "agent-desk-input",
            "initial_timeout": 10,
            "digits": {"max": 10, "terminators": "#", "digit_timeout": 5},
            "start_input_timers": true,
            "status_url": "https://your-host/collect-events"}}

The SDK’s calling namespace, rest/namespaces/calling.py, sends every call command to that one path and puts the call id in id. Each operation gets its own control id, and the matching stop command names it.

The spec documents what arrives at status_url. A digit result has the shape {control_id, call_id, node_id, result: {type: "digit", params: {digits, terminator}}}; a speech result carries {type: "speech", params: {text, confidence}}. Playback events carry a state of playing, paused, finished or error. The route that receives them is an ordinary webhook handler, the same shape as the one in Handle call status callbacks.

Limitations

The verifier proves the requests, not the audio or the recognition. What the caller hears, and what text the speech engine returns, are live behaviour.

The recipe gives the play and the collect fixed control ids. Two prompts playing at once on one call need two ids; the spec says the id must be unique per active play on the call.

What to change first

Change "tts" in say to "speech" and run the verifier. The item type is outside the spec’s enum and the exact body comparison fails, which is the point: the four item types are the whole vocabulary.

Where this sits

Before this

Build an IVR menu

End or transfer a live call over REST Collect speech input and branch on it Handle call status callbacks

python/app.py

"""Play a prompt and collect digits or speech over REST.

`calling.play` speaks text or plays a file into a live call, `calling.play.stop`
cuts it short, and `calling.collect` gathers keypad digits or speech. Each is
one POST to /api/calling/calls addressed to the call id. Results do not come
back in the HTTP response: the platform posts them to the `status_url` you
give, so a collect without one is refused here before it is sent.

Written against signalwire-sdk 3.0.1 (RestClient.calling).

    python app.py say <call_id> "Please key in your account number"
    python app.py stop <call_id>
    python app.py volume <call_id> -6
    python app.py digits <call_id> https://your-host/collect-events
    python app.py speech <call_id> https://your-host/collect-events
"""
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# one id per operation type; stop and collect.stop name them
PLAY_ID = "agent-desk-prompt"
COLLECT_ID = "agent-desk-input"


def say(call_id, text, control_id=PLAY_ID, status_url=None):
    """Speak `text` to the caller. Playback events go to status_url if given."""
    item = {"type": "tts", "params": {"text": text}}
    params = {"control_id": control_id, "play": [item]}
    if status_url:
        params["status_url"] = status_url
    return client.calling.play(call_id, **params)


def play_file(call_id, url, control_id=PLAY_ID):
    """Play an audio file from an HTTP(S) URL instead of speaking text."""
    item = {"type": "audio", "params": {"url": url}}
    return client.calling.play(call_id, control_id=control_id, play=[item])


def set_volume(call_id, volume, control_id=PLAY_ID):
    """Adjust a playing prompt, in dB. The spec's range is -40 to 40."""
    try:
        # the command line hands this over as a string
        volume = float(volume)
    except (TypeError, ValueError):
        raise ValueError(f"volume must be a number of dB, not {volume!r}") from None
    if not -40 <= volume <= 40:
        raise ValueError(f"volume must be between -40 and 40 dB, not {volume!r}")
    return client.calling.play_volume(call_id, control_id=control_id, volume=volume)


def stop_playback(call_id, control_id=PLAY_ID):
    """Cut the prompt short, for example when the caller starts keying digits."""
    return client.calling.play_stop(call_id, control_id=control_id)


def _needs_status_url(status_url):
    # the result arrives only by webhook; without one the collect is unobservable
    if not status_url:
        raise ValueError("a collect needs a status_url to deliver its result")


def ask_digits(call_id, status_url, max_digits=10, control_id=COLLECT_ID):
    """Collect up to max_digits keypad digits, ended early by #."""
    _needs_status_url(status_url)
    digits = {"max": max_digits, "terminators": "#", "digit_timeout": 5}
    # start_input_timers defaults to false, and then initial_timeout never runs
    return client.calling.collect(call_id, control_id=control_id, digits=digits,
                                  initial_timeout=10, start_input_timers=True,
                                  status_url=status_url)


def ask_speech(call_id, status_url, language="en-US", control_id=COLLECT_ID):
    """Collect one spoken answer, ended by 1.5 seconds of silence."""
    _needs_status_url(status_url)
    speech = {"end_silence_timeout": 1.5, "speech_timeout": 15, "language": language}
    return client.calling.collect(call_id, control_id=control_id, speech=speech,
                                  initial_timeout=10, start_input_timers=True,
                                  status_url=status_url)


def stop_collect(call_id, control_id=COLLECT_ID):
    """Give up waiting for input."""
    return client.calling.collect_stop(call_id, control_id=control_id)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    call_id = args[1] if len(args) > 1 else ""
    rest = args[2:]
    actions = {"say": say, "file": play_file, "stop": stop_playback,
               "volume": set_volume, "digits": ask_digits,
               "speech": ask_speech, "cancel": stop_collect}
    if cmd in actions and call_id:
        print(actions[cmd](call_id, *rest))
    else:
        print(__doc__)

/**
 * Play a prompt and collect digits or speech over REST.
 *
 * `calling.play` speaks text or plays a file into a live call,
 * `calling.play.stop` cuts it short, and `calling.collect` gathers keypad digits
 * or speech. Results do not come back in the HTTP response: the platform posts
 * them to the `status_url` you give, so a collect without one is refused here
 * before it is sent.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start say <call_id> "Please key in your account number"
 *     npm start digits <call_id> https://your-host/collect-events
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// one id per operation type; stop and collect.stop name them
export const PLAY_ID = "agent-desk-prompt";
export const COLLECT_ID = "agent-desk-input";

/** Speak `text` to the caller. Playback events go to statusUrl if given. */
export function say(callId: string, text: string, controlId = PLAY_ID,
                    statusUrl?: string) {
  const item = { type: "tts", params: { text } };
  const params: Record<string, unknown> = { control_id: controlId, play: [item] };
  if (statusUrl) {
    params["status_url"] = statusUrl;
  }
  return client.calling.play(callId, params);
}

/** Play an audio file from an HTTP(S) URL instead of speaking text. */
export function playFile(callId: string, url: string, controlId = PLAY_ID) {
  const item = { type: "audio", params: { url } };
  return client.calling.play(callId, { control_id: controlId, play: [item] });
}

/** Adjust a playing prompt, in dB. The spec's range is -40 to 40. */
export function setVolume(callId: string, volume: number, controlId = PLAY_ID) {
  if (!Number.isFinite(volume)) {
    // Number("loud") is NaN, and NaN fails every range comparison silently
    throw new Error(`volume must be a number of dB, not ${volume}`);
  }
  if (volume < -40 || volume > 40) {
    throw new Error(`volume must be between -40 and 40 dB, not ${volume}`);
  }
  return client.calling.playVolume(callId, { control_id: controlId, volume });
}

/** Cut the prompt short, for example when the caller starts keying digits. */
export function stopPlayback(callId: string, controlId = PLAY_ID) {
  return client.calling.playStop(callId, { control_id: controlId });
}

function needsStatusUrl(statusUrl: string | undefined): asserts statusUrl is string {
  // the result arrives only by webhook; without one the collect is unobservable
  if (!statusUrl) {
    throw new Error("a collect needs a status_url to deliver its result");
  }
}

/** Collect up to maxDigits keypad digits, ended early by #. */
export function askDigits(callId: string, statusUrl?: string, maxDigits = 10,
                          controlId = COLLECT_ID) {
  needsStatusUrl(statusUrl);
  const digits = { max: maxDigits, terminators: "#", digit_timeout: 5 };
  // start_input_timers defaults to false, and then initial_timeout never runs
  return client.calling.collect(callId, {
    control_id: controlId, digits, initial_timeout: 10,
    start_input_timers: true, status_url: statusUrl,
  });
}

/** Collect one spoken answer, ended by 1.5 seconds of silence. */
export function askSpeech(callId: string, statusUrl?: string, language = "en-US",
                          controlId = COLLECT_ID) {
  needsStatusUrl(statusUrl);
  const speech = { end_silence_timeout: 1.5, speech_timeout: 15, language };
  return client.calling.collect(callId, {
    control_id: controlId, speech, initial_timeout: 10,
    start_input_timers: true, status_url: statusUrl,
  });
}

/** Give up waiting for input. */
export function stopCollect(callId: string, controlId = COLLECT_ID) {
  return client.calling.collectStop(callId, { control_id: controlId });
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, arg] = process.argv.slice(2);
  if (!callId) {
    console.log("usage: npm start <say|file|stop|digits|speech|cancel> <call_id> [arg]");
  } else if (cmd === "say") {
    console.log(await say(callId, arg));
  } else if (cmd === "file") {
    console.log(await playFile(callId, arg));
  } else if (cmd === "stop") {
    console.log(await stopPlayback(callId));
  } else if (cmd === "volume") {
    console.log(await setVolume(callId, Number(arg)));
  } else if (cmd === "digits") {
    console.log(await askDigits(callId, arg));
  } else if (cmd === "speech") {
    console.log(await askSpeech(callId, arg));
  } else if (cmd === "cancel") {
    console.log(await stopCollect(callId));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py say <call_id> "Please key in your account number, then press pound."
python app.py digits <call_id> https://your-host/collect-events
python app.py speech <call_id> https://your-host/collect-events
python app.py volume <call_id> -6
python app.py stop <call_id>

The TypeScript surface is the same commands on @signalwire/sdk:

cd typescript
npm ci
cp ../.env.example .env
npm start digits <call_id> https://your-host/collect-events

Take the call id from a tool webhook, a status callback, or the dial response. The commands need no server of yours. The status_url does: it is where the collected digits or text arrive, so point it at a public route that logs the body.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, calls every helper, and asserts the following.

a collect with a missing or empty status URL raises before any request is made
each helper adds exactly one POST to the documented calling path
a play is sent with and without status_url, and the key is absent when it is not given
calling.play requires control_id and play, the item type enum is exactly the four types, and each item type is pinned to its own required param: text for tts, url for audio, duration for silence
the spec’s calling.play description names the four playback states, and its calling.collect description says results are delivered to the status_url webhook
calling.collect requires only control_id, digits requires max, and every sent digits and speech key is documented
the spec defaults start_input_timers to false, and both collects send true
the two stop commands require only control_id, and calling.play.volume requires the control id and a volume, with the range in the spec’s own text
a volume outside -40 to 40 raises before any request is made, as does one that is not a number, in both the value a caller passes and the string the command line hands over
each body equals the expected {"command", "id", "params"} shape, and every param is a documented property
the TypeScript surface sends those same seven bodies, and refuses a collect with no status URL before any request

Report an issue