> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Nigerian Developer Guide

> MNO prefix routing, NDPR data protection compliance, CBN call window regulations, and Naira billing for Nigerian telecom infrastructure.

Everything you need to know about building on Nigerian telecom infrastructure with Voicebip, including MNO routing, CBN regulations, NDPR compliance, and Naira billing.

## MNO Prefix Routing

Voicebip routes calls and SMS to the correct Mobile Network Operator based on the destination number's prefix. The platform handles this automatically -- you send a valid E.164 Nigerian number and Voicebip picks the right MNO.

| MNO         | Prefixes                                       | Market Share    |
| ----------- | ---------------------------------------------- | --------------- |
| **MTN**     | 0803, 0806, 0703, 0706, 0813, 0816, 0810, 0814 | Largest network |
| **Glo**     | 0805, 0807, 0705, 0815, 0811                   | Second largest  |
| **Airtel**  | 0802, 0808, 0708, 0812                         | Third largest   |
| **9mobile** | 0809, 0817, 0818, 0908, 0909                   | Fourth largest  |

> **Note**
>
> Numbers with unrecognized prefixes default to **MTN** as the fallback carrier. This covers ported numbers and newly allocated NCC prefix blocks.

All phone numbers must be submitted in E.164 format (`+234XXXXXXXXXX`). The prefix table above shows local format for reference -- Voicebip strips the `+234` and reads the next three or four digits to determine the MNO.

### How Prefix Routing Works

When you place a call or send a message to `+2348031234567`:

1. Voicebip strips `+234` to get `8031234567`
2. Reads prefix `0803` (MTN)
3. Routes through the MTN interconnect
4. If MTN fails, failover kicks in (see below)

No developer action is needed. Routing is fully automatic.

## MNO Failover

When the primary MNO route fails (network congestion, SMSC down, SIP timeout), Voicebip automatically attempts the next carrier in the failover chain:

| Priority | Carrier     | Role       |
| -------- | ----------- | ---------- |
| 1        | **MTN**     | Primary    |
| 2        | **Glo**     | Secondary  |
| 3        | **Airtel**  | Tertiary   |
| 4        | **9mobile** | Quaternary |

The total failover budget is **5 seconds**. If all four carriers fail within this window, the API returns a `CALL_FAILED` or `MESSAGE_FAILED` error. Your webhook receives the failure event with details about which routes were attempted.

Failover is fully automatic. You do not need to configure anything or handle retries yourself. The `mno_used` field in `call.completed` events tells you which carrier ultimately handled the call. If all routes fail, the API returns a `CALL_FAILED` or `MESSAGE_FAILED` error and a `call.completed` event is fired with `status: "failed"`.

## CBN Call Window Rules

The Central Bank of Nigeria (CBN) restricts outbound telemarketing and financial service calls to specific hours. Voicebip enforces these rules at the API level.

### Default Window

All outbound calls are restricted to **08:00 - 20:00 WAT** (West Africa Time, `Africa/Lagos`, UTC+1) by default.

### Configuring Per-Agent Windows

You can customize the call window per agent using three fields:

| Field                  | Type   | Default          | Description                                             |
| ---------------------- | ------ | ---------------- | ------------------------------------------------------- |
| `call_window_start`    | string | `"08:00"`        | Earliest time outbound calls are allowed (HH:MM format) |
| `call_window_end`      | string | `"20:00"`        | Latest time outbound calls are allowed (HH:MM format)   |
| `call_window_timezone` | string | `"Africa/Lagos"` | IANA timezone for the call window                       |

```bash
curl -X PATCH "https://api.voicebip.com/v1/agents/agt_abc123" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "call_window_start": "09:00",
    "call_window_end": "18:00",
    "call_window_timezone": "Africa/Lagos"
  }'
```

### Outside-Window Behavior

Outbound calls initiated outside the configured window return **HTTP 422** with error code `CALL_WINDOW_RESTRICTED`:

```json
{
  "error_code": "CALL_WINDOW_RESTRICTED",
  "message": "Outbound calls are restricted to 09:00-18:00 Africa/Lagos. Current time: 21:14 WAT.",
  "request_id": "req_m8k2v5",
  "documentation_url": "https://docs.voicebip.com/errors/CALL_WINDOW_RESTRICTED"
}
```

