GatherInfo & GatherQuestion

GatherInfo and GatherQuestion provide structured information gathering within context steps. Instead of relying on LLM tool calls, the gather system uses dynamic step instruction re-injection to present questions one at a time, producing zero tool_call/tool_result entries in the LLM-visible history.

Answers are stored in global_data and can be referenced by subsequent steps or tools.

1 import { ContextBuilder } from '@signalwire/sdk';

GatherInfo is typically configured through the Step.setGatherInfo() and Step.addGatherQuestion() methods rather than instantiated directly.

GatherQuestion

Represents a single question in a gather_info configuration. Each question defines a key for storing the answer, the question text, and optional validation and confirmation settings.

key

stringRequired

Key name for storing the answer in global_data. Must be unique within a single GatherInfo configuration.

question

stringRequired

The question text to present to the user.

type

stringDefaults to string

Expected answer type. Valid values:

"string" — free-form text
"number" — numeric value
"boolean" — yes/no
"integer" — whole number

confirm

booleanDefaults to false

When true, the model must confirm the answer with the user before submitting it.

prompt

string

Extra instruction text appended to the step prompt when this specific question is active. Use this to give the model additional context for asking or validating this question.

functions

string[]

Additional SWAIG function names to make visible while this question is active. Useful when a question requires tool access (e.g., a lookup function to validate an account number).

toDict

Convert the question to a dictionary for SWML generation. Fields with default values are omitted from the output.

Returns

Record<string, unknown>

GatherInfo

Configuration for gathering multiple pieces of information in a step. Wraps a list of GatherQuestion objects and controls how answers are stored and what happens after all questions are answered.

outputKey

string

Key in global_data under which to nest all answers. When undefined, answers are stored at the top level of global_data using each question’s key.

completionAction

string

Where to navigate after all questions have been answered. Valid values:

undefined — return to normal step mode
"next_step" — auto-advance to the next sequential step in the context
A step name (e.g., "process_results") — jump to that specific step

prompt

string

Preamble text injected once when entering the gather step. Gives the model personality and context for why it is asking these questions.

addQuestion

Add a question to the gather configuration. Returns this for method chaining.

Parameters

opts.key

stringRequired

Key name for storing the answer in global_data.

opts.question

stringRequired

The question text to ask.

opts.type

stringDefaults to string

Answer type: "string", "number", "boolean", "integer".

opts.confirm

booleanDefaults to false

Whether to confirm the answer with the user.

opts.prompt

string

Extra instruction text for this question.

opts.functions

string[]

SWAIG function names available during this question.

Returns

GatherInfo — self, for method chaining.

toDict

Convert the gather configuration to a dictionary for SWML generation. Throws an error if no questions have been added.

Returns

Record<string, unknown>

Example

The typical pattern is to use GatherInfo through the Step API:

1 import { ContextBuilder } from '@signalwire/sdk';
2 
3 const builder = new ContextBuilder();
4 const ctx = builder.addContext('default');
5 
6 // Configure gather info on a step
7 ctx.addStep('intake')
8   .setText('Collect the caller\'s information.')
9   .setGatherInfo({
10     outputKey: 'caller_info',
11     completionAction: 'next_step',
12     prompt: 'You are a friendly receptionist collecting basic info.',
13   })
14   .addGatherQuestion({ key: 'name', question: 'What is your full name?', confirm: true })
15   .addGatherQuestion({ key: 'phone', question: 'What is your callback number?', type: 'string' })
16   .addGatherQuestion({ key: 'reason', question: 'What is the reason for your call?' });
17 
18 ctx.addStep('process')
19   .setText('Thank the caller and summarize what was collected.');

You can also use GatherInfo directly:

1 import { GatherInfo } from '@signalwire/sdk';
2 
3 const gather = new GatherInfo({ outputKey: 'patient_info', completionAction: 'next_step' });
4 gather.addQuestion({ key: 'dob', question: 'What is your date of birth?', type: 'string', confirm: true });
5 gather.addQuestion({ key: 'allergies', question: 'Do you have any allergies?' });

1	import { ContextBuilder } from '@signalwire/sdk';
2
3	const builder = new ContextBuilder();
4	const ctx = builder.addContext('default');
5
6	// Configure gather info on a step
7	ctx.addStep('intake')
8	.setText('Collect the caller\'s information.')
9	.setGatherInfo({
10	outputKey: 'caller_info',
11	completionAction: 'next_step',
12	prompt: 'You are a friendly receptionist collecting basic info.',
13	})
14	.addGatherQuestion({ key: 'name', question: 'What is your full name?', confirm: true })
15	.addGatherQuestion({ key: 'phone', question: 'What is your callback number?', type: 'string' })
16	.addGatherQuestion({ key: 'reason', question: 'What is the reason for your call?' });
17
18	ctx.addStep('process')
19	.setText('Thank the caller and summarize what was collected.');

1	import { GatherInfo } from '@signalwire/sdk';
2
3	const gather = new GatherInfo({ outputKey: 'patient_info', completionAction: 'next_step' });
4	gather.addQuestion({ key: 'dob', question: 'What is your date of birth?', type: 'string', confirm: true });
5	gather.addQuestion({ key: 'allergies', question: 'Do you have any allergies?' });