> 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. # Agents > Create and manage AI agents that own phone numbers and handle communications. Agents are the core resource in Voicebip. Each agent is an AI persona that owns phone numbers and handles voice calls, SMS, and WhatsApp conversations. ## Create an Agent ```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": "Loan Recovery Agent", "language": "en", "system_prompt": "You are a friendly loan recovery agent for a Nigerian fintech. Help callers understand their outstanding balance and payment options. Be professional and empathetic." }' ``` ### Parameters | Field | Type | Required | Description | | ----------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `display_name` | string | Yes | Human-readable name | | `template_id` | string | No | Template ID to pre-fill agent configuration (see [Templates](/guides/templates)) | | `language` | string | No | `en`, `ha`, `yo`, `ig`, `pcm`, `fr`, `ar`, `pt`, `auto` (default: `en`) | | `ai_provider` | string | No | `byom` to relay every turn to your own webhook, or a hosted AI provider slug. List available providers via `GET /v1/ai/models`. Set to `byom` to bring your own model. | | `ai_model` | string | No | Model ID for the selected hosted provider. Must be an active model in the platform catalogue — see [`GET /v1/ai/models`](#voices) for available `` values. Omit to use the provider's platform default. Ignored when `ai_provider` is `byom`. | | `tts_voice` | string | No | The voice the agent speaks with. Pass a `voice_id` from [`GET /v1/voice/models`](#voices) (``). An unknown id is rejected with `400`. Defaults to the platform's TTS voice. | | `system_prompt` | string | No | Instructions for the AI model | | `webhook_url` | string | No | URL that receives BYOM turn requests and lifecycle events (`call.initiated`, `call.transcription`, `call.completed`). Required when `ai_provider` is `byom`; also used for lifecycle events on hosted providers. | | `greeting_text` | string | No | Custom greeting played via TTS when a call connects | | `greeting_audio_url` | string | No | URL of a hosted WAV played as the greeting **instead of** `greeting_text`. Must be 8 kHz mono 16-bit linear-PCM (telephony format). Validated and stored when you save the agent, so a bad URL or wrong format is rejected on the API call, never mid-call. Send `""` to clear it; omit it to leave it unchanged. A per-call screening greeting override still takes precedence. | | `pre_call_announcement` | string | No | Short announcement played before the greeting. Required for CBN-regulated financial agents | | `shareable` | boolean | No | Enable "try my agent" public link (default: `false`) | | `tool_definitions` | string | No | JSON array of OpenAI-compatible tool definitions. Built-in tools: `hang_up`, `transfer_call`, `hold_call`, `resume_call`. Custom tools dispatch to your webhook URL. Defaults to `"[]"`. | | `call_window_start` | string | No | Earliest time the agent accepts inbound calls in `HH:MM` 24h format (e.g. `08:00`). CBN compliance field | | `call_window_end` | string | No | Latest time the agent accepts inbound calls in `HH:MM` 24h format (e.g. `18:00`). CBN compliance field | | `call_window_timezone` | string | No | IANA timezone for call window enforcement (e.g. `Africa/Lagos`). Defaults to `Africa/Lagos` | | `recording_enabled` | boolean | No | Enable call recording for this agent (default: `false`). Workspace-level recording must also be enabled via `POST /v1/workspace/recording`. | | `consent_required` | boolean | No | When `true` (default), the caller hears a consent prompt before recording starts. When `false`, recording begins immediately without a prompt — only disable this if you have an independent legal basis under NDPR. | | `screening_enabled` | boolean | No | BYOM only. When `true`, inbound calls trigger a synchronous `call.screening` webhook (to `webhook_url`) **before** the greeting so you can allow/reject the caller and optionally override the greeting. See [Call Screening](/guides/byom#call-screening-allow--reject-inbound-callers) (default: `false`). | | `screening_fail_closed` | boolean | No | Screening failure policy. `false` (default) = fail-open (allow the call if the screening webhook errors/times out); `true` = fail-closed (reject). | ## List Agents ```bash curl "https://api.voicebip.com/v1/agents" \ -H "Authorization: Bearer pk_live_your_key" ``` ## Update an Agent ```bash curl -X PATCH "https://api.voicebip.com/v1/agents/{agent_id}" \ -H "Authorization: Bearer pk_live_your_key" \ -H "Content-Type: application/json" \ -d '{"system_prompt": "Updated prompt."}' ``` ## Delete an Agent ```bash curl -X DELETE "https://api.voicebip.com/v1/agents/{agent_id}" \ -H "Authorization: Bearer pk_live_your_key" ``` ## Agent ID Format `agt_{WORKSPACE_PREFIX}_{nanoid(12)}` — Example: `agt_PAEZ_njcfm2kycpjs` ## Agent Playground Test your agent's prompt with text chat before making live calls: ```bash curl -X POST https://api.voicebip.com/v1/agents/agt_xxx/playground \ -H "Authorization: Bearer pk_live_xxx" \ -H "Content-Type: application/json" \ -d '{"message": "Hello, what can you help me with?", "history": []}' ``` The playground uses the agent's configured system prompt, AI provider, and model. Pass previous turns in `history` to maintain conversation context. ## Tool Calling (Function Calling) Agents can invoke tools during voice calls. When the AI decides to call a tool, the voice pipeline executes it and feeds the result back to the AI before generating the spoken response. ### Built-in Tools | Tool | Description | Parameters | | --------------- | -------------------------------------- | -------------------------------- | | `hang_up` | End the call gracefully after farewell | None | | `transfer_call` | Transfer to another phone number | `destination` (string, required) | | `hold_call` | Place the caller on hold | None | | `resume_call` | Resume a held call | None | ### Custom Tools Custom tools are dispatched to your agent's webhook URL as a POST request: ```json { "event_type": "tool.invocation", "call_id": "call_xxx", "agent_id": "agt_xxx", "tool": { "tool_call_id": "call_abc", "name": "check_balance", "arguments": {"account_id": "ACC-4421"} } } ``` Return a JSON response with the tool result. The AI receives this and generates its spoken response. ### Configuring Tools Set `tool_definitions` when creating or updating an agent: ```bash curl -X PATCH https://api.voicebip.com/v1/agents/agt_xxx \ -H "Authorization: Bearer pk_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "tool_definitions": "[{\"type\":\"function\",\"function\":{\"name\":\"hang_up\",\"description\":\"End the call gracefully\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"required\":[]}}}]" }' ``` The format follows the OpenAI function calling schema. The `hang_up` tool is enabled by default in the dashboard. ## Voices Each agent speaks with a text-to-speech voice. List the available voices, then set one on an agent via `tts_voice`. ```bash curl https://api.voicebip.com/v1/voice/models \ -H "Authorization: Bearer pk_xxx" ``` ```json { "voices": [ { "provider": "", "voice_id": "", "display_name": "Voice One", "is_platform_default": true }, { "provider": "", "voice_id": "", "display_name": "Voice Two", "is_platform_default": false } ] } ``` Use a `voice_id` as the agent's `tts_voice` on create or update: ```bash curl -X PATCH https://api.voicebip.com/v1/agents/agt_xxx \ -H "Authorization: Bearer pk_xxx" -H "Content-Type: application/json" \ -d '{"tts_voice": ""}' ``` The voice is validated against the catalogue at save time — an unknown `voice_id` returns `400`. Send an empty string to reset to the platform-default voice. The same list powers the voice picker in the dashboard. ## Recording Call recording requires two gates to be open: recording must be enabled at the workspace level, and then separately enabled on each agent. ### Step 1 — Enable recording for your workspace Recording availability and pricing depends on your billing tier: | Tier | Recording | Monthly cost (NGN) | | ------- | ------------- | ------------------ | | Starter | Not available | — | | Builder | Add-on | ₦10,000/month | | Scale | Included | Free | | PAYG | Add-on | ₦15,000/month | Enable it workspace-wide: ```bash curl -X POST "https://api.voicebip.com/v1/workspace/recording" \ -H "Authorization: Bearer pk_live_your_key" \ -H "Content-Type: application/json" \ -d '{"enabled": true}' ``` Returns `400 RESOURCE_NOT_AVAILABLE_ON_TIER` on Starter. Disabling is unconditional on all tiers. ### Step 2 — Enable recording on the agent Once workspace recording is on, flip the flag per agent: ```bash curl -X PATCH "https://api.voicebip.com/v1/agents/agt_xxx" \ -H "Authorization: Bearer pk_live_your_key" \ -H "Content-Type: application/json" \ -d '{"recording_enabled": true}' ``` Both flags must be `true` for a call to be recorded. Either flag being `false` suppresses recording. ### Consent Prompt By default (`consent_required: true`) Voicebip plays a consent prompt at the start of every recorded call: > "This call may be recorded for quality purposes. Press 1 to continue, or press 2 to opt out of recording." * DTMF `1` — consent granted, recording starts * DTMF `2` — caller opts out, call continues without recording * No input within 12 seconds — defaults to no recording To disable the prompt and record immediately without asking: ```bash curl -X PATCH "https://api.voicebip.com/v1/agents/agt_xxx" \ -H "Authorization: Bearer pk_live_your_key" \ -H "Content-Type: application/json" \ -d '{"consent_required": false}' ``` > **Warning** > > Setting `consent_required` to `false` means you are recording callers without an in-call prompt. You must have an independent legal basis (e.g. prior written consent, a pre-call disclosure, or a regulatory exemption) under the Nigeria Data Protection Regulation (NDPR) before doing this. Every toggle is recorded in the audit log. ### Accessing Recordings When a call is recorded the `call.completed` webhook payload includes a `recording_url` field. Use it to download the WAV file: ```bash curl "https://api.voicebip.com/v1/calls/{call_id}/recording" \ -H "Authorization: Bearer pk_live_your_key" \ --output recording.wav ``` Recordings are retained for 30 days and then automatically deleted. See [Recording Playback](/guides/recording-playback) for range-request and browser-playback details. ## Tier Limits | Tier | Max Agents | | ------- | ---------- | | Starter | 2 | | Builder | 10 | | Scale | Unlimited |