Call Transfer & Behavior

Vocobase agents can transfer live calls to a human agent mid-conversation. When a caller asks to speak to a human, the agent announces the transfer and the caller is bridged to the configured human number. You can also configure the agent to end calls automatically when the conversation goal is reached.

How call transfer works

Caller speaks with your AI agent
        │
        ▼
Agent detects a transfer trigger (e.g., caller asks for human)
        │
        ▼
Agent speaks the transfer announcement ("Please hold while I transfer you...")
        │
        ▼
Vocobase transfers the call to the human's phone number
        │
        ▼
Human picks up — caller is now speaking with a human agent
        │
        ▼
Webhook fires session.completed for the agent-handled portion

The agent detects a trigger condition — e.g., the caller says “let me speak to a manager”
The agent speaks the configured transfer announcement
Vocobase transfers the caller to the configured human phone number
The session.completed webhook includes transfer metadata so you can identify the handoff

The number you transfer to must be in E.164 format (e.g., +14155551234).

Enabling call transfer on an agent

Set transfer_enabled to true when creating or updating an agent. Provide the phone number the caller should be transferred to. The transfer_instructions field is plain English guidance for when the agent should transfer:

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_enabled": true,
    "transfer_number": "+14155551234",
    "transfer_message": "Let me connect you with a human agent now.",
    "transfer_instructions": "If the caller asks to speak to a human, agent, supervisor, manager, or representative, transfer the call. If the caller becomes visibly upset, raises their voice, or repeatedly expresses frustration, transfer the call. If the caller has a billing or refund question that requires account access you do not have, transfer the call."
  }'

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transfer_enabled": true,
    "transfer_number": "+14155551234",
    "transfer_message": "Let me connect you with a human agent now.",
    "transfer_instructions": "If the caller asks to speak to a human ...",
    ...
  }
}

Transfer agent fields

Field	Type	Description
`transfer_enabled`	`boolean`	Master toggle. Defaults to `false`.
`transfer_number`	`string`	E.164 phone number to transfer to. Max 32 characters. Required when `transfer_enabled` is true.
`transfer_message`	`string`	Announcement spoken right before transferring. Max 500 characters. If empty, the bot uses a platform default.
`transfer_instructions`	`string` (≤2000 chars)	Free-text natural-language instructions for when to transfer. Pass `null` or empty to skip the section.

Writing transfer instructions

transfer_instructions is plain English. There’s no fixed taxonomy — write conditions specific to your use case:

If the caller mentions they're driving and we'll call them back, transfer the call to our voicemail line.
If the caller asks for our hours of operation in a language other than English, transfer.
If the caller mentions a chargeback or dispute, immediately transfer to billing.

Hard cutover — the prior transferTriggers: string[] array of fixed keys (CALLER_ASKS_HUMAN, FRUSTRATED, etc.) has been removed. If you were posting that field, replace it with transfer_instructions containing the equivalent prose. Existing agents were auto-migrated.

End-call behavior

Configure the agent to end calls automatically when certain conditions are met. Same free-form pattern as transfer:

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "end_call_enabled": true,
    "end_call_message": "Thank you for calling. Have a great day!",
    "end_call_instructions": "When the caller says goodbye, says they have to go, or otherwise indicates the conversation is over, end the call. If the caller has not spoken for an extended period and is unlikely to respond, end the call."
  }'

End-call agent fields

Field	Type	Description
`end_call_enabled`	`boolean`	Master toggle. Defaults to `true`.
`end_call_message`	`string`	Farewell message spoken before hanging up. Max 500 characters.
`end_call_instructions`	`string` (≤2000 chars)	Free-text natural-language instructions for when to end the call. Pass `null` or empty to skip the section.

User idle behavior

Agents default to user_idle_enabled: true. With the default setting, Vocobase uses platform-managed silence timing and retry settings to ask whether the caller is still there and may end the call after repeated idle prompts. Set user_idle_enabled to false to disable that behavior for an agent:

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "user_idle_enabled": false
  }'

V2 only exposes the boolean toggle. user_idle_timeout_secs and max_idle_retries are platform-managed and are not accepted by the agent API.

What happens when a call is transferred

When a transfer happens:

The agent speaks the configured transfer_message.
Vocobase transfers the caller to transfer_number.
The session.completed webhook includes data.call.transferred: true.

The session.completed partner webhook fires when the agent-handled portion ends. Distinguish a transferred call from a normal hangup via data.call.transferred on the webhook payload — see session.completed payload. duration_seconds reflects only the bot leg. recording_url, when present, is the bot-leg recording — the human side is not recorded.

Initiating a transfer from the API

You can programmatically transfer an active call to a human number using the transfer endpoint:

curl -X POST https://api.vocobase.com/api/v2/calls/{call_id}/transfer \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210"
  }'

{
  "success": true,
  "data": {
    "message": "Call transferred",
    "callId": "c1234567-abcd-1234-abcd-123456789012",
    "sessionId": "s1234567-abcd-1234-abcd-123456789012"
  }
}

Request

Field	Type	Required	Description
`to`	`string`	No	E.164 number to transfer to. If omitted, the agent’s `transfer_number` is used.

Response

Field	Type	Description
`success`	`boolean`	Whether the transfer was queued successfully
`data.message`	`string`	Status message
`data.callId`	`string`	The call identifier
`data.sessionId`	`string`	The Vocobase session ID

The call must be actively in-progress for a transfer to succeed. Transferring an already-completed call returns a 400 error.

Testing the transfer flow

Enable transfer on your agent

Set transfer_enabled: true, a valid E.164 transfer_number, and clear transfer_instructions.

Place a test call

Make a call to your agent. During the conversation, say something that matches your transfer instructions, like “Can I talk to a real person?”

Verify in webhook

After the call ends, check your session.completed webhook. A transferred call will include the transfer details in the session metadata.

Next steps

Inbound Calls

Set up inbound call handling with Twilio.

Custom Functions

Create custom LLM-callable API functions for your agents.

Webhooks

Configure webhook notifications for call events.

Billing (₹)

Understand how call ₹ is calculated, including 15s buckets and tier pricing.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Call Transfer & Behavior

Call Transfer & Behavior

How call transfer works

Enabling call transfer on an agent

Transfer agent fields

Writing transfer instructions

End-call behavior

End-call agent fields

User idle behavior

What happens when a call is transferred

Initiating a transfer from the API

Request

Response

Testing the transfer flow

Next steps

Inbound Calls

Custom Functions

Webhooks

Billing (₹)

​Call Transfer & Behavior

​How call transfer works

​Enabling call transfer on an agent

​Transfer agent fields

​Writing transfer instructions

​End-call behavior

​End-call agent fields

​User idle behavior

​What happens when a call is transferred

​Initiating a transfer from the API

​Request

​Response

​Testing the transfer flow

​Next steps

Inbound Calls

Custom Functions

Webhooks

Billing (₹)

Call Transfer & Behavior

How call transfer works

Enabling call transfer on an agent

Transfer agent fields

Writing transfer instructions

End-call behavior

End-call agent fields

User idle behavior

What happens when a call is transferred

Initiating a transfer from the API

Request

Response

Testing the transfer flow

Next steps