FAQ

How do I get a Nigerian phone number?

Send a POST /v1/numbers request with the desired number_type and country_code set to NG. Voicebip has numbers available from all four Nigerian MNOs (MTN, Glo, Airtel, and 9mobile). Once provisioned, assign the number to an agent to start 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, Google Gemini, 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 configuration. When enabled, a DTMF consent prompt plays at the start of each call asking the caller to press 1 to consent to recording. Recording only begins after the caller presses 1. Calls where the caller does not consent proceed normally without recording.