> **Warning**
>
> Inbound calls are **not** restricted by the call window. Your agent will still receive and handle inbound calls at any hour.

## Pre-Call Announcement

The CBN requires financial service agents to identify the institution at the start of every outbound call. Configure this via the `pre_call_announcement` field on the agent:

```bash
curl -X PATCH "https://api.voicebip.com/v1/agents/agt_abc123" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pre_call_announcement": "This call is from First National Microfinance Bank, regulated by the Central Bank of Nigeria."
  }'
```

When set, Voicebip plays this announcement via TTS before the AI agent begins the conversation. The announcement appears in the call transcript with speaker label `system`:

```json
{
  "speaker": "system",
  "text": "This call is from First National Microfinance Bank, regulated by the Central Bank of Nigeria.",
  "start_ms": 0,
  "end_ms": 3200
}
```

The greeting message from your agent follows immediately after the pre-call announcement finishes playing.

## NDPR Compliance Checklist

The Nigeria Data Protection Regulation (NDPR) governs how personal data is collected, stored, and processed. Voicebip provides built-in compliance features to help you meet NDPR requirements.

* **Data residency** -- NDPR cross-border data transfer safeguards apply. Voicebip handles the required Standard Contractual Clauses automatically.
* **Data retention** -- 90-day default retention for call recordings, transcripts, and message content. Configurable per workspace down to 30 days or up to 365 days.
* **Consent management** -- Record consent status per phone number. Voicebip blocks outbound messages to numbers with `consent: false`.
* **STOP opt-out** -- Inbound SMS containing "STOP" automatically sets `consent: false` for that number and fires a `message.opt_out` webhook event. The recipient is added to the workspace opt-out list and subsequent `POST /v1/messages` calls to that number return `422 OPT_OUT_ENFORCED`.
* **DPA acceptance** -- Your workspace must accept the Data Processing Agreement before making production API calls. Accept programmatically with `POST /v1/dpa/accept`.
* **Breach notification** -- Voicebip commits to notifying affected workspaces within 72 hours of a confirmed data breach, in compliance with NDPR Article 2.11.

### Accept the DPA

```bash
curl -X POST "https://api.voicebip.com/v1/dpa/accept" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"version": "1.0"}'
```

```json
{
  "accepted": true,
  "version": "1.0",
  "accepted_at": "2026-04-09T14:30:00Z"
}
```

> **Warning**
>
> Production API calls (calls, SMS, WhatsApp) return `403 PERMISSION_DENIED` until the DPA is accepted. Sandbox mode works without DPA acceptance.

## Naira Billing

All charges for Nigerian operations are denominated in **Nigerian Naira (NGN)** and expressed in **kobo** (1 NGN = 100 kobo) to avoid floating-point precision issues.

| Resource                             | Unit        | Example Rate (Starter / PAYG)                                           |
| ------------------------------------ | ----------- | ----------------------------------------------------------------------- |
| Voice — BYOM (your webhook)          | per minute  | ₦50/min (Starter), ₦70/min (PAYG)                                       |
| Voice — Hosted AI                    | per minute  | ₦80/min (Starter), ₦100/min (PAYG)                                      |
| SMS (outbound)                       | per segment | ₦15/segment (1,500 kobo, Starter), ₦20/segment (PAYG)                   |
| SMS (inbound)                        | per message | ₦15/message (1,500 kobo, Starter), ₦20/message (PAYG)                   |
| Phone number (DID or mobile virtual) | per month   | 500,000 kobo/month (₦5,000, Starter), 600,000 kobo/month (₦6,000, PAYG) |

> **Note**
>
> These are illustrative seeded rates and are subject to change — always read live pricing from the billing API rather than hardcoding these values.

### Check Your Balance

```bash
curl -X GET "https://api.voicebip.com/v1/billing/balance" \
  -H "Authorization: Bearer pk_live_your_key"
```

```json
{
  "workspace_id": "ws_PAEZ",
  "balance_kobo": 4250000,
  "currency": "NGN"
}
```