> 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 消息。若要主动联系用户——例如发送通知、重新互动或安排通话——需要发送经 Meta 批准的 **消息模板**。本页介绍如何创建模板、发送外发消息和通话，以及大规模运行这些操作。

## 在 WhatsApp Manager 中创建模板

模板需在 [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates) 中创建并获批，不在 ElevenLabs 中创建。

创建模板时：

* 选择类别：交易类消息选择 **实用型**，推广类消息选择 **营销型**，验证码选择 **身份验证型**。Meta 对各类别采用不同的定价和速率限制——请参阅 [WhatsApp 定价](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)。
* 选择参数格式：位置参数（`{{1}}`、`{{2}}`）或命名参数（`{{customer_name}}`）。命名参数要求为发送的每个值提供 `parameter_name`。
* 提交审批。审批通常需要几分钟到几小时。待审批或被拒绝的模板无法发送——API 会接受请求，但 Meta 不会投递消息。

> **Note**
>
> Meta 限制单个用户在指定时间段内可接收的[营销模板 ](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)
> 数量。如果营销模板未被投递，常见原因是超出此限制（Meta 错误 131049）。

## 发送外发消息

发送模板消息会开启新对话。用户回复前，智能体会保持静默——模板本身是第一条消息，用户回复前不会启动任何对话计时器。

#### 控制台

前往 [WhatsApp 页面](https://elevenlabs.io/app/agents/whatsapp)，选择账户，然后点击 ***外发 -> 消息*** 按钮。选择智能体，提供 WhatsApp 用户 ID，并选择消息模板及其参数：

![WhatsApp 外发消息对话框](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp)

#### 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",
    conversation_initiation_client_data={
        "dynamic_variables": {"customer_name": "Daniele"},
    },
)
```

#### 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",
  conversationInitiationClientData: {
    dynamicVariables: { customer_name: "Daniele" },
  },
});
```

#### 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",
    "conversation_initiation_client_data": {
      "dynamic_variables": {"customer_name": "Daniele"}
    }
  }'
