WhatsApp 模板 API

WhatsApp 消息模板是预先编写的消息，已获准在正常的 24 小时会话窗口之外发送——例如欢迎消息、预约提醒或重新互动提示。此 API 允许您以编程方式列出、创建、编辑、提交、检查、删除和发送模板。

以下所有路径均相对于 API 基础 URL：

https://api.youraiconnector.com/v1

每个请求都必须经过身份验证。有关四种接受的方法，请参阅身份验证。本页上的示例使用 X-API-Key 标头（以及一种用于 cURL 的查询参数形式）。

注意： 模板运行在 WhatsApp Business API 通道上，因此 API 的这一部分既需要 API 访问权限，也需要包含 WhatsApp 通道的套餐。如果没有这些，请求将被 403 拒绝。

使用子账户（代理机构）

审批状态

由于在开放会话之外发送的消息必须先由 WhatsApp 审核，因此每个模板都带有审批 status：

状态	含义
`draft`	已创建或保存，但尚未发送以供审核。您仍然可以对其进行编辑。
`received`	已提交并进入审核队列。
`pending`	审核中。
`approved`	已获准发送。
`rejected`	已拒绝。`rejection_reason` 字段解释了原因；请修复它，然后再次提交。

只有 draft 和 rejected 状态的模板可以被编辑或（重新）提交。一旦模板处于 approved 状态，它就会被锁定——如果您需要更改，请创建一个新模板。

自动审批： 某些通道不需要外部审核步骤。在此类通道上为营销活动创建或提交的模板会立即存储为 approved，且没有内容 ID (sid)。

Meta 连接账户上的模板

无论您的账户使用哪种 WhatsApp 连接方式，这些端点的工作方式都是相同的，但其背后的处理逻辑有所不同：

在托管 WhatsApp 连接上，模板会在消息服务提供商处注册，且 sid 是该提供商的内容 ID (HXXXXXXXX…)。
在使用自有 WhatsApp Business 账户（任一 Meta 连接选项）的账户上，模板是在该 WhatsApp Business 账户中创建并审核的，且 sid 是 Meta 自己的模板 ID——一个数字字符串，例如 "3394843740694756"。status 仍然使用上表中的值，rejection_reason 仍然包含 Meta 的说明。

为此提供了两个额外的端点：一个用于查询您当前使用的连接方式，另一个用于将您的模板列表与您的 WhatsApp Business 账户进行对账。同步操作会将 WhatsApp Business 账户中已存在的模板导入到您的库中，因此同步后的 GET /whatsapp-templates 会像列出其他模板一样列出它们。

检查模板运行所在的连接方式

GET /whatsapp-templates/provider

字段	描述
`provider`	当模板在托管消息服务提供商处注册时为 `twilio`，当模板位于您自己的 WhatsApp Business 账户中时为 `meta`。
`lane`	当前使用的 Meta 连接方式 — `meta_cloud_api`（您自己的 Meta 应用）或 `meta_embedded`（通过我们的 Meta 应用连接）。在托管连接上为 `null`。
`waba_id`	模板所在的 WhatsApp Business 账户，或 `null`。
`templates_enabled`	当 Meta 连接尚未完成（未存储 WhatsApp Business 账户或访问令牌）时为 `false`。在此之前，创建或提交模板的操作将失败并返回 `400`。

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

从 Meta 同步模板

刷新位于您的 WhatsApp Business 账户中的每个模板的审核状态，并导入所有存在于该账户中但尚未进入您库中的模板。可以根据需要随时调用，无需担心风险。在托管连接上，由于没有可同步的内容，该调用不会执行任何操作，仅报告您拥有的模板数量。

POST /whatsapp-templates/meta-sync

字段	描述
`imported`	在 WhatsApp Business 账户中找到并通过此调用添加到您库中的模板。
`updated`	状态或详细信息发生更改的现有模板。
`total`	同步后您库中的模板。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

直接与 Meta 对话（高级）

如果您需要上述端点未公开的功能（例如模板页眉、页脚、按钮或完全手动构建的模板），/v1/meta-templates 会将您的请求直接传递给 Meta 自己的模板 API，而不会在您的模板库中存储任何内容。它仅适用于号码运行在自有 WhatsApp Business 账户上的账户；在托管连接上，每次调用都会返回 400，要求您先连接一个 Meta 应用。

