***

title: Survey
description: Conduct automated surveys with different question types including rating, multiple choice, yes/no, and open-ended, with validation and response logging.
slug: /guides/survey
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

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

### Basic Usage

<Tabs>
  <Tab title="Python">
    ```python
    from signalwire.prefabs import SurveyAgent

    agent = SurveyAgent(
        survey_name="Customer Satisfaction Survey",
        questions=[
            {
                "id": "satisfaction",
                "text": "How satisfied were you with our service?",
                "type": "rating",
                "scale": 5
            },
            {
                "id": "recommend",
                "text": "Would you recommend us to others?",
                "type": "yes_no"
            },
            {
                "id": "comments",
                "text": "Any additional comments?",
                "type": "open_ended",
                "required": False
            }
        ]
    )

    if __name__ == "__main__":
        agent.run()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript
    import { SurveyAgent } from 'signalwire-agents';

    const agent = new SurveyAgent({
      surveyName: 'Customer Satisfaction Survey',
      questions: [
        { id: 'satisfaction', text: 'How satisfied were you with our service?', type: 'rating', scale: 5 },
        { id: 'recommend', text: 'Would you recommend us to others?', type: 'yes_no' },
        { id: 'comments', text: 'Any additional comments?', type: 'open_ended', required: false },
      ],
    });

    agent.run();
    ```
  </Tab>
</Tabs>

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

```python
SurveyAgent(
    survey_name="...",         # Name of the survey (required)
    questions=[...],           # List of question dictionaries (required)
    introduction=None,         # Custom intro message
    conclusion=None,           # Custom conclusion message
    brand_name=None,           # Company/brand name
    max_retries=2,             # Retries for invalid answers
    name="survey",             # Agent name
    route="/survey",           # HTTP route
    **kwargs                   # Additional AgentBase arguments
)
```

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

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

### Survey Flow

<Frame caption="Survey agent conversation flow.">
  <img class="diagram" src="https://files.buildwithfern.com/signalwire.docs.buildwithfern.com/docs/8c3e04622071a3ec1035779582fc1cacf025209794fe245daae781edd8366d01/assets/images/sdks/diagrams/09_03_survey_diagram1.webp" alt="Diagram showing the survey flow from introduction through question presentation, validation, and conclusion." />
</Frame>

### Complete Example

```python
#!/usr/bin/env python3
## product_survey.py - Product feedback survey agent
from signalwire.prefabs import SurveyAgent

agent = SurveyAgent(
    survey_name="Product Feedback Survey",
    brand_name="TechGadgets Inc.",
    introduction="Thank you for purchasing our product. We'd love your feedback!",
    conclusion="Thank you for completing our survey. Your input helps us improve.",
    questions=[
        {
            "id": "overall_rating",
            "text": "How would you rate the product overall?",
            "type": "rating",
            "scale": 5,
            "required": True
        },
        {
            "id": "quality",
            "text": "How would you rate the build quality?",
            "type": "multiple_choice",
            "options": ["Poor", "Fair", "Good", "Excellent"],
            "required": True
        },
        {
            "id": "purchase_again",
            "text": "Would you purchase from us again?",
            "type": "yes_no",
            "required": True
        },
        {
            "id": "improvements",
            "text": "What could we improve?",
            "type": "open_ended",
            "required": False
        }
    ],
    max_retries=2
)

if __name__ == "__main__":
    agent.add_language("English", "en-US", "rime.spore")
    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