> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloannie.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Define multi-step processes for complex interactions

Workflows define multi-step processes your agent can execute. Unlike FAQs (which are single question-answer pairs), workflows handle complex interactions with branching logic.

**Use workflows for:**

* Appointment scheduling
* Patient intake collection
* Multi-step qualification processes
* Anything requiring back-and-forth conversation

## Example: Creating a Workflow

Here's how to create a basic workflow using the API:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/bots/YOUR_BOT_ID/workflows",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        title: "Collect Patient Information",
        description: "Gathers basic patient details for new callers",
        enabled: true,
        steps: [
          {
            title: "Get Name",
            order: 0,
            description: null,
            instructions: "Ask for the patient's full name.",
            examples: [
              "Can I get your full name?",
              "What name should I have on file?"
            ]
          },
          {
            title: "Get Date of Birth",
            order: 1,
            description: null,
            instructions: "Ask for the patient's date of birth to verify their identity.",
            examples: [
              "And what's your date of birth?",
              "Can you confirm your birthday for me?"
            ]
          },
          {
            title: "Get Reason for Call",
            order: 2,
            description: null,
            instructions: "Ask why they're calling today.",
            examples: [
              "How can I help you today?",
              "What are you calling about?"
            ]
          }
        ]
      })
    }
  )

  const { data } = await response.json()
  console.log(data.workflow)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helloannie.com/v1/bots/YOUR_BOT_ID/workflows \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Collect Patient Information",
      "description": "Gathers basic patient details for new callers",
      "enabled": true,
      "steps": [
        {
          "title": "Get Name",
          "order": 0,
          "description": null,
          "instructions": "Ask for the patient'\''s full name.",
          "examples": ["Can I get your full name?", "What name should I have on file?"]
        },
        {
          "title": "Get Date of Birth",
          "order": 1,
          "description": null,
          "instructions": "Ask for the patient'\''s date of birth to verify their identity.",
          "examples": ["And what'\''s your date of birth?", "Can you confirm your birthday for me?"]
        },
        {
          "title": "Get Reason for Call",
          "order": 2,
          "description": null,
          "instructions": "Ask why they'\''re calling today.",
          "examples": ["How can I help you today?", "What are you calling about?"]
        }
      ]
    }'
  ```
</CodeGroup>

Realistically, you'll want to add more steps to handle the full interaction, such as additional qualifying questions or follow-up steps. You can add more steps to the workflow as needed.

## Workflow Structure

Each step has:

* **title** — What the step is called
* **description** — Optional description of the step (can be `null`)
* **instructions** — Guidance for Annie on what to do
* **examples** — Sample phrases Annie might use
* **order** — The sequence of steps (starting at 0)
* **action** — Optional action tool to execute
* **actionMetadata** — Optional metadata for the action
* **childSteps** — Optional nested steps for branching logic

### A Note on Actions

Actions allow Annie to perform tasks during a workflow step, such as searching for appointments, booking, or transferring calls. Actions integrate with your practice management system to execute real operations.

<Warning>
  **Actions are not yet fully documented.** We recommend testing workflows without actions (non-scheduling use cases) until more documentation is released on configuring custom actions that integrate with your systems.
</Warning>

### `TRANSFER_CALL`

`TRANSFER_CALL` supports either a saved `forwardingNumberId` or inline transfer metadata. The inline form accepts `name`, `phoneNumber`, and an optional `extension`.

```json theme={null}
{
  "title": "Transfer to Front Desk",
  "order": 0,
  "description": null,
  "instructions": "If the caller asks for a human, transfer them to the front desk.",
  "action": "TRANSFER_CALL",
  "actionMetadata": {
    "name": "Front Desk",
    "phoneNumber": "+15551234567",
    "extension": "w123#"
  }
}
```

The `extension` field is optional. It supports DTMF characters `0-9`, `*`, `#`, `A-D`, `w`, and `W`. In templated workflows, you can also use `{{variable}}` placeholders for the extension.

## Listing Workflows

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.helloannie.com/v1/bots/YOUR_BOT_ID/workflows",
    {
      headers: { "Authorization": "Bearer YOUR_API_KEY" }
    }
  )

  const { data } = await response.json()
  // data.workflows contains an array of workflow objects
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.helloannie.com/v1/bots/YOUR_BOT_ID/workflows",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  data = response.json()["data"]
  # data["workflows"] contains an array of workflow objects
  ```

  ```bash cURL theme={null}
  curl https://api.helloannie.com/v1/bots/YOUR_BOT_ID/workflows \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

<Info>
  Workflows are powerful but complex to configure from scratch. We recommend starting with **templates**, which give you pre-built workflows you can customize.
</Info>

***

<Card title="Workflows API" icon="code" href="/api-reference/workflows/list-workflows">
  See the full API reference for workflow endpoints.
</Card>