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

# 语音通知 API

> 使用 Lovi Voice API 发送自动化语音呼叫的官方文档

## 介绍

语音通知允许通过自动化电话呼叫联系客户，当 WhatsApp 不可用或更可取时。此端点允许您向联系人发送带有 AI 代理的语音呼叫，提供个性化的语音体验。

## 📞 发送语音通知

要通过 Lovi API 发送语音通知，请使用必要的参数和认证向语音端点发送 POST 请求。

> **方法**：POST **格式**：JSON

### 端点

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

### 查询参数

| 参数           | 必需 | 描述                                                             |
| ------------ | -- | -------------------------------------------------------------- |
| `access_key` | 是  | 您的唯一 API 访问密钥。                                                 |
| `unflatten`  | 否  | 如果设置为 `true`，则正文必须包含平面变量（无嵌套对象）。如果设置为 `false` 或省略，则正文可以包含嵌套对象。 |

**示例 URL：**

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

### 标头

| 键            | 值                | 必需 | 描述                |
| ------------ | ---------------- | -- | ----------------- |
| Content-Type | application/json | 是  | 指示请求正文采用 JSON 格式。 |

**注意**：认证通过 URL 中的 `access_key` 参数处理，而不是通过标头。

### 请求正文

请求正文包含语音通知详细信息。

#### 带嵌套对象的结构（unflatten=false 或省略）

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "first_name": "李",
    "last_name": "明",
    "email": "li@email.com",
    "specialty": "护士助理",
    "client_source": "主网站"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-语音代理",
  "notification_type": "marketing",
  "campaign_name": "Q4 信息通话",
  "name_event": "info-护理课程",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Asia/Shanghai"
}
```

### 必需参数

| 参数                  | 类型     | 描述            | 示例                               |
| ------------------- | ------ | ------------- | -------------------------------- |
| `contact.number`    | String | 收件人电话号码（仅数字）  | `"34666033135"`                  |
| `recipient_id`      | String | 收件人的 ID 或电话号码 | `"34911670470"`                  |
| `agent_id`          | String | 语音代理的唯一标识符    | `"uuid-语音代理"`                    |
| `notification_type` | String | 用于分析的类型       | `"marketing"`, `"transactional"` |

## 🎵 语音配置

### 可用的语音

**中文：**

* `zh-CN-Standard-A`（女性，标准）
* `zh-CN-Standard-B`（男性，标准）
* `zh-CN-Wavenet-A`（女性，高品质）
* `zh-CN-Wavenet-B`（男性，高品质）

## 📋 语音模板

### 创建语音模板

**简单模板：**

```json theme={null}
{
  "name": "order_ready_voice",
  "language": "zh-CN",
  "content": "您好 {{name}}，您的订单编号 {{order_id}} 已准备好在 {{store_location}} 领取",
  "voice": "zh-CN-Standard-A",
  "variables": ["name", "order_id", "store_location"]
}
```

## ⏰ 规划语音通知

### 即时发送

**基本呼叫：**

```javascript theme={null}
await loviService.sendVoiceNotification({
  contact: { number: "34666033135" },
  message: "您好李先生，您的预约已确认明天上午10:00",
  voice: "zh-CN-Standard-A",
  language: "zh-CN"
});
```

## 📞 呼叫管理

### 呼叫状态

| 状态          | 描述     |
| ----------- | ------ |
| `queued`    | 排队等待发送 |
| `ringing`   | 正在呼叫   |
| `answered`  | 收件人已接听 |
| `completed` | 呼叫成功完成 |
| `busy`      | 线路忙碌   |
| `no_answer` | 无应答    |
| `failed`    | 呼叫失败   |

语音通知提供替代的有效渠道，当 WhatsApp 不足时。战略性地使用它们来改善客户体验和通信效率。