Get Started

Nigeria Quick Start

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.

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:

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."
  }'
{
  "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:

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"]
  }'
{
  "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:

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"
  }'
{
  "agent_id": "agt_k7m2n9p4q1",
  "display_name": "Lagos Support Agent",
  "webhook_url": "https://your-server.com/voicebip/webhook",
  "updated_at": "2026-04-09T14:00:10Z"
}

For local development, use ngrok to expose your localhost. See the Testing Locally guide for full setup instructions.

Step 4: Test Your Setup

Verify your webhook handler works before making real calls:

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"
  }'
{
  "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:

curl -X GET "https://api.voicebip.com/v1/billing/balance" \
  -H "Authorization: Bearer pk_live_your_key"
{
  "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:

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