SurveyAgent

Conducts surveys with support for multiple question types, conditional branching based on answers, per-answer scoring, and a completion callback. The agent guides the caller through each question, validates answers, and tracks progress per call.

1 import { SurveyAgent } from '@signalwire/sdk';
2 
3 const agent = new SurveyAgent({ /* SurveyConfig */ });

SurveyConfig

surveyName

stringRequired

Human-readable survey name used in prompts and global data.

questions

SurveyQuestion[]Required

Ordered list of survey questions. Each SurveyQuestion object has:

id (string, required) — Unique question identifier.
text (string, required) — The question text to ask the caller.
type (string, required) — One of "multiple_choice", "open_ended", "rating", or "yes_no".
options (string[]) — Required for multiple_choice questions.
scale (number, default 5) — For rating questions, the upper bound of the scale (1..scale).
required (boolean, default true) — Whether the question must be answered.
nextQuestion (string | Record<string, string>) — Next question ID, or a map from answer value to next question ID for branching. If omitted, proceeds in array order.
points (number | Record<string, number>) — Fixed points for any answer, or per-answer scoring map.

introduction

string

Opening message before the first question. Defaults to a generic intro.

conclusion

string

Closing message spoken after the survey completes.

brandName

stringDefaults to "Our Company"

Brand or company name the agent represents. Used in prompt sections.

maxRetries

numberDefaults to 2

Maximum number of times to retry invalid answers before moving on.

onComplete

(responses: Record<string, unknown>, score: number) => void | Promise<void>

Callback fired when the survey is finished. Receives all responses and the total score.

name

stringDefaults to "survey"

Agent display name.

route

stringDefaults to "/survey"

HTTP route for the agent.

agentOptions

Partial<AgentOptions>

Additional AgentBase options forwarded to the constructor.

Built-in Tools

Tool	Description	Parameters
`validate_response`	Validate a response against the question’s type and rules without advancing	`question_id` (string), `response` (string)
`log_response`	Log a validated response to the session without scoring or advancing	`question_id` (string), `response` (string)
`answer_question`	Record the caller’s answer, validate it, apply scoring, and advance to the next question	`question_id` (string), `answer` (string)
`get_current_question`	Get the current question that should be asked	(none)
`get_survey_progress`	Get progress stats: questions answered, total score, and answer history	(none)

Branching and Scoring

Questions support conditional branching via the nextQuestion property. When set to a Record<string, string>, the agent routes to different follow-up questions based on the caller’s answer. Use the key "_default" as a fallback branch.

Scoring is configured via the points property. A fixed number awards the same points for any answer. A Record<string, number> awards different points per answer value.

Example

1 import { SurveyAgent } from '@signalwire/sdk';
2 
3 const agent = new SurveyAgent({
4   surveyName: 'Product Feedback',
5   brandName: 'Acme Corporation',
6   introduction: 'Thank you for purchasing our product. We\'d love your feedback!',
7   conclusion: 'Thanks for your time. Your feedback helps us improve!',
8   questions: [
9     {
10       id: 'overall_rating',
11       text: 'On a scale of 1 to 10, how would you rate the product overall?',
12       type: 'rating',
13       points: { '9': 3, '10': 3, '7': 2, '8': 2 },
14     },
15     {
16       id: 'quality',
17       text: 'How would you rate the build quality?',
18       type: 'multiple_choice',
19       options: ['Poor', 'Fair', 'Good', 'Excellent'],
20       points: { 'Excellent': 3, 'Good': 2, 'Fair': 1, 'Poor': 0 },
21     },
22     {
23       id: 'purchase_again',
24       text: 'Would you purchase from us again?',
25       type: 'yes_no',
26       nextQuestion: {
27         yes: 'recommend',
28         no: 'improvements',
29       },
30     },
31     {
32       id: 'recommend',
33       text: 'Would you recommend us to a friend?',
34       type: 'yes_no',
35     },
36     {
37       id: 'improvements',
38       text: 'What could we improve?',
39       type: 'open_ended',
40     },
41   ],
42   onComplete: (responses, score) => {
43     console.log('Survey complete:', { responses, score });
44   },
45 });
46 
47 agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' });
48 
49 agent.serve();

createSurveyAgent

1 import { createSurveyAgent } from '@signalwire/sdk';
2 
3 const agent = createSurveyAgent({
4   surveyName: 'Quick Feedback',
5   questions: [
6     { id: 'q1', text: 'How was your experience?', type: 'rating' },
7     { id: 'q2', text: 'Any comments?', type: 'open_ended' },
8   ],
9 });

1	import { SurveyAgent } from '@signalwire/sdk';
2
3	const agent = new SurveyAgent({ /* SurveyConfig */ });

1	import { SurveyAgent } from '@signalwire/sdk';
2
3	const agent = new SurveyAgent({
4	surveyName: 'Product Feedback',
5	brandName: 'Acme Corporation',
6	introduction: 'Thank you for purchasing our product. We\'d love your feedback!',
7	conclusion: 'Thanks for your time. Your feedback helps us improve!',
8	questions: [
9	{
10	id: 'overall_rating',
11	text: 'On a scale of 1 to 10, how would you rate the product overall?',
12	type: 'rating',
13	points: { '9': 3, '10': 3, '7': 2, '8': 2 },
14	},
15	{
16	id: 'quality',
17	text: 'How would you rate the build quality?',
18	type: 'multiple_choice',
19	options: ['Poor', 'Fair', 'Good', 'Excellent'],
20	points: { 'Excellent': 3, 'Good': 2, 'Fair': 1, 'Poor': 0 },
21	},
22	{
23	id: 'purchase_again',
24	text: 'Would you purchase from us again?',
25	type: 'yes_no',
26	nextQuestion: {
27	yes: 'recommend',
28	no: 'improvements',
29	},
30	},
31	{
32	id: 'recommend',
33	text: 'Would you recommend us to a friend?',
34	type: 'yes_no',
35	},
36	{
37	id: 'improvements',
38	text: 'What could we improve?',
39	type: 'open_ended',
40	},
41	],
42	onComplete: (responses, score) => {
43	console.log('Survey complete:', { responses, score });
44	},
45	});
46
47	agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' });
48
49	agent.serve();

1	import { createSurveyAgent } from '@signalwire/sdk';
2
3	const agent = createSurveyAgent({
4	surveyName: 'Quick Feedback',
5	questions: [
6	{ id: 'q1', text: 'How was your experience?', type: 'rating' },
7	{ id: 'q2', text: 'Any comments?', type: 'open_ended' },
8	],
9	});