FAQ

How do I get a Nigerian phone number?

First browse the pool with GET /v1/numbers/available?type=geo_did&country_code=NG (valid type values: geo_did, mobile_virtual, intl_did, shortcode), then provision one with POST /v1/numbers and a body of { "number_id": "...", "agent_id": "...", "channels": ["voice", "sms"] }. To do both in one call, use POST /v1/numbers/auto, which claims the first available number matching your type + country_code and assigns it to the agent. Voicebip has numbers available from all four Nigerian MNOs (MTN, Glo, Airtel, and 9mobile). Once provisioned, the number is assigned to the agent and starts receiving calls and messages.

What happens when I call outside the call window?

The API returns a 422 CALL_WINDOW_RESTRICTED error. Configure call_window_start and call_window_end on your agent to control when calls are allowed. The default window is 08:00-20:00 Africa/Lagos. To allow calls at any time, set both fields to null.

How does MNO failover work?

Failover is automatic. Voicebip routes through MTN as the primary carrier, then falls over to Glo, Airtel, and 9mobile in sequence. The entire failover chain operates within a 5-second total budget. No developer action is needed — the platform handles routing and retries transparently.

What is sandbox mode?

Use a pk_test_ API key prefix instead of pk_live_. This activates sandbox mode where the full call and message lifecycle is simulated, complete with webhook events and valid HMAC signatures. No real SIP or SMPP connections are made, and no charges are incurred. Switch to production by swapping your API key prefix.

How do I verify webhook signatures?

Compute an HMAC-SHA256 hash of "{timestamp}.{body}" using your workspace signing_secret, where {timestamp} is the value from the X-Voicebip-Timestamp header (Unix seconds) and {body} is the raw request body. Convert the result to a hex digest and compare it to the value in the X-Voicebip-Signature header, which uses the format sha256={hex}. Always use a constant-time comparison function to prevent timing attacks, and reject deliveries where the timestamp is more than 5 minutes old to prevent replay attacks.

What LLMs can I use with BYOM mode?

Any LLM works with BYOM (Bring Your Own Model). OpenAI, Anthropic Claude, Cohere, Meta Llama, or a local model running on Ollama. Voicebip sends transcription events to your webhook endpoint. You call your LLM of choice and return a text response. The platform is completely model-agnostic.

What is conversation_history?

An array of the last 20 conversation turns included in every BYOM webhook event. Each entry has the format {role, text, timestamp}. This means you do not need to maintain your own session store — pass the array directly to your LLM as conversation context.

How is billing calculated?

Voicebip uses a prepaid balance model denominated in NGN kobo. Usage is charged against your balance according to your workspace tier and the applicable overage rates. Top up your balance via Paystack (NGN) or Stripe (USD) through the dashboard or the billing API.

What data residency does Voicebip use?

Voicebip applies NDPR cross-border data transfer safeguards to ensure compliance with Nigerian data protection regulations. Standard Contractual Clauses are handled automatically.

Can I record calls?

Yes, but only with explicit consent. Set recording_enabled on your agent, and enable recording at the workspace level via POST /v1/workspace/recording (both must be on). When enabled, a consent prompt plays at the start of each inbound call: the caller presses 1 to continue with recording or 2 to opt out. Recording only begins after the caller presses 1; no response within the consent timeout (~12 seconds) defaults to no recording. Calls where the caller does not consent proceed normally without recording. Setting consent_required: false on the agent skips the prompt and records immediately — only do this with an independent legal basis under NDPR.