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

# Voice Calls

> Place outbound voice calls with pre-recorded audio, uploaded audio files, or text-to-speech. Learn how to use the Karibu Voice API endpoints.

# Voice Calls

The Karibu Voice API lets you place outbound voice calls to phone numbers. When the recipient answers, they hear either a pre-recorded audio file or synthesized speech from text. All voice endpoints require your **X-API-Key** header for authentication.

## Overview

You can initiate voice calls in three ways:

| Method                   | Endpoint                            | Use when                                               |
| ------------------------ | ----------------------------------- | ------------------------------------------------------ |
| **Audio from URL**       | `POST /v1/voice/calls/audio`        | You have a public URL to an audio file (MP3, WAV).     |
| **Audio upload**         | `POST /v1/voice/calls/audio/upload` | You have the audio file on disk and want to upload it. |
| **Text-to-speech (TTS)** | `POST /v1/voice/calls/tts`          | You want the system to speak a text message.           |

The **receiver number** is always in E.164 or national format (e.g. `255788344348` for Tanzania).

***

## 1. Voice call with audio from URL

Use this when your audio is already hosted at a **public URL** (e.g. on your CDN or S3 with public read). The API will fetch the file and play it to the recipient when they answer.

### Request

* **Method:** `POST /v1/voice/calls/audio`
* **Headers:** `X-API-Key` (required), `Content-Type: application/json`
* **Body:**
  * `receiver_number` (string, required) — E.164 or national number to call (e.g. `255788344348`)
  * `audio_url` (string, required) — Public URL of the audio file (e.g. MP3, WAV)

### Example

```bash theme={null}
curl -X POST https://karibu.briq.tz/v1/voice/calls/audio \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "receiver_number": "255788344348",
    "audio_url": "https://example.com/announcement.mp3"
  }'
```

### When to use

* Announcements or pre-recorded messages already on a server
* Audio that you update by changing the file at the same URL
* No need to send the file in the request body

***

## 2. Voice call with uploaded audio

Use this when you have the **audio file locally** (e.g. from your app or user upload). You send the file as multipart form data; it is stored and then played to the recipient when they answer.

### Request

* **Method:** `POST /v1/voice/calls/audio/upload`
* **Headers:** `X-API-Key` (required). Do **not** set `Content-Type`; the client will set it to `multipart/form-data` with the correct boundary.
* **Body (multipart/form-data):**
  * `receiver_number` (string, required) — E.164 or national number to call
  * `file` (file, required) — Audio file (MP3 or WAV) to play to the recipient

### Example

```bash theme={null}
curl -X POST https://karibu.briq.tz/v1/voice/calls/audio/upload \
  -H "X-API-Key: your_api_key_here" \
  -F "receiver_number=255788344348" \
  -F "file=@/path/to/announcement.mp3"
```

### When to use

* Audio is generated or stored on your server
* You don’t have a public URL for the file
* One-off or dynamic recordings (e.g. per-user messages)

***

## 3. Voice call with text-to-speech (TTS)

Use this when you want the system to **speak a text message** to the recipient. No audio file is needed; the text is synthesized to speech when they answer.

### Request

* **Method:** `POST /v1/voice/calls/tts`
* **Headers:** `X-API-Key` (required), `Content-Type: application/json`
* **Body:**
  * `receiver_number` (string, required) — E.164 or national number to call
  * `text` (string, required) — The message to be spoken (at least one character)

### Example

```bash theme={null}
curl -X POST https://karibu.briq.tz/v1/voice/calls/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "receiver_number": "255788344348",
    "text": "Hello, this is a message from Briq. Your order has been confirmed."
  }'
```

### When to use

* Notifications or alerts (e.g. order confirmation, reminders)
* Dynamic content that changes per call
* No need to record or host audio files

***

## Authentication

All voice endpoints require the **X-API-Key** header with a valid API key. Use the same key you use for other Karibu API calls (workspace, messages, OTP, etc.).

```http theme={null}
X-API-Key: your_api_key_here
```

***

## Phone number format

* Use **E.164** or **national** format (e.g. `255788344348` for Tanzania).
* Include country code; no leading `+` is required in the request body.
* Validate numbers before calling to avoid failed or wrong-destination calls.

***

## Webhooks for voice events

To receive call status or events (e.g. answered, completed, failed), create a webhook with **service type** `voice` for your developer app. See [Webhooks](/guides/webhooks) for creating and managing webhooks. The voice endpoints initiate the call; webhooks deliver event notifications to your URL.

***

## Summary

| Need                       | Endpoint                            | Key parameters                        |
| -------------------------- | ----------------------------------- | ------------------------------------- |
| Play audio from a URL      | `POST /v1/voice/calls/audio`        | `receiver_number`, `audio_url`        |
| Upload and play audio file | `POST /v1/voice/calls/audio/upload` | `receiver_number`, `file` (multipart) |
| Speak text to the user     | `POST /v1/voice/calls/tts`          | `receiver_number`, `text`             |

For full request/response schemas and to try the endpoints in the docs, use the **API reference** (Karibu-Voice section).