# Voicebip | Documentation

## Instructions for AI Agents

- For clean Markdown of any page, append `.md` to the page URL
- For section-specific indexes, append `/llms.txt` to any section URL
- For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server

## Docs

- [Introduction](https://docs.voicebip.com/get-started/welcome.md): Voicebip is the developer platform for giving AI agents real Nigerian phone numbers, WhatsApp, and SMS — through a single API.
- [Authentication](https://docs.voicebip.com/get-started/authentication.md): How to authenticate with the Voicebip API using API keys.
- [Nigeria Quick Start](https://docs.voicebip.com/get-started/quickstart.md): Get a Lagos phone number and make your first AI-powered call in 30 seconds.
- [Agent Templates](https://docs.voicebip.com/guides/templates.md): Create production-ready agents in seconds using pre-built templates for common Nigerian business use cases.
- [Agents](https://docs.voicebip.com/guides/agents.md): Create and manage AI agents that own phone numbers and handle communications.
- [Workspace](https://docs.voicebip.com/guides/workspace.md): Read and update your workspace settings, and permanently delete a workspace.
- [BYOM (Bring Your Own Model)](https://docs.voicebip.com/guides/byom.md): Plug your own LLM or agent logic into Voicebip calls via a single webhook endpoint.
- [Knowledge Base](https://docs.voicebip.com/guides/knowledge-base.md): Give your agents grounded answers with retrieval-augmented generation (RAG) — upload documents, attach them to an agent, and Voicebip retrieves the most relevant passages on every turn.
- [Phone Numbers](https://docs.voicebip.com/guides/phone-numbers.md): Provision Nigerian DIDs, mobile virtual numbers, and international numbers for your agents.
- [Multi-Agent Routing](https://docs.voicebip.com/guides/routing.md): Route inbound calls on a single phone number to different specialized agents based on caller intent.
- [Voice Calls](https://docs.voicebip.com/guides/voice-calls.md): Build AI-powered voice agents with real-time transcription and text-to-speech.
- [Call Control](https://docs.voicebip.com/guides/call-control.md): Real-time control of active voice calls
- [Campaigns](https://docs.voicebip.com/guides/campaigns.md): Paced outbound campaigns — reach a list of recipients over voice, SMS, or WhatsApp at a controlled, carrier-safe rate
- [Recording Playback](https://docs.voicebip.com/guides/recordings.md): Access and play back call recordings via the API with range-request support.
- [Browser Calls (WebRTC)](https://docs.voicebip.com/guides/browser-calls.md): Make voice calls to your AI agent directly from the browser using WebRTC.
- [Shareable Links](https://docs.voicebip.com/guides/shareable-links.md): Generate public "try my agent" links that let anyone test-call your AI agent from a browser.
- [Analytics](https://docs.voicebip.com/guides/analytics.md): Track call resolution rates, voice quality (MOS), and conversation trends across your workspace.
- [SMS](https://docs.voicebip.com/guides/sms.md): Send and receive SMS messages through direct SMPP connections to Nigerian MNOs.
- [WhatsApp](https://docs.voicebip.com/guides/whatsapp.md): Send WhatsApp messages and templates through the Voicebip API.
- [Conversations](https://docs.voicebip.com/guides/conversations.md): List, inspect, hand off, and stream messaging conversations across SMS and WhatsApp.
- [Webhooks](https://docs.voicebip.com/guides/webhooks.md): Receive real-time events for calls, messages, and deliveries with HMAC-SHA256 signature verification.
- [Usage & Billing](https://docs.voicebip.com/guides/usage-billing.md): Monitor usage, understand pricing tiers, and manage billing with Paystack (NGN).
- [Plans & Tier Switching](https://docs.voicebip.com/guides/plans-tier-switching.md): Inspect your subscription, switch between Starter / Builder / Scale mid-period with proration, and understand quota carryover.
- [Contact Erasure (NDPR Right to Erasure)](https://docs.voicebip.com/guides/contact-erasure.md): How to permanently anonymize a phone number's data using DELETE /v1/contacts/{e164}.
- [Use Cases](https://docs.voicebip.com/use-cases/use-cases.md): End-to-end recipes that combine Voicebip primitives into a working thing — an answered support line, an outbound reminder campaign, a WhatsApp agent. Each page is copy-paste runnable against the sandbox.
- [Inbound Support Agent + Knowledge Base](https://docs.voicebip.com/use-cases/inbound-support-kb.md): Provision a Nigerian number bound to a hosted-AI agent grounded in your own docs, and it answers callers 24/7 — no call centre, no code for the answering itself.
- [Voice Agent with Tool-Calling](https://docs.voicebip.com/use-cases/tool-calling.md): Go from a chatbot-on-the-phone to an agent that does things — recognises intent mid-call, calls your backend through a tool, and speaks the result ("your order ships tomorrow").
- [WhatsApp AI Agent](https://docs.voicebip.com/use-cases/whatsapp-agent.md): An AI agent that holds a full WhatsApp conversation — answers questions, sends a template to open the window, hands off to a human. The channel most of Nigeria actually uses.
- [Outbound Reminder Campaign](https://docs.voicebip.com/use-cases/reminder-campaign.md): Upload a list, run an outbound voice or SMS campaign that confirms appointments or payments, and tally the results — the classic "reach everyone before tomorrow" flow.
- [Verification Call-back (Voice OTP)](https://docs.voicebip.com/use-cases/verification-callback.md): Trigger an outbound call that reads a one-time code (or confirms an action). The "call me to verify" pattern — reliable where SMS delivery is flaky.
- [Knowledge Base Deep-Dive](https://docs.voicebip.com/use-cases/knowledge-base-deep-dive.md): Everything the KB primitive does on its own — ingest documents, poll status, tune retrieval, and query for relevant chunks *without* a call. RAG search as a standalone capability.
- [Campaigns Deep-Dive](https://docs.voicebip.com/use-cases/campaigns-deep-dive.md): The outbound orchestrator as a primitive — full lifecycle, per-recipient params, retries, counters, and the webhook reference flow for tracking every target.
- [Multi-Agent Routing](https://docs.voicebip.com/use-cases/multi-agent-routing.md): One number, many specialised agents. Route each caller to the right agent by what they say — "sales" vs "support" — using keyword or regex rules with a catch-all default.
- [Bring Your Own Model (BYOM)](https://docs.voicebip.com/use-cases/byom-custom-llm.md): Voicebip handles telephony, STT, TTS, and barge-in while your endpoint runs the LLM. Full control over the model and prompt, zero lock-in.
- [Multi-Channel Cascade](https://docs.voicebip.com/use-cases/multi-channel-cascade.md): Reach a contact by voice; if they don't pick up, fall back to SMS, then WhatsApp — automatically. The cross-channel outreach neither voice-only tool can do.
- [Browser Voice Widget](https://docs.voicebip.com/use-cases/browser-widget.md): Put a "Talk to our agent" button on any web page. The visitor speaks to your agent from the browser over WebRTC — no phone number dialled, no app installed.
- [Drive Voicebip from an AI Assistant (MCP)](https://docs.voicebip.com/use-cases/mcp-tour.md): Connect the Voicebip MCP server and let an AI assistant (Claude, Cursor, any MCP client) provision numbers, build agents, launch campaigns, and read analytics — conversationally.
- [Error Codes](https://docs.voicebip.com/reference/error-codes.md): Complete reference of Voicebip API error codes, HTTP status mappings, and troubleshooting guidance.
- [Pagination](https://docs.voicebip.com/reference/pagination.md): How to paginate through list endpoints using cursor-based pagination.
- [Rate Limits](https://docs.voicebip.com/reference/rate-limits.md): Per-workspace rate limits by tier and how to handle 429 responses.
- [Live Streaming (SSE & WebSocket)](https://docs.voicebip.com/reference/streaming.md): Real-time streams for call transcripts, call events, and conversation messages. Use SSE for browsers and WebSocket for low-latency audio paths.
- [Testing Locally](https://docs.voicebip.com/reference/testing.md): Sandbox mode, mock webhook payloads, signature verification, and local development with ngrok.
- [Code Examples](https://docs.voicebip.com/reference/code-examples.md): Production-ready webhook handlers in Express.js, Flask, Go, and Next.js, plus LLM integration examples with OpenAI and Claude.
- [Nigerian Developer Guide](https://docs.voicebip.com/reference/nigeria-guide.md): MNO prefix routing, NDPR data protection compliance, CBN call window regulations, and Naira billing for Nigerian telecom infrastructure.
- [Best Practices](https://docs.voicebip.com/reference/best-practices.md): Latency optimization, Nigerian network tips, NDPR compliance, and error handling best practices for Voicebip integrations.
- [DPA Compliance](https://docs.voicebip.com/reference/dpa-compliance.md): NDPR Data Processing Agreement for Voicebip developers.
- [Sandbox Mode](https://docs.voicebip.com/reference/sandbox-mode.md): Test your integration without real phone calls or SMS charges.
- [FAQ](https://docs.voicebip.com/reference/faq.md): Frequently asked questions
- [Changelog](https://docs.voicebip.com/changelog/release-history.md): Release history
- [Terms of Service](https://docs.voicebip.com/legal/terms.md): The terms governing access to and use of the Voicebip platform, API, dashboard, and SDKs.
- [Privacy Policy](https://docs.voicebip.com/legal/privacy.md): How Voicebip collects, uses, shares, and protects personal data under the NDPA and NDPR.
- [TypeScript / JavaScript SDK](https://docs.voicebip.com/integrations/sdks/typescript.md): Install and use the @voicebip/sdk npm package.
- [Python SDK](https://docs.voicebip.com/integrations/sdks/python.md): Install and use the voicebip Python package.
- [Go SDK](https://docs.voicebip.com/integrations/sdks/go.md): Install and use the voicebip-go module — auto-generated from the OpenAPI spec via Fern.
- [@voicebip/web — Browser SDK](https://docs.voicebip.com/integrations/sdks/web.md): Embed a live AI voice call in any web page in 10 lines of JavaScript.
- [MCP Server — Overview & Setup](https://docs.voicebip.com/integrations/mcp/overview.md): Use Voicebip from Cursor, Claude Desktop, or any MCP-compatible AI tool.

## API Docs

- API Reference > System [Exchange an API key for a short-lived JWT](https://docs.voicebip.com/api/system/create-session.md)
- API Reference > System [API health check](https://docs.voicebip.com/api/system/health-check.md)
- API Reference > System [Create a new user account and workspace](https://docs.voicebip.com/api/system/signup.md)
- API Reference > System [Confirm a signup verification token](https://docs.voicebip.com/api/system/verify-email.md)
- API Reference > System [Exchange email + password for a JWT](https://docs.voicebip.com/api/system/login.md)
- API Reference > System [Request a password reset email](https://docs.voicebip.com/api/system/forgot-password.md)
- API Reference > System [Consume a reset token and set a new password](https://docs.voicebip.com/api/system/reset-password.md)
- API Reference > System [Get authenticated user and workspace](https://docs.voicebip.com/api/system/get-auth-me.md)
- API Reference > System [Revoke all active sessions](https://docs.voicebip.com/api/system/logout-all.md)
- API Reference > System [Permanently delete user account](https://docs.voicebip.com/api/system/delete-account.md)
- API Reference > Templates [List agent templates](https://docs.voicebip.com/api/templates/list-templates.md)
- API Reference > Agents [List agents](https://docs.voicebip.com/api/agents/list-agents.md)
- API Reference > Agents [Create an agent](https://docs.voicebip.com/api/agents/create-agent.md)
- API Reference > Agents [Get an agent](https://docs.voicebip.com/api/agents/get-agent.md)
- API Reference > Agents [Delete an agent](https://docs.voicebip.com/api/agents/delete-agent.md)
- API Reference > Agents [Update an agent](https://docs.voicebip.com/api/agents/update-agent.md)
- API Reference > Agents [Toggle shareable flag on an agent](https://docs.voicebip.com/api/agents/toggle-agent-shareable.md)
- API Reference > Agents [Export agent conversations](https://docs.voicebip.com/api/agents/export-conversations.md)
- API Reference > Agents [Chat with an agent (text mode)](https://docs.voicebip.com/api/agents/agent-playground.md)
- API Reference > Agents [List available AI models](https://docs.voicebip.com/api/agents/list-ai-models.md)
- API Reference > API Keys [List API keys](https://docs.voicebip.com/api/api-keys/list-api-keys.md)
- API Reference > API Keys [Create an API key](https://docs.voicebip.com/api/api-keys/create-api-key.md)
- API Reference > API Keys [Revoke an API key](https://docs.voicebip.com/api/api-keys/revoke-api-key.md)
- API Reference > API Keys [Rotate an API key](https://docs.voicebip.com/api/api-keys/rotate-api-key.md)
- API Reference > Numbers [List available numbers](https://docs.voicebip.com/api/numbers/list-available-numbers.md)
- API Reference > Numbers [List numbers owned by the workspace](https://docs.voicebip.com/api/numbers/list-numbers.md)
- API Reference > Numbers [Provision a number](https://docs.voicebip.com/api/numbers/provision-number.md)
- API Reference > Numbers [Claim the first available number matching criteria](https://docs.voicebip.com/api/numbers/auto-provision-number.md)
- API Reference > Numbers [Get a number](https://docs.voicebip.com/api/numbers/get-number.md)
- API Reference > Numbers [Release a number](https://docs.voicebip.com/api/numbers/release-number.md)
- API Reference > Numbers [Reclaim a quarantined number](https://docs.voicebip.com/api/numbers/reclaim-number.md)
- API Reference > Calls [List calls in the workspace](https://docs.voicebip.com/api/calls/list-calls.md)
- API Reference > Calls [Initiate an outbound call](https://docs.voicebip.com/api/calls/initiate-call.md)
- API Reference > Calls [Get call details](https://docs.voicebip.com/api/calls/get-call.md)
- API Reference > Calls [End a call](https://docs.voicebip.com/api/calls/end-call.md)
- API Reference > Calls [Get call recording audio](https://docs.voicebip.com/api/calls/get-call-recording.md)
- API Reference > Calls [Put a call on hold](https://docs.voicebip.com/api/calls/hold-call.md)
- API Reference > Calls [Resume a held call](https://docs.voicebip.com/api/calls/resume-call.md)
- API Reference > Calls [Transfer a call to another number](https://docs.voicebip.com/api/calls/transfer-call.md)
- API Reference > Calls [Inject DTMF tones into a call](https://docs.voicebip.com/api/calls/send-dtmf.md)
- API Reference > Calls [Stream real-time call events via WebSocket](https://docs.voicebip.com/api/calls/stream-call.md)
- API Reference > Calls [Stream real-time call transcript via SSE](https://docs.voicebip.com/api/calls/stream-call-transcript.md)
- API Reference > Calls [List available TTS voice IDs](https://docs.voicebip.com/api/calls/list-voice-models.md)
- API Reference > Campaigns [List campaigns in the workspace](https://docs.voicebip.com/api/campaigns/list-campaigns.md)
- API Reference > Campaigns [Create a campaign](https://docs.voicebip.com/api/campaigns/create-campaign.md)
- API Reference > Campaigns [Get a campaign](https://docs.voicebip.com/api/campaigns/get-campaign.md)
- API Reference > Campaigns [Start a campaign](https://docs.voicebip.com/api/campaigns/start-campaign.md)
- API Reference > Campaigns [Pause a running campaign](https://docs.voicebip.com/api/campaigns/pause-campaign.md)
- API Reference > Campaigns [Resume a paused campaign](https://docs.voicebip.com/api/campaigns/resume-campaign.md)
- API Reference > Campaigns [Cancel a campaign](https://docs.voicebip.com/api/campaigns/cancel-campaign.md)
- API Reference > Campaigns [Retry a campaign's failed recipients](https://docs.voicebip.com/api/campaigns/retry-failed-campaign.md)
- API Reference > Campaigns [List a campaign's targets](https://docs.voicebip.com/api/campaigns/list-campaign-targets.md)
- API Reference > Campaigns [Add recipients to a campaign](https://docs.voicebip.com/api/campaigns/add-campaign-targets.md)
- API Reference > Analytics [Get workspace analytics](https://docs.voicebip.com/api/analytics/get-analytics.md)
- API Reference > Routing [List routing rules](https://docs.voicebip.com/api/routing/list-routing-rules.md)
- API Reference > Routing [Create a routing rule](https://docs.voicebip.com/api/routing/create-routing-rule.md)
- API Reference > Routing [Update a routing rule](https://docs.voicebip.com/api/routing/update-routing-rule.md)
- API Reference > Routing [Delete a routing rule](https://docs.voicebip.com/api/routing/delete-routing-rule.md)
- API Reference > Public [Public shareable agent landing-page metadata](https://docs.voicebip.com/api/public/try-agent-info.md)
- API Reference > Public [WebRTC signaling for shareable agent links](https://docs.voicebip.com/api/public/try-agent-offer.md)
- API Reference > Web Rtc [Mint a scoped token for a browser call](https://docs.voicebip.com/api/web-rtc/create-web-rtc-token.md)
- API Reference > Web Rtc [Submit a WebRTC SDP offer for an authenticated browser call](https://docs.voicebip.com/api/web-rtc/create-web-rtc-offer.md)
- API Reference > Messages [Send a message (SMS or WhatsApp)](https://docs.voicebip.com/api/messages/send-message.md)
- API Reference > Messages [Send a WhatsApp template message](https://docs.voicebip.com/api/messages/send-template.md)
- API Reference > Messages [Get a single message](https://docs.voicebip.com/api/messages/get-message.md)
- API Reference > Messages [Get conversation with message history](https://docs.voicebip.com/api/messages/get-conversation.md)
- API Reference > Messages [Transition a conversation's AI mode](https://docs.voicebip.com/api/messages/set-conversation-mode.md)
- API Reference > Messages [Stream real-time conversation events via SSE](https://docs.voicebip.com/api/messages/stream-conversation.md)
- API Reference > Webhooks [Send a test webhook event](https://docs.voicebip.com/api/webhooks/test-webhook.md)
- API Reference > Webhooks [List webhook delivery attempts](https://docs.voicebip.com/api/webhooks/list-webhook-deliveries.md)
- API Reference > Webhooks [Get a single webhook delivery](https://docs.voicebip.com/api/webhooks/get-webhook-delivery.md)
- API Reference > Webhooks [Re-drive events from the webhook dead-letter queue](https://docs.voicebip.com/api/webhooks/replay-dlq.md)
- API Reference > Webhooks [List webhook endpoints for an agent](https://docs.voicebip.com/api/webhooks/list-webhook-endpoints.md)
- API Reference > Webhooks [Register a new webhook endpoint](https://docs.voicebip.com/api/webhooks/create-webhook-endpoint.md)
- API Reference > Webhooks [Delete a webhook endpoint](https://docs.voicebip.com/api/webhooks/delete-webhook-endpoint.md)
- API Reference > Webhooks [Enable or disable a webhook endpoint](https://docs.voicebip.com/api/webhooks/update-webhook-endpoint.md)
- API Reference > Billing [Get usage for current billing period](https://docs.voicebip.com/api/billing/get-usage.md)
- API Reference > Billing [Get workspace prepaid balance](https://docs.voicebip.com/api/billing/get-balance.md)
- API Reference > Billing [Initiate a Paystack payment to top up balance](https://docs.voicebip.com/api/billing/create-checkout.md)
- API Reference > Billing [Stripe payment webhook (signature-verified, no auth)](https://docs.voicebip.com/api/billing/stripe-webhook.md)
- API Reference > Compliance [Accept the NDPR Data Processing Agreement](https://docs.voicebip.com/api/compliance/accept-dpa.md)
- API Reference > Compliance [Check DPA acceptance status](https://docs.voicebip.com/api/compliance/get-dpa-status.md)
- API Reference > Compliance [Erase all PII for a phone number (NDPR right to erasure)](https://docs.voicebip.com/api/compliance/erase-contact.md)
- API Reference > Workspace [Get the caller's workspace](https://docs.voicebip.com/api/workspace/get-workspace.md)
- API Reference > Workspace [Permanently delete the workspace](https://docs.voicebip.com/api/workspace/delete-workspace.md)
- API Reference > Workspace [Update workspace settings](https://docs.voicebip.com/api/workspace/update-workspace.md)
- API Reference > Workspace [Rotate the workspace HMAC signing secret](https://docs.voicebip.com/api/workspace/rotate-signing-secret.md)
- API Reference > Workspace [Get the caller workspace's active subscription](https://docs.voicebip.com/api/workspace/get-subscription.md)
- API Reference > Workspace [Change the subscription plan (tier switch with proration)](https://docs.voicebip.com/api/workspace/update-subscription.md)
- API Reference > Messaging [List WhatsApp and SMS conversations in the workspace](https://docs.voicebip.com/api/messaging/list-conversations.md)
- API Reference > Knowledge Bases [List knowledge bases](https://docs.voicebip.com/api/knowledge-bases/list-knowledge-bases.md)
- API Reference > Knowledge Bases [Create a knowledge base](https://docs.voicebip.com/api/knowledge-bases/create-knowledge-base.md)
- API Reference > Knowledge Bases [Get a knowledge base](https://docs.voicebip.com/api/knowledge-bases/get-knowledge-base.md)
- API Reference > Knowledge Bases [Delete a knowledge base (soft delete)](https://docs.voicebip.com/api/knowledge-bases/delete-knowledge-base.md)
- API Reference > Knowledge Bases [Update a knowledge base](https://docs.voicebip.com/api/knowledge-bases/update-knowledge-base.md)
- API Reference > Knowledge Bases [List documents in a knowledge base](https://docs.voicebip.com/api/knowledge-bases/list-knowledge-base-documents.md)
- API Reference > Knowledge Bases [Add a document to a knowledge base](https://docs.voicebip.com/api/knowledge-bases/create-knowledge-base-document.md)
- API Reference > Knowledge Bases [Get a document](https://docs.voicebip.com/api/knowledge-bases/get-knowledge-base-document.md)
- API Reference > Knowledge Bases [Delete a document (chunks + object, recompute counts)](https://docs.voicebip.com/api/knowledge-bases/delete-knowledge-base-document.md)
- API Reference > Knowledge Bases [Finalize a file upload and start ingestion](https://docs.voicebip.com/api/knowledge-bases/complete-knowledge-base-document.md)
- API Reference > Knowledge Bases [Retrieve relevant chunks from a knowledge base (BYOM)](https://docs.voicebip.com/api/knowledge-bases/query-knowledge-base.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.voicebip.com/openapi.json)
- [OpenAPI YAML](https://docs.voicebip.com/openapi.yaml)