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

# Smart Routing

> Automatic channel selection that reduces costs up to 80%

Smart Routing is Zavu's system that automatically selects the optimal channel for each message, maximizing delivery rates while minimizing costs.

<Note>
  **Smart routing only applies to outbound messages.** When replying to an inbound message, Zavu always responds on the **same channel** the contact used.
</Note>

## When Smart Routing Applies

| Message Type                        | Routing Behavior                      |
| ----------------------------------- | ------------------------------------- |
| **Outbound** (you initiate)         | Smart routing selects optimal channel |
| **Inbound reply** (direct response) | Always use the contact's channel      |

## How It Works

For outbound messages, the router checks if the contact has previously messaged you:

```
Has contact messaged via WhatsApp in last 24h?
      |
   +--+--+
   |     |
  Yes   No
   |     |
   v     v
WhatsApp    WhatsApp only
available   with template
(preferred)
```

Since WhatsApp is cheaper than SMS, the router **prefers WhatsApp when the 24-hour window is open**.

## Channel Selection Algorithm

The router evaluates channels in this order:

1. **Filter viable channels**: Remove channels that can't deliver (e.g., WhatsApp without open window)
2. **Sort by cost**: Cheapest channels first
3. **Check success rate**: Channel must have at least 80% success rate (or fewer than 3 attempts for exploration)
4. **Select best option**: First channel meeting all criteria

## Cost Optimization

| Channel  | Approximate Cost |
| -------- | ---------------- |
| WhatsApp | \~\$0.01/message |
| SMS      | \~\$0.05/message |

Smart routing can reduce messaging costs by **up to 80%** by preferring WhatsApp when available.

## WhatsApp 24-Hour Window

WhatsApp has a strict rule: you can only send free-form messages within **24 hours** of the last message received from the contact.

```
Contact sends message ... 24-hour window opens
      |
Within 24h: Send any message type
      |
After 24h: Only template messages allowed
```

<Warning>
  If the 24-hour window is closed and you don't have a template configured, the smart router will automatically select SMS instead of failing.
</Warning>

## Channel Metrics

Zavu tracks delivery metrics for each contact and channel:

```json theme={null}
{
  "channelMetrics": {
    "sms": {
      "successCount": 45,
      "failureCount": 2,
      "avgDeliveryTimeMs": 3200,
      "lastSuccessAt": "2025-01-15T10:30:00Z"
    },
    "whatsapp": {
      "successCount": 120,
      "failureCount": 1,
      "avgDeliveryTimeMs": 1100,
      "lastSuccessAt": "2025-01-15T14:22:00Z"
    }
  }
}
```

The router uses these metrics to:

* Avoid channels with low success rates (below 80%)
* Prefer faster channels when speed matters
* Explore new channels (first 3 attempts get a chance regardless of stats)

## Automatic Fallback

When a message fails on one channel, Zavu **automatically retries** on an alternate channel.

### Fallback Flow

```
Send via WhatsApp
      |
      v
  Failed?
      |
   +--+--+
   |     |
  No    Yes
   |     |
   v     v
Done   Wait 5s
         |
         v
   Retry via SMS
         |
         v
     Success?
         |
      +--+--+
      |     |
     Yes   No
      |     |
      v     v
   Done   Mark Failed
```

### Fallback Rules

| Rule                     | Description                                                |
| ------------------------ | ---------------------------------------------------------- |
| Max 2 attempts           | Each message is tried on at most 2 channels                |
| 5-second delay           | Wait 5 seconds before retry to avoid race conditions       |
| No duplicate channels    | Never retry on a channel that already failed               |
| Sender must support both | Fallback only works if sender has both channels configured |

### Tracking Fallback

Messages track which channels have been attempted:

```json theme={null}
{
  "id": "msg_abc123",
  "status": "delivered",
  "channel": "sms",
  "attemptedChannels": ["whatsapp", "sms"],
  "fallbackEnabled": true
}
```

In this example, the message first tried WhatsApp, failed, and was successfully delivered via SMS.

## Manual Override

To bypass Smart Routing for a specific message, specify the channel explicitly:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await zavu.messages.send({
    to: "+56912345678",
    text: "This must go via SMS",
    channel: "sms"
  });
  ```

  ```python Python theme={null}
  zavu.messages.send(
      to="+56912345678",
      text="This must go via SMS",
      channel="sms"
  )
  ```

  ```ruby Ruby theme={null}
  client.messages.send(
    to: "+56912345678",
    text: "This must go via SMS",
    channel: "sms"
  )
  ```

  ```go Go theme={null}
  client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("+56912345678"),
  	Text:    zavudev.String("This must go via SMS"),
  	Channel: zavudev.String("sms"),
  })
  ```

  ```php PHP theme={null}
  <?php
  $client->messages->send([
      'to' => '+56912345678',
      'text' => 'This must go via SMS',
      'channel' => 'sms',
  ]);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+56912345678",
      "text": "This must go via SMS",
      "channel": "sms"
    }'
  ```
</CodeGroup>

<Tip>
  You can optionally specify a sender by passing `zavuSender` (TypeScript), `zavu_sender` (Python), or the `Zavu-Sender` header (cURL). If omitted, your project's default sender is used.
</Tip>

## Best Practices

<CardGroup cols={2}>
  <Card title="Configure Multiple Channels" icon="layer-group">
    Set up both SMS and WhatsApp on your sender to enable automatic fallback.
  </Card>

  <Card title="Use Templates for Outreach" icon="file-lines">
    When initiating conversations, use WhatsApp templates to avoid 24-hour window issues.
  </Card>

  <Card title="Monitor Metrics" icon="chart-line">
    Check your contact metrics to understand channel performance in your region.
  </Card>

  <Card title="Keep Numbers Updated" icon="phone">
    Invalid numbers waste attempts across all channels.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Senders" icon="id-card" href="/concepts/senders">
    Learn more about sender configuration
  </Card>

  <Card title="WhatsApp Templates" icon="whatsapp" href="/guides/whatsapp/templates/sending">
    Create templates for outbound messaging
  </Card>
</CardGroup>