Nigerian Developer Guide

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.

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:

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:

$
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:

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

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:

$
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:

1
{
2
  "speaker": "system",
3
  "text": "This call is from First National Microfinance Bank, regulated by the Central Bank of Nigeria.",
4
  "start_ms": 0,
5
  "end_ms": 3200
6
}

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

$
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"}'

1
{
2
  "accepted": true,
3
  "version": "1.0",
4
  "accepted_at": "2026-04-09T14:30:00Z"
5
}

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.

Check Your Balance

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

1
{
2
  "workspace_id": "ws_PAEZ",
3
  "balance_kobo": 4250000,
4
  "currency": "NGN"
5
}