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

# Pathways

> Design conversation flows and decision logic for your agents

# Pathways

Pathways are the conversation flows that guide how your agents interact with users. They define the logic, branching, and actions that occur during a conversation.

## What Are Pathways?

A Pathway is a visual or code-defined flow that determines:

* What questions the agent asks
* How it responds to user input
* When to take actions (book appointment, transfer call)
* When to escalate to a human

```
Start
  ↓
Greeting
  ↓
Identify Intent → Appointment? → Collect Details → Book → Confirm
                → Question? → Search KB → Answer
                → Transfer? → Route Call
                → Other → Fallback
```

## Pathway Components

### Nodes

Nodes are the building blocks of pathways:

| Node Type     | Description                      |
| ------------- | -------------------------------- |
| **Start**     | Entry point of the conversation  |
| **Message**   | Agent speaks or sends text       |
| **Listen**    | Waits for user input             |
| **Condition** | Branches based on logic          |
| **Action**    | Triggers external action         |
| **Transfer**  | Routes to human or another agent |
| **End**       | Terminates the conversation      |

### Conditions

Conditions control conversation branching:

```javascript theme={null}
// Intent-based
if (intent === "book_appointment") {
  goto("collect_appointment_details");
}

// Keyword-based
if (userInput.includes("emergency")) {
  goto("escalate_to_human");
}

// Data-based
if (customer.hasAppointment) {
  goto("existing_appointment_flow");
}
```

### Actions

Actions trigger external operations:

* **API Call** — Send data to external systems
* **Book Appointment** — Create calendar entries
* **Send SMS** — Dispatch text messages
* **Update CRM** — Modify customer records
* **Transfer Call** — Route to human agents

## Creating Pathways

### Visual Builder

The visual builder provides a drag-and-drop interface:

<Steps>
  <Step title="Open Pathway Editor">
    Navigate to your Crew and select **Pathways**
  </Step>

  <Step title="Add Start Node">
    Every pathway begins with a Start node
  </Step>

  <Step title="Build Flow">
    Drag nodes onto the canvas and connect them
  </Step>

  <Step title="Configure Nodes">
    Set messages, conditions, and actions for each node
  </Step>

  <Step title="Test">
    Use the simulator to test your pathway
  </Step>
</Steps>

### Code Definition

For complex logic, define pathways in code:

```json theme={null}
{
  "id": "appointment_booking",
  "name": "Appointment Booking Flow",
  "nodes": [
    {
      "id": "start",
      "type": "start",
      "next": "greeting"
    },
    {
      "id": "greeting",
      "type": "message",
      "content": "Hi, I can help you schedule an appointment. What day works best for you?",
      "next": "collect_date"
    },
    {
      "id": "collect_date",
      "type": "listen",
      "variable": "appointment_date",
      "next": "collect_time"
    },
    {
      "id": "collect_time",
      "type": "message",
      "content": "Great, and what time would you prefer?",
      "next": "listen_time"
    }
  ]
}
```

## Common Patterns

### Intent Classification

Route conversations based on user intent:

```
Listen → Classify Intent
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
Schedule  Question  Transfer
```

### Information Collection

Gather required data before taking action:

```
Ask Name → Store → Ask Phone → Store → Ask Email → Store → Confirm All
```

### Escalation Flow

Gracefully hand off to humans:

```
Detect Escalation Trigger
        ↓
Check Agent Availability
        ↓
    Available? ─→ Warm Transfer
        ↓
    Unavailable → Collect Callback Info → Promise Follow-up
```

### FAQ Handling

Search and respond from knowledge base:

```
User Question → Search KB → Found? → Deliver Answer
                              ↓
                           Not Found → Apologize → Offer Transfer
```

## Variables and Context

Pathways maintain conversation context:

```javascript theme={null}
// Set variables
context.customerName = "John";
context.appointmentDate = "2024-01-15";

// Use in messages
"Great, {{customerName}}, I've booked you for {{appointmentDate}}."
```

### Built-in Variables

| Variable         | Description                      |
| ---------------- | -------------------------------- |
| `caller_number`  | Phone number of the caller       |
| `call_duration`  | How long the call has lasted     |
| `current_time`   | Current timestamp                |
| `agent_name`     | Name of the active agent         |
| `transfer_count` | Number of transfers in this call |

## Testing Pathways

### Simulator

Test pathways without making real calls:

1. Open the Pathway Editor
2. Click **Simulate**
3. Type responses as if you were the user
4. Verify the agent follows expected paths

### Staging Environment

Deploy pathways to a staging Crew before production:

```
Development → Test → Staging → Validate → Production
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the happy path">
    Design the ideal conversation first, then add error handling.
  </Accordion>

  <Accordion title="Keep it shallow">
    Avoid deeply nested pathways. If a branch is complex, create a sub-pathway.
  </Accordion>

  <Accordion title="Always provide exits">
    Users should always be able to reach a human or end the call.
  </Accordion>

  <Accordion title="Handle the unexpected">
    Add catch-all nodes for unrecognized input.
  </Accordion>

  <Accordion title="Test with real users">
    Simulate real scenarios, including edge cases and mistakes.
  </Accordion>
</AccordionGroup>

## Pathway Limits

| Plan         | Pathways  | Nodes per Pathway |
| ------------ | --------- | ----------------- |
| Starter      | 5         | 50                |
| Professional | 25        | 200               |
| Enterprise   | Unlimited | Unlimited         |

## Next Steps

* [AI Receptionist](/voice/ai-receptionist) — Apply pathways to voice agents
* [Custom Code Nodes](/developer/custom-code-nodes) — Add custom logic
* [Webhooks](/integrations/webhooks) — Trigger external actions