Agents

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

$
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",
>
    "ai_provider": "openai",
>
    "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

List Agents

$
curl "https://api.voicebip.com/v1/agents" \
>
  -H "Authorization: Bearer pk_live_your_key"

Update an Agent

$
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

$
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:

$
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

Custom Tools

Custom tools are dispatched to your agent’s webhook URL as a POST request:

1
{
2
  "event_type": "tool.invocation",
3
  "call_id": "call_xxx",
4
  "agent_id": "agt_xxx",
5
  "tool": {
6
    "tool_call_id": "call_abc",
7
    "name": "check_balance",
8
    "arguments": {"account_id": "ACC-4421"}
9
  }
10
}

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:

$
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.

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:

Enable it workspace-wide:

$
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:

$
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:

$
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}'

Accessing Recordings

When a call is recorded the call.completed webhook payload includes a recording_url field. Use it to download the WAV file:

$
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 for range-request and browser-playback details.

Tier Limits