端点	功能
`GET /meta-templates`	列出您的 WhatsApp Business 账户下的模板及其最新状态。添加 `?name=` 可筛选至特定的模板名称。返回 `{ "success": true, "templates": [...] }`。
`POST /meta-templates`	创建一个模板并将其一步提交至 Meta 进行审核。需要 `name`、`language` 和 `body`（或完整的 `components` 数组，而非 `body`）。可选：`variables`（字符串数组）、`category`（`MARKETING`、`UTILITY` 或 `AUTHENTICATION`）、`header`、`footer`、`buttons`。使用 `category: "AUTHENTICATION"` 时无需 `body`：模板将以 WhatsApp 固定的“一次性验证码”格式提交，包含一个复制验证码按钮，且仅有 `add_security_recommendation`（默认 `true`）和 `code_expiration_minutes`（1 到 90，添加过期提示）选项。返回带有 `{ "success": true, "template": {...} }` 的 `201`。
`DELETE /meta-templates/{name}`	通过 Meta 名称删除模板——包含其所有语言版本。添加带有 Meta 模板 ID 的 `?hsm_id=` 可仅删除单一语言版本。返回 `{ "success": true, "name": "..." }`。

Meta 拒绝的模板会返回 400，并在 error 中包含 Meta 自己的解释。

列出模板

返回您账户上的所有模板，并附带每个模板的简要摘要。

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

获取模板

返回单个模板的完整详细信息，包括其变量、状态和时间戳。

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

如果您的账户中不存在该模板，则会返回 404 以及 { "success": false, "error": "Template not found" }。

创建模板

为营销活动的开场消息创建一个模板，并将其一步提交以供审核。

POST /whatsapp-templates

字段	必填	描述
`campaign_id`	是	模板所属的营销活动。
`name`	是	模板名称。
`language`	是	语言代码，例如 `en`、`es`、`de`、`pt_BR`、`zh_CN`。
`body`	是	消息文本，最多 1024 个字符。
`variables`	否	正文中使用的变量名称的有序列表。

变量占位符可以写为 {{first_name}}、{first_name} 或 [first_name] —— 它们都会被标准化为双花括号形式。

结果取决于营销活动的渠道：

WhatsApp Business API 营销活动： 内容会被发送以进行 WhatsApp 审核。响应包含 campaign_status（received 或 pending）以及 template_sid。
无需外部审核步骤的渠道： 模板会被存储并自动批准（campaign_status: "approved"，template_sid: null）。
营销活动中没有 WhatsApp 渠道： 不会创建任何内容，且 campaign_status 为 not_applicable。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

响应（已提交审核）

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

创建独立模板

在您的模板库中创建一个模板，而不将其绑定到营销活动的开场消息。这是本页面后续生命周期中的创建步骤：在此处创建、编辑、提交审核、轮询其状态，并在不再需要时将其删除。

POST /whatsapp-templates/docs

字段	必填	描述
`name`	是	模板名称。
`language`	是	语言代码，例如 `en`、`es`、`de`、`pt_BR`、`zh_CN`。
`body`	是	消息文本，最多 1024 个字符。
`variables`	否	正文中使用的变量名称的有序列表。
`status`	否	`draft`（默认）仅存储而不提交；`submitted` 立即将其加入 WhatsApp 审核队列。
`type`	否	`general`（默认）或 `smart_followup`。
`category`	否	`marketing`、`utility`、`authentication` 或 `authentication-international`。
`campaign_id`	否	将模板链接到您的某个营销活动。

身份验证（一次性验证码）模板。 WhatsApp 不接受自由文本形式的身份验证模板：消息正文由 WhatsApp 预设，且模板必须包含一个“复制验证码”按钮。当您使用 category: "authentication" 创建模板时，我们会为您以该固定格式提交。您的 body 将作为在应用程序中显示的预览，但您的联系人实际收到的文本是 WhatsApp 自己的措辞（验证码、安全提醒和 10 分钟过期提示）。声明且仅声明一个变量（例如 ["code"]），并在发送时传入验证码（请参阅向联系人发送模板中的 variables 字段）。验证码长度必须小于 15 个字符。无论您的号码是在托管连接上运行，还是在您自己的 Meta 应用程序上运行，此功能的工作方式均相同。