```

完整请求架构请参阅 [API 参考文档](/docs/zh/api-reference/whats-app/outbound-message)。

> **Tip**
>
> AI 助手可以根据模板调整这些示例。让它参考 ElevenLabs 文档的
> [llms.txt](/docs/zh/llms.txt)（或更详细的 [llms-full.txt](/docs/zh/llms-full.txt)），粘贴 WhatsApp Manager 中的
> 模板定义，并要求生成请求——它会生成包含正确 `template_params` 的 cURL
> 命令或 SDK 调用。

### 模板参数

`template_params` 是 **组件** 对象列表，每个包含参数的模板组件对应一个对象：

* `{"type": "body", "parameters": [...]}` 用于正文占位符
* `{"type": "header", "parameters": [...]}` 用于参数化页眉（文本、图片、文档或位置）
* `{"type": "button", "sub_type": ..., "index": ..., "parameters": [...]}` 用于按钮参数

`parameters` 中的每一项都是值对象，例如 `{"type": "text", "text": "Daniele"}`。对于使用命名参数的模板，请为每个值添加 `parameter_name`。省略组件包装层——例如直接在 `template_params` 中传入 `{"type": "text", ...}`——会被拒绝。

### 收件人号码格式

`whatsapp_user_id` 必须仅包含数字：国家/地区代码后接号码，不含 `+`、空格或连字符。例如应使用 `14155552671`，而不是 `+1 (415) 555-2671`。

> **Warning**
>
> 在某些国家/地区，WhatsApp 用于标识用户的 ID 与其拨打号码不同——例如，墨西哥号码在国家/地区代码后会额外带有 `1`（`521...`），巴西
> 号码可能包含或省略第 9 位数字。如果用户此前曾向你发送消息，建议优先使用之前对话中的
> `whatsapp_user_id`，可从对话记录中复制。

### 动态变量、分支和环境

`conversation_initiation_client_data` 字段可为对话设置[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)，并将其固定到特定的[智能体分支](/docs/zh/eleven-agents/operate/versioning)和[环境](/docs/zh/eleven-agents/integrate/environment-variables)：

```json
{
  "dynamic_variables": { "customer_name": "Daniele" },
  "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0",
  "environment": "staging"
}
```

这些设置会在整个对话中保留：用户回复后，智能体将在指定的分支和环境中继续运行。系统会先验证分支和环境——若任一不存在，请求将返回错误，且不会发送消息。

外发对话通过此请求字段接收动态变量；入站对话则通过对话初始化 webhook 接收——请参阅[初始化上下文](/docs/zh/eleven-agents/whatsapp#initialization-context)。

> **Note**
>
> 模板参数仅用于填充模板文本，不会提供给智能体。如果智能体需要使用模板中的值（例如客户姓名），请在
> `dynamic_variables` 中再次传入该值。

### 发送后

成功请求会返回 `conversation_id`，对话记录中会出现该对话，渲染后的模板将作为第一条消息。用户回复前，智能体不会运行。发送模板不会启动最长时长计时器或非活跃计时器；两者都会在对话恢复后开始。`200` 响应表示 ElevenLabs 已接受请求——Meta 之后仍可能拒绝投递。如果消息始终未送达，请参阅[故障排除](/docs/zh/eleven-agents/whatsapp/troubleshooting)。

## 安排外发通话

外发 WhatsApp 通话需要获得用户许可——请参阅[用户通话权限](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions)。在 [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates) 中创建包含 **通话许可请求** 组件的消息模板。安排通话时，ElevenLabs 会检查许可状态：

* 已获许可：立即发起通话。
* 尚未请求许可：发送许可请求模板，用户批准后立即发起通话。
* 用户拒绝许可：对话会被记录为失败，原因为 `User declined the call permission request.`。

#### 控制台

前往 [WhatsApp 页面](https://elevenlabs.io/app/agents/whatsapp)，选择账户，然后点击 ***外发 -> 通话*** 按钮。选择智能体，提供 WhatsApp 用户 ID，并选择通话许可请求模板：

![WhatsApp 外发通话对话框](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp)

#### Python

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.whatsapp.outbound_call(
    whatsapp_phone_number_id="524029457612345",
    whatsapp_user_id="12213231492",
    whatsapp_call_permission_request_template_name="call_permission",
    whatsapp_call_permission_request_template_language_code="en",
    agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    conversation_initiation_client_data={
        "dynamic_variables": {"customer_name": "Daniele"},
    },
)
```

#### TypeScript

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

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.whatsapp.outboundCall({
  whatsappPhoneNumberId: "524029457612345",
  whatsappUserId: "12213231492",
  whatsappCallPermissionRequestTemplateName: "call_permission",
  whatsappCallPermissionRequestTemplateLanguageCode: "en",
  agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
  conversationInitiationClientData: {
    dynamicVariables: { customer_name: "Daniele" },
  },
});
```

#### cURL

```bash
curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_phone_number_id": "524029457612345",
    "whatsapp_user_id": "12213231492",
    "whatsapp_call_permission_request_template_name": "call_permission",
    "whatsapp_call_permission_request_template_language_code": "en",
    "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9",
    "conversation_initiation_client_data": {
      "dynamic_variables": {"customer_name": "Daniele"}
    }
  }'
```

完整请求架构请参阅 [API 参考文档](/docs/zh/api-reference/whats-app/outbound-call)。与外发消息一样，`conversation_initiation_client_data` 可设置动态变量，并将对话固定到某个分支和环境；系统会在安排通话前拒绝未知的分支或环境。

> **Note**
>
> Meta 会对外发通话，以及在[客服窗口 ](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)
> 外发送的通话许可请求收费。
> 安排通话前，请先在 WhatsApp Manager 中添加付款方式。

## 营销活动与批量处理

如需呼叫大量用户，请结合 `whatsapp_params` 使用[批量呼叫](/docs/zh/eleven-agents/phone-numbers/batch-calls)：提供一次电话号码 ID 和通话许可请求模板，并为每位收件人提供一个 `whatsapp_user_id`。

目前外发消息尚无原生批量端点。对于模板营销活动，请为每位收件人调用一次[外发消息端点](/docs/zh/api-reference/whats-app/outbound-message)，并遵守 Meta 对号码的消息限制——请参阅[消息限制](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits)。