SurveyAgent | SignalWire

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

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.
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.

introMessage

stringDefaults to Thank you for taking our survey. I have a few questions for you.

Opening message before the first question.

completionMessage

stringDefaults to Thank you for completing the survey! Your responses have been recorded.

Message after the survey is complete.

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 SurveyAgent

Agent display name.

agentOptions

Partial<AgentOptions>

Additional AgentBase options forwarded to the constructor.

Built-in Tools

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

createSurveyAgent

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