我应该使用哪个创建接口？ 当您想要一个可以自行编辑和提交的模板时，请使用此接口。当您想要设置营销活动的开场消息时，请使用 POST /whatsapp-templates（见上文）——该接口需要 campaign_id 并直接写入营销活动中。

以 submitted 方式创建的模板会在后台发送以进行 WhatsApp 审核，因此请检查状态端点以获取结果，而不是期望在响应中直接获得结果。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

响应

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

缺少 name、language 或 body，使用不支持的语言，status 不是 draft 或 submitted，未知的 type 或 category，或者正文超过 1024 个字符，将返回 400 并附带解释性的 error。如果 campaign_id 不是您的营销活动之一，将返回 404。

更新模板

编辑尚未批准的模板。只有状态为 draft 或 rejected 的模板可以编辑。提供 name、body、language 和 variables 的任意组合 —— 仅会更改您发送的字段。

PUT /whatsapp-templates/{templateId}

编辑不会将模板重新提交以供审核。之后请使用提交端点。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

响应

{
  "success": true,
  "template_id": "template_abc123"
}

尝试编辑已处于 approved（或以其他方式不可编辑）状态的模板、不发送任何字段或发送无效值，将返回 400 以及解释性的 error。

提交模板以供审核

提交 draft 或 rejected 模板以供审核。在不需要外部审核的渠道上的模板会立即获得批准；所有其他模板都会发送至 WhatsApp，返回的 status（通常为 received 或 pending）将存储在模板中。

POST /whatsapp-templates/{templateId}/submit

跟进模板在提交前必须声明并使用其所需的变量：一个名字占位符，以及一个用于智能跟进的个人语境占位符。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

检查审核状态

一个用于轮询模板当前状态的轻量级端点。该状态从存储的记录中读取，记录会在后台定期刷新，因此最近的批准或拒绝可能需要一点时间才能显示。

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

删除模板

从您的账户中删除模板记录。

DELETE /whatsapp-templates/{templateId}

重要提示： 在托管连接上，仅会删除存储的记录——WhatsApp 已经批准的内容可能仍会在消息服务提供商处注册。在独立运行 WhatsApp Business 账户的账户上，该模板也会从该账户中删除。无论哪种情况，如果某个营销活动仍在使用此模板，请在删除前将该营销活动重新指向另一个模板，否则依赖该模板的发送任务将会失败。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

向联系人发送模板

即使在没有开启对话的情况下，也可以向联系人发送已批准的模板——这会重新开启聊天会话。您可以通过 contactId 或 phoneNumber 指定联系人，并通过 whatsappTemplateId 或 templateName 选择模板。

POST /whatsapp-templates/send

字段	必填	说明
`contactId`	二选一	联系人的 ID。
`phoneNumber`	二选一	联系人的电话号码（带国家/地区代码，无空格）。如有需要，将进行查找或创建。
`whatsappTemplateId`	二选一	模板的 ID。
`templateName`	二选一	模板名称，如应用中所示。
`firstName`	否	用于填充新创建的联系人。
`lastName`	否	用于填充新创建的联系人。
`email`	否	用于填充新创建的联系人。
`variables`	否	模板变量的显式值，以变量名为键，例如 `{ "code": "482913" }`。此处提供的值优先于联系人字段中该变量的值；您未指定的变量仍将按如下所述从联系人信息中填充。这就是您如何将一次性代码传递给身份验证模板的方法。

模板正文支持高级变量替换：

