> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Survey

> Conduct automated surveys with different question types including rating, multiple choice, yes/no, and open-ended, with validation and response logging.

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

### Basic Usage

#### 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()
```

#### TypeScript

```typescript
import { SurveyAgent } from '@signalwire/sdk';

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();
```

### 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/sdk'` |

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

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

### Survey Flow

```mermaid
flowchart TD
    intro["Introduction"] --> ask["Ask question"]
    ask --> response["Get response"]
    response --> valid{"Valid?"}
    valid -->|yes| log["Log response"]
    valid -->|no| retry["Retry up to max_retries"]
    retry -->|valid| log
    retry -->|still invalid| fallback["Skip or ask again"]
    log & fallback --> more{"More questions?"}
    more -->|yes| ask
    more -->|no| conclusion["Conclusion"]
    conclusion --> summary["Generate summary"]
```

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