> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wadial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Live calls

> Build audio-only WhatsApp calls with live PCM streaming, prerecorded audio, and retained recordings.

Live calls let your application start or handle WhatsApp audio calls from a connected token.

Version 1 supports audio-only media over WebSocket PCM. WebRTC is planned as a later transport, and the call records already include a `transport` field so your integration can keep the same call model.

## Start a call

```http theme={null}
POST /api/v1/sessions/{sessionId}/calls
Authorization: Bearer <api_key>
Content-Type: application/json
```

```json theme={null}
{
  "to": "15551234567@s.whatsapp.net"
}
```

The token must be paired and connected. The response contains a call snapshot with `callId`, `peerJid`, `direction`, `state`, `transport`, timestamps, and mute state.

## Stream live audio

Upgrade the media URL with bearer auth:

```http theme={null}
GET /api/v1/sessions/{sessionId}/calls/{callId}/media
Authorization: Bearer <api_key>
Upgrade: websocket
```

Client binary frames are outbound mono `Float32LE` PCM at `16000` Hz. Server binary frames are inbound peer audio in the same format.

Server JSON text frames include:

| Type         | Purpose                                                         |
| ------------ | --------------------------------------------------------------- |
| `ready`      | Confirms encoding, sample rate, channels, and direction.        |
| `buffer`     | Reports live outbound buffer depth and backpressure watermarks. |
| `call_state` | Mirrors call state changes.                                     |
| `error`      | Reports invalid frames or feed failures.                        |
| `ended`      | Reports that the call ended.                                    |

Raw audio is never sent over SSE or webhooks.

## Play prerecorded audio

Upload an audio asset once, then play it into active calls:

```http theme={null}
POST /api/v1/call-audio-assets
Authorization: Bearer <api_key>
Content-Type: multipart/form-data
```

Multipart field:

| Field   | Required | Notes                                     |
| ------- | -------- | ----------------------------------------- |
| `audio` | Yes      | Any supported `audio/*` file up to 32 MB. |

Playback:

```http theme={null}
POST /api/v1/sessions/{sessionId}/calls/{callId}/audio/play
Authorization: Bearer <api_key>
Content-Type: application/json
```

```json theme={null}
{
  "assetId": "019f..."
}
```

## Recordings

WADial stores inbound, outbound, and mixed WAV recording artifacts for calls with captured media. Retention defaults to 30 days and can be configured by the account environment.

Recording-ready events include metadata such as `recordingId`, `kind`, `durationMs`, `sizeBytes`, and `expiresAt`; they do not include raw audio.