基本变量： {{first_name}}, {{email}}, {{company}}
默认值： 如果字段为空，{{first_name|there}} 将显示 there
转换： {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
组合： {{company|Your Company|uppercase}}

额度： 发送模板会消耗额度。具体费用取决于收件人所在的国家/地区以及模板的类别。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

响应

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

如果请求中同时缺少联系人标识符和两个模板标识符，则会返回 400。如果您的账户缺少发送所需的通信凭据，响应将为 403。

创建或更新营销活动的实时模板

这是针对营销活动开场模板的第二组端点，通过路径而非正文中的 campaign_id 进行作用域限定。对于已经上线的营销活动，请使用这些端点：与上文的创建模板不同，在此处进行更新还会重新提交营销活动的后续草稿以供审核，从而确保开场模板及其后续内容保持同步。

POST /whatsapp-templates/campaign/{campaignId} 用于创建营销活动的开场模板。PUT /whatsapp-templates/campaign/{campaignId} 用于编辑模板——营销活动必须已经拥有模板，否则将返回 400。

字段	必填	描述
`name`	是	模板名称。
`language`	是	语言代码，例如 `en`、`es`、`de`、`pt_BR`、`zh_CN`。
`body`	是	消息文本，最多 1024 个字符。
`variables`	是	正文中使用的变量名称的有序列表。如果模板未使用任何变量，请传递一个空数组。

cURL (创建)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

响应

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

若要进行编辑，请将方法更改为 PUT 并使用相同的字段——这会重新提交开场模板（以及 WhatsApp API 营销活动中的后续草稿）以供审核。

如果营销活动不属于您的账户，将返回 404；如果营销活动属于您无权访问的其他账户，将返回 403。编辑没有现有模板的营销活动将返回 400。

将营销活动的已批准模板导入到库中

POST /whatsapp-templates/from-campaign

作为营销活动开场消息而批准的模板仅存在于该营销活动中，因此本页面上的库端点无法通过名称或 SID 找到它。此调用将其作为已批准的模板复制到您的模板库中，并保留相同的提供商内容 SID，因此无需重新提交。此后，它便可与所有库端点配合使用，特别是向现有联系人发送模板。它是通过已弃用的 Campaigns API 发送营销活动模板的替代方案。

字段	必填	描述
`campaign_id`	二选一	您希望将其已批准的开场模板导入库中的营销活动。
`broadcast_id`	二选一	镜像经典营销活动的广播；其营销活动会为您解析。原生广播会返回 `400`，因为其模板已在库中。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/from-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

响应（创建时返回 201，库中已有时返回 200）

{
  "success": true,
  "template_id": "template_abc123",
  "created": true,
  "sid": "HXf6e5c6e85731c9be8b2e6226235e8f34",
  "status": "approved"
}

针对同一营销活动再次调用此接口会返回现有的库模板并附带 created: false，因此在每次发送时运行都是安全的。非您所有的营销活动会返回 404；模板尚未批准的营销活动会返回 400。

向现有联系人发送模板

这是上文向联系人发送模板的一种更简单的路径作用域替代方案：模板和联系人都必须已经存在——系统不会按名称查找或即时创建任何内容。

POST /whatsapp-templates/{templateId}/send-to-contact

字段	必填	描述
`contactId`	是	联系人 ID。必须属于您的账户。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

响应

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

积分： 发送消息会消耗积分，定价方式与上述端点相同。如果 contactId 缺失或不在您的账户中，将返回 403；如果 templateId 不存在，将返回 404。

批量发送模板

在单次调用中向多个联系人发送一个模板，并提供可在提交前展示的费用预览。

先估算费用

返回发送成本，按目标国家/地区细分，且不会实际发送任何内容或扣除额度。模板定价按目标国家/地区计算，因此必须在服务器端针对真实联系人进行计算，而不是在客户端进行估算。

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

字段	必填	说明
`contactIds`	是	需要定价的联系人，每次调用最多 500 个。重复项仅计算一次。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

响应

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts 计算的是缺失的、不属于您的或没有电话号码的 ID 数量——估算仅涵盖其余部分，因此非零值意味着实际发送量将少于您选择的联系人数量。

发送批次

将模板发送给列表中的每个联系人，解析每个联系人的智能变量，并按发送次数扣除额度。

POST /whatsapp-templates/{templateId}/bulk-send

字段	必填	说明
`contactIds`	是	发送目标联系人，每次调用最多 5000 个。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

响应

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

失败的联系人（未找到、不属于您的账户或发送错误）将被跳过并计入 failed，而不会停止整个批次。空的 contactIds、单次发送超过 5000 个 ID（估算为 500 个）或缺失 templateId 将返回 400。

重试失败的消息

用于重新发送失败消息的两个端点，无需创建新的消息记录或再次消耗额度。

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template 专门用于重试失败的模板消息——如果失败的消息本身不包含内容，它会从营销活动中重新解析模板内容。只有状态为 failed 且类型为 template 的消息才能通过这种方式重试。

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry 与渠道无关，适用于任何失败的非模板消息（例如 WhatsApp Web），并根据消息的渠道分发到正确的发送路径。它接受状态 failed、failed_connection、limit_exceeded 或 queued_retry。

这两个端点都不需要请求正文。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "data": "Message retry initiated successfully"
}

