出站消息与模板 | ElevenLabs Documentation

概述

智能体只能在活跃对话中发送自由格式的 WhatsApp 消息。若要主动联系用户——例如发送通知、重新互动或安排通话——需要发送经 Meta 批准的 消息模板。本页介绍如何创建模板、发送外发消息和通话，以及大规模运行这些操作。

在 WhatsApp Manager 中创建模板

模板需在 WhatsApp Manager 中创建并获批，不在 ElevenLabs 中创建。

创建模板时：

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

Meta 限制单个用户在指定时间段内可接收的营销模板数量。如果营销模板未被投递，常见原因是超出此限制（Meta 错误 131049）。

发送外发消息

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

控制台

Python

TypeScript

cURL

前往 WhatsApp 页面，选择账户，然后点击 外发 -> 消息 按钮。选择智能体，提供 WhatsApp 用户 ID，并选择消息模板及其参数：

完整请求架构请参阅 API 参考文档。

AI 助手可以根据模板调整这些示例。让它参考 ElevenLabs 文档的 llms.txt（或更详细的 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。

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

动态变量、分支和环境

conversation_initiation_client_data 字段可为对话设置动态变量，并将其固定到特定的智能体分支和环境：

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

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

外发对话通过此请求字段接收动态变量；入站对话则通过对话初始化 webhook 接收——请参阅初始化上下文。

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

发送后

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

安排外发通话

外发 WhatsApp 通话需要获得用户许可——请参阅用户通话权限。在 WhatsApp Manager 中创建包含 通话许可请求 组件的消息模板。安排通话时，ElevenLabs 会检查许可状态：

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

控制台

Python

TypeScript

cURL

前往 WhatsApp 页面，选择账户，然后点击 外发 -> 通话 按钮。选择智能体，提供 WhatsApp 用户 ID，并选择通话许可请求模板：

完整请求架构请参阅 API 参考文档。与外发消息一样，conversation_initiation_client_data 可设置动态变量，并将对话固定到某个分支和环境；系统会在安排通话前拒绝未知的分支或环境。

Meta 会对外发通话，以及在客服窗口外发送的通话许可请求收费。安排通话前，请先在 WhatsApp Manager 中添加付款方式。

营销活动与批量处理

如需呼叫大量用户，请结合 whatsapp_params 使用批量呼叫：提供一次电话号码 ID 和通话许可请求模板，并为每位收件人提供一个 whatsapp_user_id。

目前外发消息尚无原生批量端点。对于模板营销活动，请为每位收件人调用一次外发消息端点，并遵守 Meta 对号码的消息限制——请参阅消息限制。