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

1

Country detection

The Navigator reads the recipient’s phone number to determine their country.

2

Policy lookup

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

3

Channel selection

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

4

Delivery attempt

The message is sent through the first channel in the list.

5

Fallback (if needed)

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

6

Status tracking

Every attempt is recorded, giving you full visibility into the message journey.

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

1

Go to Developer > Navigators in the dashboard.

Go to Developer > Navigators in the dashboard.

2

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

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

3

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

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

4

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).

5

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

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

6

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.

7

Monitor delivery performance in the Logs tab.

Monitor delivery performance in the Logs tab.

Frequently Asked Questions

Can I use a Navigator for all message types?

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.

What happens if all channels fail?

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.

How do I see which channel delivered my message?

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

Does adding more fallback channels guarantee delivery?

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

Are fallback attempts billed?

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