对于与渠道无关的版本，请将路径切换为 .../msg_abc789/retry。如果消息的状态不符合重试条件，或者（在模板端点上）不是模板消息，则返回 400。如果联系人或消息缺失，则返回 404。

WhatsApp Business 个人资料

管理在 WhatsApp 上向联系人显示的 WhatsApp Business 个人资料（关于、地址、描述、电子邮件、网站、业务类别和徽标）。适用于托管连接以及运行自身 WhatsApp Business 账户的账户。

保存个人资料

PUT /whatsapp-templates/profile

字段	必填	描述
`phoneNumber`	是	此个人资料所属的 WhatsApp 号码。必须在您的账户上已连接。
`about`	否	个人资料上显示的简短“关于”文本。
`address`	否	商家地址。
`description`	否	较长的商家描述。
`email`	否	个人资料上显示的联系电子邮件。
`websites`	否	网站 URL 数组。每个 URL 都必须是有效的 URL。
`vertical`	否	业务类别，例如 `Retail` 或 `Professional Services`。
`profilePictureHandle`	否	由下方的图片上传端点返回的句柄，用于设置个人资料照片。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

响应

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

缺少 phoneNumber、无效的网站 URL 或未在您的账户上连接的 phoneNumber 将返回 400 或 404。

上传个人资料图片

从您提供的 URL 下载图片并将其上传到 WhatsApp，然后返回一个句柄。将该句柄作为上述保存个人资料调用中的 profilePictureHandle 传递，以将其设置为照片——此端点仅上传图片，不会自行设置它。

POST /whatsapp-templates/profile/picture

字段	必填	描述
`phoneNumber`	是	此个人资料所属的 WhatsApp 号码。
`fileUrl`	是	可公开访问的待上传图片 URL。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

响应

{
  "success": true,
  "data": "1234567890123456"
}

data 是已上传图片的句柄。缺少 phoneNumber 或 fileUrl，或者存档中没有 WhatsApp 访问令牌的 phoneNumber 将返回 400；无法访问或无效的 fileUrl 将返回描述下载失败原因的错误。

检查发送方状态

轮询（并刷新）已连接的 WhatsApp 号码在消息服务提供商处的实时发送状态。在您依赖某个号码之前，这对于确认该号码确实能够发送消息非常有用。

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

响应

{
  "success": true,
  "data": "ONLINE"
}

data 为 ONLINE（正常发送）、PENDING（仍在验证中）或 DELETED（提供商不再识别此发送方——请重新连接该号码）之一。存档中没有 WhatsApp 业务信息的 phoneNumber 将返回 404。

使用 AI 生成跟进模板

该平台可以为您编写 AI Agent 的 WhatsApp 跟进模板（即当对话静止时发送的提醒），这些模板基于 Agent 自身的指令和目标生成。目前有一个作业端点，外加三个为现有集成保留的旧版端点。所有这些端点都会消耗 AI 点数。

启动生成作业

POST /agents/{agentId}/template-generation

字段	描述
`type`	`all`（默认值）写入整个集合。`cold_only` 仅写入从未回复的联系人的消息。

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation",
  {
    method: "POST",
    headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ type: "all" }),
  },
);
const body = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
body = res.json()

此操作有两种返回方式，target 字段会告知您具体是哪一种：

target: "agent" 使用 200 — 模板是在通话期间编写的，结果位于 data 中。通过 Agent 的 follow_up_config（获取 Agent）读取它们。这是常见情况。
target: "campaign" 使用 202 — 任务已排队至 campaign_id 中指定的旧版营销活动。监控该营销活动的 template_generation_status 对象，直到其完成：

字段	说明
`status`	作业运行时为 `processing`，完成后为 `completed` 或 `failed`。
`progress`	0 到 100。
`current_template`, `total_templates`	已编写的模板数量，以及作业总共将编写的模板数量（外呼或组合营销活动为 11 个，否则为 9 个）。
`error`	`failed` 作业停止的原因，例如点数不足。
`started_at`, `completed_at`	作业开始和结束的时间。

