Survey | SignalWire

SurveyAgent conducts automated surveys with different question types (rating, multiple choice, yes/no, open-ended), validation, and response logging.

Basic Usage

Python

TypeScript

1 from signalwire.prefabs import SurveyAgent
2 
3 agent = SurveyAgent(
4     survey_name="Customer Satisfaction Survey",
5     questions=[
6         {
7             "id": "satisfaction",
8             "text": "How satisfied were you with our service?",
9             "type": "rating",
10             "scale": 5
11         },
12         {
13             "id": "recommend",
14             "text": "Would you recommend us to others?",
15             "type": "yes_no"
16         },
17         {
18             "id": "comments",
19             "text": "Any additional comments?",
20             "type": "open_ended",
21             "required": False
22         }
23     ]
24 )
25 
26 if __name__ == "__main__":
27     agent.run()

Question Types

Type	Fields	Example
`rating`	scale (1-10)	“Rate 1-5, where 5 is best”
`multiple_choice`	options (list)	“Choose: Poor, Fair, Good, Excellent”
`yes_no`	(none)	“Would you recommend us?”
`open_ended`	(none)	“Any comments?”

Question Format

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the question
`text`	string	Yes	The question to ask
`type`	string	Yes	rating, multiple_choice, yes_no, open_ended
`options`	list[string]	*	Required for multiple_choice
`scale`	integer	No	For rating (default: 5)
`required`	boolean	No	Is answer required (default: true)

Importing SurveyAgent

Language	Import
Python	`from signalwire.prefabs import SurveyAgent`
TypeScript	`import { SurveyAgent } from 'signalwire-agents'`

Constructor Parameters

1 SurveyAgent(
2     survey_name="...",         # Name of the survey (required)
3     questions=[...],           # List of question dictionaries (required)
4     introduction=None,         # Custom intro message
5     conclusion=None,           # Custom conclusion message
6     brand_name=None,           # Company/brand name
7     max_retries=2,             # Retries for invalid answers
8     name="survey",             # Agent name
9     route="/survey",           # HTTP route
10     **kwargs                   # Additional AgentBase arguments
11 )

Built-in Functions

SurveyAgent provides these SWAIG functions automatically:

Function	Description
`validate_response`	Check if response is valid for question type
`log_response`	Record a validated response

Survey handlers return FunctionResult(string) objects (not plain dicts). If extending SurveyAgent with custom handlers, always return a FunctionResult.

Survey Flow

Complete Example

1 #!/usr/bin/env python3
2 ## product_survey.py - Product feedback survey agent
3 from signalwire.prefabs import SurveyAgent
4 
5 agent = SurveyAgent(
6     survey_name="Product Feedback Survey",
7     brand_name="TechGadgets Inc.",
8     introduction="Thank you for purchasing our product. We'd love your feedback!",
9     conclusion="Thank you for completing our survey. Your input helps us improve.",
10     questions=[
11         {
12             "id": "overall_rating",
13             "text": "How would you rate the product overall?",
14             "type": "rating",
15             "scale": 5,
16             "required": True
17         },
18         {
19             "id": "quality",
20             "text": "How would you rate the build quality?",
21             "type": "multiple_choice",
22             "options": ["Poor", "Fair", "Good", "Excellent"],
23             "required": True
24         },
25         {
26             "id": "purchase_again",
27             "text": "Would you purchase from us again?",
28             "type": "yes_no",
29             "required": True
30         },
31         {
32             "id": "improvements",
33             "text": "What could we improve?",
34             "type": "open_ended",
35             "required": False
36         }
37     ],
38     max_retries=2
39 )
40 
41 if __name__ == "__main__":
42     agent.add_language("English", "en-US", "rime.spore")
43     agent.run()

Best Practices

Question Design

Keep surveys short (5-7 questions max)
Start with easy questions
Put open-ended questions at the end
Make non-essential questions optional

Question Types

Use rating for satisfaction metrics (NPS, CSAT)
Use multiple_choice for specific options
Use yes_no for simple binary questions
Use open_ended sparingly — harder to analyze

Validation

Set appropriate max_retries (2-3)
Use clear scale descriptions
List all options for multiple choice