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

# Voice Notifications API

> Official documentation for using Lovi's Voice API to send automated voice calls

## Introduction

Voice notifications allow you to make automated calls with virtual agents. This endpoint enables you to send voice calls with AI-powered agents to your contacts, providing a personalized voice experience.

## 📞 Send Voice Notification

To send a voice notification via the Lovi API, make a POST request to the voice endpoint with the necessary parameters and authentication.

> **Method**: POST **Format**: JSON

### Endpoint

```
POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key={YOUR_ACCESS_KEY}
```

### Query Parameters

| Parameter    | Required | Description                                                                                                                                    |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_key` | Yes      | Your unique API access key.                                                                                                                    |
| `unflatten`  | No       | If set to `true`, the body must contain flat variables (no nested objects). If set to `false` or omitted, the body can contain nested objects. |

**Example URL:**

```
POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key=your-api-key&unflatten=true
```

### Headers

| Key          | Value            | Required | Description                                        |
| ------------ | ---------------- | -------- | -------------------------------------------------- |
| Content-Type | application/json | Yes      | Indicates that the request body is in JSON format. |

**Note**: Authentication is handled via the `access_key` parameter in the URL, not through headers.

### Body Request

The body of the request contains the voice notification details.

#### Structure with nested objects (unflatten=false or omitted)

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González",
    "email": "maria@email.com",
    "titulacion": "Técnico en Enfermería",
    "fuente_cliente": "Web Principal"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}
```

#### Structure with flat variables (unflatten=true)

```json theme={null}
{
  "contact.number": "34666033135",
  "contact.first_name": "María",
  "contact.last_name": "González",
  "contact.email": "maria@email.com",
  "contact.titulacion": "Técnico en Enfermería",
  "contact.fuente_cliente": "Web Principal",
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}
```

### Required Parameters

| Parameter           | Type   | Description                          | Example                          |
| ------------------- | ------ | ------------------------------------ | -------------------------------- |
| `contact.number`    | String | Phone number without '+' or spaces   | `"34666033135"`                  |
| `recipient_id`      | String | ID or phone number of the recipient  | `"34911670470"`                  |
| `agent_id`          | String | Unique identifier of the voice agent | `"uuid-agente-voz"`              |
| `notification_type` | String | Type for analytics                   | `"marketing"`, `"transactional"` |
| `campaign_name`     | String | Campaign identifier name             | `"Voice Campaign Q4"`            |

### Optional Parameters

| Parameter            | Type     | Description                    | Example                   | Default   |
| -------------------- | -------- | ------------------------------ | ------------------------- | --------- |
| `contact.first_name` | String   | Contact's first name           | `"María"`                 | -         |
| `contact.last_name`  | String   | Contact's last name            | `"González"`              | -         |
| `contact.email`      | String   | Contact's email                | `"maria@email.com"`       | -         |
| `name_event`         | String   | Event to trigger flows         | `"info-curso-enfermeria"` | -         |
| `datetime_sending`   | DateTime | Scheduled date/time (ISO 8601) | `"2024-12-25T09:00:00"`   | Immediate |
| `timezone`           | String   | Timezone for scheduling        | `"Europe/Madrid"`         | `"UTC"`   |

**Custom Contact Fields**: You can include any additional fields in the `contact` object for personalization (e.g., `titulacion`, `fuente_cliente`, etc.).

### Response

When the request is successful, the response will contain:

```json theme={null}
{
  "success": true,
  "message": "Voice notification queued successfully",
  "notification_id": "uuid-notification",
  "scheduled_time": "2024-12-25T09:00:00Z"
}
```

### Voice-Specific Features

* **AI-Powered Agents**: Use virtual agents with natural voice synthesis
* **Personalization**: Include custom contact data for personalized calls
* **Scheduling**: Program calls for specific times with timezone support
* **Event Triggers**: Trigger specific conversation flows with `name_event`

### Best Practices

* **Timing**: Schedule calls during business hours for better engagement
* **Personalization**: Include relevant contact information for better conversation flow
* **Agent Selection**: Choose appropriate agents based on use case (sales, support, etc.)
* **Compliance**: Ensure calls comply with local regulations and consent requirements

***

## 📚 Tips for Voice Development

* Always include `agent_id` for voice notifications
* Use scheduling features to respect time zones
* Test with development agents before production
* Monitor call completion rates and adjust timing accordingly