hold | SignalWire

Put the call on hold. The caller hears hold music until the hold is released or the timeout expires.

During a hold, speech detection is paused and the agent doesn’t respond, so anything the caller needs to hear must be said before the hold takes effect. Passing prompt does that: it becomes the structured response’s tool_prompt (with tool_result: "status: on hold", see setToolResponse()) and turns on postProcess, so the model takes one more turn, and can tell the caller, before the hold runs.

step and timeoutStep move the call to a step when the hold ends: step when the call is taken off hold, timeoutStep when the hold times out. Unlike swmlChangeStep(), which applies at once, they wait for the hold to end. Omit one, and a hold that ends that way resumes in the current step. With neither, the action is the bare timeout ({ hold: 300 }); with either, it’s { hold: { timeout, step, timeout_step } }.

Parameters

prompt

string | number

Instruction for the model to act on before the hold. A number here is taken as timeout, so hold(120) sets a 120-second hold.

timeout

numberDefaults to 300

Maximum hold duration in seconds. Clamped to the range 0—900 (15 minutes max).

step

string

Step to move to when the call is taken off hold.

timeoutStep

string

Step to move to when the hold times out.

Returns

FunctionResult — this, for chaining.

Examples

Default 300-second hold

import { FunctionResult } from '@signalwire/sdk';
const result = new FunctionResult('Please hold.').hold();

Announce the hold and route what happens next

import { FunctionResult } from '@signalwire/sdk';
const result = new FunctionResult().hold(
  'Tell the caller you are checking whether a dispatcher is available.',
  300,
  'back_with_dispatcher',
  'take_a_message',
);