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

# Call Control

> Real-time control of active voice calls

Control active calls in real time. Hold, resume, transfer, and inject DTMF tones. All endpoints require the call to be in active (`in_progress`) status.

## Hold a Call

Pause media on both sides of an active call.

```bash
curl -X POST "https://api.voicebip.com/v1/calls/call_abc123/hold" \
  -H "Authorization: Bearer pk_live_your_key"
```

Response:

```json
{ "status": "held" }
```

## Resume a Call

Resume a previously held call.

```bash
curl -X POST "https://api.voicebip.com/v1/calls/call_abc123/resume" \
  -H "Authorization: Bearer pk_live_your_key"
```

Response:

```json
{ "status": "resumed" }
```

## Transfer a Call

Transfer an active call to another phone number. The destination must be in E.164 format.

```bash
curl -X POST "https://api.voicebip.com/v1/calls/call_abc123/transfer" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+2348031234567"
  }'
```

Response:

```json
{ "status": "transferring" }
```

## Send DTMF Tones

Inject DTMF digits into an active call. Useful for navigating IVR menus or entering PINs programmatically.

```bash
curl -X POST "https://api.voicebip.com/v1/calls/call_abc123/dtmf" \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "digits": "1234#"
  }'
```

Response:

```json
{ "status": "sent" }
```

## Error Handling

* **400 Bad Request** -- `destination` (transfer) or `digits` (DTMF) is missing or empty.
* **404 Not Found** -- The `call_id` does not exist, belongs to a different workspace, or the call has already ended and been removed from the active session map.
* **500 Internal Server Error** -- The voice controller is not configured or unreachable, or the call is in an unexpected state (e.g., trying to resume a call that is not currently held).

All call control endpoints require the call to be active. Attempting to control a completed call returns 404.