生成的模板会显示在列出模板中，并且在发送前仍需通过 WhatsApp 审核。400 表示 type 不是 all 或 cold_only；cold_only 需要一个外呼营销活动，如果 Agent 没有营销活动，则会拒绝并返回 409；404 表示 Agent 不存在或属于另一个账户。

以营销活动为寻址方式的表单 POST /campaigns/{campaignId}/template-generation 仍适用于现有集成，但已与 Campaigns API 的其余部分一起被弃用。

旧版生成端点

三个较早的端点执行相同的工作，保留它们是为了确保现有集成能够继续运行。新代码应使用上述的作业端点。

端点	功能
`POST /whatsapp-templates/campaign/{campaignId}/generate-async`	在后台启动营销活动的跟进生成，并返回 `202` 和 `{ "success": true, "data": { "result": "success", "message": "..." } }`。点数会预先扣除（自带 AI 密钥的账户除外），营销活动的 `template_generation_status` 会按上述方式报告进度。
`POST /whatsapp-templates/campaign/{campaignId}/generate-followups`	在调用期间生成所有九个跟进模板 —— 适用于在自动跟进功能出现之前创建的营销活动，或需要重新编写模板的营销活动 —— 并返回 `200`，其中包含 `templatesGenerated` 和 `data`。
`POST /whatsapp-templates/agent/{agentId}/generate-followups`	与代理相关的同步生成。响应增加了 `agent_id`、`campaign_id` 和 `target`：当模板被写入代理的营销活动时为 `"campaign"`；当代理没有营销活动且模板存储在代理本身时为 `"agent"`（包含 `campaign_id: null`）。代理缺失或属于其他账户时返回 `404`。

这三个端点都需要账户开启自动跟进功能且拥有足够的点数 —— 400 会指出缺失的内容 —— 且针对营销活动的两个端点在营销活动属于其他账户时会返回 403。

模板 API 错误

模板端点返回标准的错误封装：

{
  "success": false,
  "error": "Template not found"
}

在这些端点上收到 404 通常意味着未找到资源——要么是资源不存在，要么是它属于另一个账户。少数端点（活动范围内的创建/更新，以及发送给现有联系人）在活动或联系人属于他人而非不存在时，会返回 403。一些端点还包含一个反映 HTTP 状态的 error_code 字段。所有端点都可能返回的共享代码——400、401、403（您的套餐不包含 API 访问权限）、429（速率限制）和 500——以及重试指南，请参阅错误与分页。

后续步骤

身份验证 — 验证请求的四种方式。
错误与速率限制 — 状态码和每分钟 300 次请求的限制。
AI Agents API — 管理模板所附加到的 Agent。

WhatsApp 模板 API #

使用子账户（代理机构） #

审批状态 #

Meta 连接账户上的模板 #

检查模板运行所在的连接方式 #

从 Meta 同步模板 #

直接与 Meta 对话（高级） #

列出模板 #

获取模板 #

创建模板 #

创建独立模板 #

更新模板 #

提交模板以供审核 #

检查审核状态 #

删除模板 #

向联系人发送模板 #

创建或更新营销活动的实时模板 #

将营销活动的已批准模板导入到库中 #

向现有联系人发送模板 #

批量发送模板 #

先估算费用 #

发送批次 #

重试失败的消息 #

WhatsApp Business 个人资料 #

保存个人资料 #

上传个人资料图片 #

检查发送方状态 #

使用 AI 生成跟进模板 #

启动生成作业 #

旧版生成端点 #

模板 API 错误 #

后续步骤 #

WhatsApp 模板 API

使用子账户（代理机构）

审批状态

Meta 连接账户上的模板

检查模板运行所在的连接方式

从 Meta 同步模板

直接与 Meta 对话（高级）

列出模板

获取模板

创建模板

创建独立模板

更新模板

提交模板以供审核

检查审核状态

删除模板

向联系人发送模板

创建或更新营销活动的实时模板

将营销活动的已批准模板导入到库中

向现有联系人发送模板

批量发送模板

先估算费用

发送批次

重试失败的消息

WhatsApp Business 个人资料

保存个人资料

上传个人资料图片

检查发送方状态

使用 AI 生成跟进模板

启动生成作业

旧版生成端点

模板 API 错误

后续步骤