> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 快速入门

## 你将构建的内容

完成本指南后，智能体可通过业务号码回复 WhatsApp 文本消息和语音留言，你还将发送 1 条由 API 发起的模板消息。预计需要约 20 分钟，另需等待 Meta 审批首个模板。

## 开始前

你需要：

* 一个 [ElevenLabs 智能体](/docs/zh/eleven-agents/quickstart)。任何现有智能体都可以。
* 可管理的 [Meta 商务资产组合](https://business.facebook.com/)。
* 一个目前**未**在 WhatsApp Business 应用中使用，也未注册到其他 WhatsApp 服务商的电话号码。已在其他地方使用的号码无法导入——请参阅[限制](/docs/zh/eleven-agents/whatsapp#limitations)。
* 如果计划发送模板或拨打电话，需在 [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) 中添加付款方式。Meta 将单独收费，不包含在 ElevenLabs 费用中。

#### 导入 WhatsApp 商务账号

前往 [WhatsApp 页面](https://elevenlabs.io/app/agents/whatsapp)，点击 ***导入账号*** 按钮。这会打开 Meta 的授权流程，你可选择（或创建）WhatsApp 商务账号和电话号码，并授予 ElevenLabs 管理权限：

![WhatsApp 授权流程](/docs/_fern-img/9e5238e98f926582db314e9debc187a7dc29fd38a980cb732b4563b373110351.webp)

#### 分配智能体并选择行为

导入后将进入账号设置页面。请分配一个智能体——否则会忽略入站消息，并拒接入站来电：

![WhatsApp 账号页面](/docs/_fern-img/f5598ac70ade00048effb5ee3bf6cbc93cd61876652eb3ce5917ac21c6209bf6.webp)

配置智能体在该号码上的行为（完整参考请参阅[账号 设置](/docs/zh/eleven-agents/whatsapp#account-settings)）：

* **启用消息**——智能体是否回复消息。若其他系统负责处理消息，而 ElevenLabs 只需处理通话，请将其关闭。
* **启用语音消息回复**——开启后，智能体会用自己的声音以语音留言回复语音留言；关闭后，始终以文本回复。
* **启用输入状态指示器**——开启后，智能体会将收到的消息标记为已读，并在处理时显示正在输入。

#### 进行首次对话

用个人手机向业务号码发送消息，智能体会回复。发送一条语音留言——系统会将其转录给智能体，智能体则会用自己的语音留言回复：

![WhatsApp 文本对话](/docs/_fern-img/4c31b4d2b5eccccd7cddfa81144176a6d3c32f4670add5306f3a6ef78bc05244.webp)

对话进行时，会显示在[对话历史记录](https://elevenlabs.io/app/agents/history)中。

> **Info**
>
> 当智能体使用 ***结束对话*** 系统工具、
> ***最长对话时长*** 到期，或智能体最近一次回复后经过默认的 15 分钟非活动超时后，消息对话将结束。
> 用户下一条消息会开启新的对话。详细了解[对话 超时](/docs/zh/eleven-agents/customization/conversation-flow#maximum-conversation-duration)。

#### 发送首条出站消息

主动联系用户需要 Meta 批准的**消息模板**——WhatsApp 仅允许在活跃对话中发送自由格式的业务消息。在 [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates) 中创建一个简单的实用型模板，例如：

```text
Hi {{name}}, thanks for signing up. Reply here if you have any questions.
```

模板获批后，发送它：

#### Python

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.whatsapp.outbound_message(
    whatsapp_phone_number_id="524029457612345",
    whatsapp_user_id="12213231492",
    template_name="welcome",
    template_language_code="en",
    template_params=[
        {
            "type": "body",
            "parameters": [
                {"type": "text", "parameter_name": "name", "text": "Daniele"}
            ],
        }
    ],
    agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
)
```

#### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.whatsapp.outboundMessage({
  whatsappPhoneNumberId: "524029457612345",
  whatsappUserId: "12213231492",
  templateName: "welcome",
  templateLanguageCode: "en",
  templateParams: [
    {
      type: "body",
      parameters: [{ type: "text", parameterName: "name", text: "Daniele" }],
    },
  ],
  agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
});
```

#### cURL

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_phone_number_id": "524029457612345",
    "whatsapp_user_id": "12213231492",
    "template_name": "welcome",
    "template_language_code": "en",
    "template_params": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "parameter_name": "name", "text": "Daniele"}
        ]
      }
    ],
    "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9"
  }'
```

这里有两个关键点：

* `template_params` 是组件对象列表——必须包含 `{"type": "body", ...}` 包装层。
* `whatsapp_user_id` 只能包含数字，需带国家代码且不含 `+`（例如 `14155552671`）。

在 [WhatsApp 页面](https://elevenlabs.io/app/agents/whatsapp)的账号菜单中，通过 ***复制电话号码 ID*** 选项查找 `whatsapp_phone_number_id`。

手机会收到该模板。回复它——智能体将从这里继续对话。

## 如果遇到问题

* **智能体从不回复**：号码未分配智能体，或**启用消息**已关闭。如果这些设置均无误，请检查智能体是否需要[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)——入站 WhatsApp 对话开始时没有用户提供的值，因此，如果智能体的工具或首条消息需要某个值，除非对话初始化 webhook 提供该值，否则它会在回复前失败。请参阅[初始化上下文](/docs/zh/eleven-agents/whatsapp#initialization-context)。
* **导入失败**：该号码已注册到其他服务商或 WhatsApp Business 应用。
* **API 返回 200，但未收到消息**：模板尚未获批、参数与模板不匹配，或 WhatsApp 商务账号存在未结清款项（Meta 错误 131042）。
* **用户回复开启了没有上下文的独立对话**：收件人 ID 格式不正确——请参阅[收件人号码格式](/docs/zh/eleven-agents/whatsapp/outbound#recipient-number-format)。

其他问题请参阅[故障排除与常见问题](/docs/zh/eleven-agents/whatsapp/troubleshooting)。

## 后续步骤

* 使用[动态变量](/docs/zh/eleven-agents/whatsapp/outbound#dynamic-variables-branches-and-environments)和[个性化系统变量](/docs/zh/eleven-agents/whatsapp#personalization)定制对话。
* 通过[出站消息与模板](/docs/zh/eleven-agents/whatsapp/outbound)大规模开展触达。
* 通过[交互式消息](/docs/zh/eleven-agents/whatsapp/interactive-messages)让智能体提供可点击的选项。
* 使用 [WhatsApp 工具](/docs/zh/eleven-agents/whatsapp/tools)，让其他渠道的智能体发送 WhatsApp 消息。
* 在[定价常见问题](/docs/zh/eleven-agents/whatsapp/troubleshooting#faq)中了解费用。