> For the complete documentation index, see [llms.txt](https://docs.bird.com/applications/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/applications/channels/channels/supported-channels/sms/navigators.md).

# Navigators

## Navigators

*Intelligent Message Routing Guide*

## Overview

Navigators is a smart message routing feature that automatically selects the best channel to deliver your messages. Instead of sending through a single fixed channel, you define a pool of channels and let the Navigator choose the optimal one based on the recipient’s location, your routing policies, and message type — with automatic fallback to the next-best channel if delivery fails.

**Where to find it:** Navigators are configured and managed in the **Developer > Navigators** section of the dashboard.

## Why Use Navigators?

* **Maximize deliverability** — If one channel fails, the Navigator automatically retries on the next available channel.
* **Reach global audiences** — Route messages through channels with the best coverage for each destination country.
* **Optimize for cost or quality** — Configure policies that balance cost efficiency against delivery quality.
* **Support multiple use cases** — Send marketing, transactional, conversational, and OTP messages through channels appropriate for each type.
* **Simplify your integration** — Send all messages to a single Navigator endpoint; it handles the routing logic for you.

## How Navigators Work

{% stepper %}
{% step %}

### Country detection

The Navigator reads the recipient’s phone number to determine their country.
{% endstep %}

{% step %}

### Policy lookup

It finds the routing policy for that country (or falls back to a default policy).
{% endstep %}

{% step %}

### Channel selection

Based on coverage and policy, it builds an ordered list of channels to try.
{% endstep %}

{% step %}

### Delivery attempt

The message is sent through the first channel in the list.
{% endstep %}

{% step %}

### Fallback (if needed)

If that channel fails, the Navigator automatically tries the next one until the message is delivered or all options are exhausted.
{% endstep %}

{% step %}

### Status tracking

Every attempt is recorded, giving you full visibility into the message journey.
{% endstep %}
{% endstepper %}

## Navigator Types

Choose the Navigator type that matches your use case:

### Messaging Navigator

General-purpose routing across a configured pool of channels. The Navigator selects from available channels based on coverage and your policies. Use this when you need flexible, policy-driven routing without strict message-type constraints.

### Use-Case Navigator

Routes messages only through channels that support the specific use case you require. This ensures your marketing messages never route through a channel configured only for transactional traffic, and vice versa.

| **Use Case Type**  | **Typical Purpose**                        |
| ------------------ | ------------------------------------------ |
| **Marketing**      | Promotional campaigns, offers, newsletters |
| **Transactional**  | Order confirmations, receipts, alerts      |
| **Conversational** | Two-way customer interactions              |
| **OTP**            | One-time passwords, verification codes     |

### OTP Navigator

Optimized specifically for one-time password and verification messages where deliverability is the top priority. The OTP Navigator tries channels in strict order of reliability:

1. **OTP-designated channels** (highest priority)
2. Transactional channels
3. Conversational channels
4. Marketing channels (last resort)

Use this type when failed delivery is not acceptable.

## Coverage and Policies

### Coverage

Coverage defines which senders are available for each destination country. Each entry includes:

* **Sender identifier** — The number or name shown to your recipient.
* **Sender type** — Alphanumeric, long code, short code, toll-free, WhatsApp, or RCS.
* **Origin country** — Where the sender originates from.
* **Channel** — Which channel the sender belongs to.
* **Coverage quality** — Optimal or Lower quality, reflecting delivery reliability and cost.

You can view your Navigator’s coverage by selecting it in the dashboard and opening the **Coverage** tab.

### Policies

Policies control how the Navigator picks senders for a given destination. Each policy specifies:

* **Country code** — The destination country the policy applies to (or default for a global fallback).
* **Originator type** — The type of sender to prefer (e.g., short code for US, alphanumeric for EU).
* **Countries scope** — Whether the sender is native to the destination (native), foreign (other), or applies everywhere (all).
* **Coverage quality** — Whether to prefer optimal routes or also allow lower quality routes.

## Sending Messages Through a Navigator

Send messages to the Navigator’s API endpoint rather than directly to a channel:

```
POST /workspaces/{workspaceID}/navigators/{navigatorID}/messages
```

The request body follows the standard messaging format. The Navigator handles channel selection transparently — your application does not need to know which channel ultimately delivers the message.

To retrieve the status of a message sent through a Navigator:

```
GET /workspaces/{workspaceID}/navigators/{navigatorID}/messages/{messageID}
```

## Logs and Monitoring

The **Logs** tab for each Navigator gives you full visibility into every message routed through it. You can filter by:

* Date range
* Destination country
* Delivery status (accepted, sent, delivered, failed, etc.)
* Message tags

Each log entry shows:

* **All channel attempts** in order, including the sender and platform used for each.
* **Failure details** — If an attempt failed, the reason code and description are recorded.
* **Final status** — Whether the message was ultimately delivered or failed after all fallback options were exhausted.

This makes it straightforward to diagnose delivery issues and understand exactly how the Navigator routed a specific message.

## OTT Channels (WhatsApp, RCS)

Each Navigator supports up to one OTT (Over-the-Top) channel per platform — for example, one WhatsApp channel and one RCS channel. These are configured in the Navigator settings and are used when the policy and coverage indicate the recipient can be reached via that platform.

## Billing

Each channel attempt — including fallback attempts — is billed according to the rates of the channel used. If a message is retried on a second or third channel after an initial failure, each attempt is billed separately. Review your coverage quality settings to balance cost against the number of fallback attempts.

## Key Concepts at a Glance

| **Term**             | **Meaning**                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| **Navigator**        | A routing configuration that selects channels and manages fallback logic |
| **Coverage**         | The set of senders available for each destination country                |
| **Policy**           | Rules that determine which sender type and quality to prefer per country |
| **Attempt**          | A single delivery try through one channel                                |
| **Fallback**         | Automatic retry on the next channel when an attempt fails                |
| **Coverage quality** | Optimal (best reliability/cost) or Lower (reduced quality route)         |
| **Use case type**    | Category of message: Marketing, Transactional, Conversational, or OTP    |

## Getting Started

{% stepper %}
{% step %}

### Go to **Developer > Navigators** in the dashboard.

Go to **Developer > Navigators** in the dashboard.
{% endstep %}

{% step %}

### Click **Create Navigator** and select the type that fits your use case.

Click **Create Navigator** and select the type that fits your use case.
{% endstep %}

{% step %}

### Add the channels you want to include in the routing pool.

Add the channels you want to include in the routing pool.
{% endstep %}

{% step %}

### Configure policies for the countries you send to (add a default policy as a global fallback).

Configure policies for the countries you send to (add a default policy as a global fallback).
{% endstep %}

{% step %}

### Review the **Coverage** tab to confirm your target destinations are covered.

Review the **Coverage** tab to confirm your target destinations are covered.
{% endstep %}

{% step %}

### Update your API integration to send messages to the Navigator endpoint instead of directly to a channel.

Update your API integration to send messages to the Navigator endpoint instead of directly to a channel.
{% endstep %}

{% step %}

### Monitor delivery performance in the **Logs** tab.

Monitor delivery performance in the **Logs** tab.
{% endstep %}
{% endstepper %}

## Frequently Asked Questions

<details>

<summary>Can I use a Navigator for all message types?</summary>

Yes, though we recommend a Use-Case Navigator or OTP Navigator if you need to enforce that messages only route through channels appropriate for their type.

</details>

<details>

<summary>What happens if all channels fail?</summary>

The message is marked as failed once all channels in the routing list have been attempted. The Logs tab will show each attempt and the reason for failure.

</details>

<details>

<summary>How do I see which channel delivered my message?</summary>

Open the Logs tab, find the message, and expand the attempts. The successful attempt will show the channel and sender used.

</details>

<details>

<summary>Does adding more fallback channels guarantee delivery?</summary>

More fallback channels increase the likelihood of delivery, but cannot guarantee it — each channel is subject to its own carrier and platform constraints.

</details>

<details>

<summary>Are fallback attempts billed?</summary>

Yes. Each attempt is billed at the rate of the channel used, regardless of whether it succeeded or failed.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/applications/channels/channels/supported-channels/sms/navigators.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.