Create an agent | Voicebip

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

display_namestringRequired

descriptionstringOptional

knowledge_base_idstringOptional

Attach a knowledge base at creation (kb_… id, must belong to the workspace).

template_idstringOptional

Optional template ID. When provided, the agent is pre-configured with the template’s settings (system_prompt, language, ai_provider, etc.). You can override individual fields.

languagestringOptionalDefaults to en

ai_providerstringOptional

AI backend for this agent. Use GET /admin/ai/providers to see all available providers (typically gemini or openai for hosted AI). Set to byom to relay every caller turn to your own webhook URL — webhook_url is then required.

ai_modelstringOptional

Model ID for the chosen provider. Must be an active model in the platform catalogue (AI model IDs validated against voicebip_v1.ai_models). Omit the field to use the provider’s platform default. Ignored when ai_provider is byom.

tts_voicestringOptional

The voice the agent speaks with. Pass a voice_id from GET /v1/voice/models (e.g. aura-asteria-en). Validated at save time — an unknown id is rejected with 400. Omit to use the platform-default voice.

system_promptstringOptional

webhook_urlstringOptional

HTTPS endpoint that receives all agent traffic: BYOM voice turn requests, messaging BYOM turns, and lifecycle events (call.initiated, call.transcription, call.completed). Required when ai_provider is byom. Ignored for hosted AI providers (gemini, openai). Distinguish turn requests from lifecycle events by the presence of an event_type field in the body. See the BYOM guide for the full request/response schema.

HTTPS endpoint that receives **all** agent traffic: BYOM voice turn requests, messaging BYOM turns, and lifecycle events (`call.initiated`, `call.transcription`, `call.completed`). Required when `ai_provider` is `byom`. Ignored for hosted AI providers (`gemini`, `openai`). Distinguish turn requests from lifecycle events by the presence of an `event_type` field in the body. See the [BYOM guide](/guides/byom) for the full request/response schema.

greeting_textstringOptional

Custom greeting played via TTS when a call connects

tool_definitionsstringOptional

JSON array of OpenAI-compatible tool definitions. Defaults to ’[]’.

shareablebooleanOptional

Enable the public 'try my agent' shareable link

call_window_startstringOptionalDefaults to 08:00

Earliest outbound call time (HH:MM). Default: 08:00

call_window_endstringOptionalDefaults to 20:00

Latest outbound call time (HH:MM). Default: 20:00

call_window_timezonestringOptionalDefaults to Africa/Lagos

IANA timezone. Default: Africa/Lagos

pre_call_announcementstringOptional

recording_enabledbooleanOptional

Enable call recording for this agent. Workspace recording must also be enabled via POST /v1/workspace/recording (available on Builder and Scale tiers; not available on Starter).

consent_requiredbooleanOptional

When true (default), plays a DTMF consent prompt before recording. Set to false only if you have prior consent or an NDPR exemption.

screening_enabledbooleanOptional

BYOM only. Enable the synchronous pre-greeting call.screening webhook for inbound calls (allow/reject + optional dynamic greeting). Requires ai_provider=byom and a webhook_url.

screening_fail_closedbooleanOptional

Screening failure policy: false (default) = fail-open (allow on webhook error), true = fail-closed (reject).

Response

Agent created

agent_idstring

workspace_idstring

display_namestring

descriptionstring

languagestring

ai_providerstring

ai_modelstring

tts_voicestring

The voice the agent speaks with. This is a voice_id from GET /v1/voice/models (e.g. aura-asteria-en). Null/absent means the platform-default voice.

system_promptstring

webhook_urlstring

greeting_textstring

Custom greeting played via TTS when a call connects. If null, a default greeting is used.

greeting_audio_urlstring

The source URL of a hosted WAV played as the greeting instead of greeting_text. Set via UpdateAgent; validated and stored at save time. The system-managed storage key is never returned.

tool_definitionsstringDefaults to []

JSON array of OpenAI-compatible function/tool definitions. The AI can invoke these tools during voice calls. Built-in tools: hang_up, transfer_call, hold_call, resume_call. Custom tools are dispatched to the agent’s webhook_url. Defaults to ”[]”.

shareableboolean

When true, enables a public ‘try my agent’ link for browser-based test calls.

knowledge_base_idstring

Attached knowledge base (RAG). When set, hosted-AI turns answer from this KB’s documents. Empty/absent = none.

call_window_startstringDefaults to 08:00

Earliest permitted outbound call time (HH:MM, 24hr). CBN compliance.

call_window_endstringDefaults to 20:00

Latest permitted outbound call time (HH:MM, 24hr). CBN compliance.

call_window_timezonestringDefaults to Africa/Lagos

IANA timezone for call window evaluation.

pre_call_announcementstring

CBN requirement: spoken announcement at start of call identifying the sponsoring institution.

recording_enabledboolean

Whether call recording is enabled for this agent. Workspace-level recording must also be enabled via POST /v1/workspace/recording for calls to be recorded.

consent_requiredboolean

When true (default), the caller hears a consent prompt before recording starts. When false, recording begins immediately. Only disable if you have an independent legal basis under NDPR.

screening_enabledboolean

BYOM only. When true, inbound calls trigger a synchronous call.screening webhook (to the agent’s webhook_url) BEFORE the greeting so you can allow/reject the caller and optionally override the greeting. See the BYOM guide.

screening_fail_closedboolean

Screening failure policy. false (default) = fail-open (allow the call if the screening webhook errors/times out); true = fail-closed (reject).

statusenum

created_atdatetime

updated_atdatetime

Errors

400

Create Agent Request Bad Request Error

401

Create Agent Request Unauthorized Error

429

Create Agent Request Too Many Requests Error

$	curl -X POST https://api.voicebip.com/v1/agents \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"display_name": "display_name"
>	}'

1	{
2	"agent_id": "agent_id",
3	"workspace_id": "workspace_id",
4	"display_name": "display_name",
5	"description": "description",
6	"language": "language",
7	"ai_provider": "ai_provider",
8	"ai_model": "ai_model",
9	"tts_voice": "tts_voice",
10	"system_prompt": "system_prompt",
11	"webhook_url": "webhook_url",
12	"greeting_text": "greeting_text",
13	"greeting_audio_url": "greeting_audio_url",
14	"tool_definitions": "[{\"type\":\"function\",\"function\":{\"name\":\"hang_up\",\"description\":\"End the call gracefully\",\"parameters\":{\"type\":\"object\",\"properties\":{},\"required\":[]}}}]",
15	"shareable": true,
16	"knowledge_base_id": "knowledge_base_id",
17	"call_window_start": "08:00",
18	"call_window_end": "20:00",
19	"call_window_timezone": "Africa/Lagos",
20	"pre_call_announcement": "pre_call_announcement",
21	"recording_enabled": true,
22	"consent_required": true,
23	"screening_enabled": true,
24	"screening_fail_closed": true,
25	"status": "active",
26	"created_at": "2024-01-15T09:30:00Z",
27	"updated_at": "2024-01-15T09:30:00Z"
28	}