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

# Nigeria Quick Start

> Get a Lagos phone number and make your first AI-powered call in 30 seconds.

Get a Lagos DID and start receiving AI-powered calls in 30 seconds. This guide assumes you already have a Voicebip API key. If not, [create one here](https://app.voicebip.com/settings).

## Lagos Number in 30 Seconds

Voicebip gives your AI agent a real Lagos phone number in four API calls. By the end of this guide, anyone in Nigeria can call your number and talk to your AI agent.

## Step 1: Create an Agent

Create an AI agent that will handle calls on your Lagos number:

```bash
curl -X POST "https://api.voicebip.com/v1/agents" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Lagos Support Agent",
    "language": "en",
    "system_prompt": "You are a helpful customer support agent for a Lagos-based business. Be friendly and professional."
  }'
```

```json
{
  "agent_id": "agt_k7m2n9p4q1",
  "display_name": "Lagos Support Agent",
  "language": "en",
  "status": "active",
  "created_at": "2026-04-09T14:00:00Z"
}
```

Save the `agent_id` from the response -- you need it in the next steps.

## Step 2: Provision a Lagos DID

Get a geographic DID (landline-style number) in Lagos. The `/auto` endpoint picks the first available number matching your criteria in one call:

```bash
curl -X POST "https://api.voicebip.com/v1/numbers/auto" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_k7m2n9p4q1",
    "type": "geo_did",
    "country_code": "NG",
    "channels": ["voice"]
  }'
```

```json
{
  "number_id": "num_a1b2c3d4e5",
  "e164": "+2342011234567",
  "type": "geo_did",
  "agent_id": "agt_k7m2n9p4q1",
  "channels": ["voice"],
  "status": "provisioned",
  "mno": "mtn",
  "provisioned_at": "2026-04-09T14:00:05Z"
}
```

Your Lagos number is now live and assigned to your agent.

## Step 3: Configure Webhook

Set a webhook URL on your agent to receive real-time call events:

```bash
curl -X PATCH "https://api.voicebip.com/v1/agents/agt_k7m2n9p4q1" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/voicebip/webhook"
  }'
```

```json
{
  "agent_id": "agt_k7m2n9p4q1",
  "display_name": "Lagos Support Agent",
  "webhook_url": "https://your-server.com/voicebip/webhook",
  "updated_at": "2026-04-09T14:00:10Z"
}
```

> **Note**
>
> For local development, use [ngrok](https://ngrok.com) to expose your localhost. See the [Testing Locally](/reference/testing) guide for full setup instructions.

## Step 4: Test Your Setup

Verify your webhook handler works before making real calls:

```bash
curl -X POST "https://api.voicebip.com/v1/webhooks/test" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/voicebip/webhook",
    "event_type": "call.completed"
  }'
```

```json
{
  "success": true,
  "response_code": 200,
  "response_body": ""
}
```

If `success` is `true` and `response_code` is `200`, your webhook handler is ready. The test event arrives with a valid `X-Voicebip-Signature` header so your signature verification code is tested too.

## Step 5: Call Your Number

Pick up your phone and dial the Lagos number from the Step 2 response (e.g. `+2342011234567`). Your AI agent answers, and you receive these webhook events in real time:

1. **`call.initiated`** -- the call is ringing
2. **`call.transcription`** -- real-time transcript segments as the conversation progresses
3. **`call.completed`** -- final summary with duration, full transcript, recording URL, and `ai_mode`

That is it. Your Lagos AI agent is live.

## Nigerian Tips

### Naira Billing

All charges are in **Nigerian Naira (NGN)**, expressed in **kobo** (100 kobo = 1 NGN). Check your workspace balance at any time:

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

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

Fund your workspace via Paystack (card, bank transfer, USSD) with `POST /v1/billing/checkout`.

### MNO Failover

Voicebip automatically routes calls through all four Nigerian MNOs with a 5-second failover budget:

**MTN** (primary) --> **Glo** (secondary) --> **Airtel** (tertiary) --> **9mobile** (quaternary)

No configuration needed. Failover happens automatically based on the destination number's prefix.

### CBN Call Windows

Outbound calls are restricted to **08:00 - 20:00 WAT** by default (CBN regulation). Customize per agent:

```bash
curl -X PATCH "https://api.voicebip.com/v1/agents/agt_k7m2n9p4q1" \
  -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"
  }'
```

Calls outside the window return `422 CALL_WINDOW_RESTRICTED`. Inbound calls are never restricted.

### Sandbox Testing

Use a `pk_test_` API key to test everything above with zero charges. Sandbox numbers (`+234800000xxxx`, `+234100000xxxx`) simulate the full call and SMS lifecycle without touching real MNO infrastructure.

## What's Next

* [Nigerian Developer Guide](/reference/nigerian-developer-guide) -- MNO prefix routing, NDPR compliance, CBN regulations, and Naira billing details
* [Testing Locally](/reference/testing-locally) -- ngrok setup, mock payloads, and webhook signature verification
* [Webhooks Guide](/guides/webhooks) -- event types, retry logic, and delivery monitoring
* [Voice Calls Guide](/guides/voice-calls) -- inbound/outbound calls, real-time transcription, and recording