跳到主要内容

WhatsApp Template API

WhatsApp Template API icon
开发者 API

通过一次 API 调用，从您自己的系统发送已获批准的 WhatsApp 消息模板；之后会话在 MonoChat 中继续。

  • WhatsApp
  • REST API
  • 仅 API
从 MonoStore 安装在 monochat.ai 上查看

概览​

WhatsApp Template API 让您的 CRM、ERP、电商网站或任何后端系统都能通过 MonoChat 向客户发送已获批准的 WhatsApp 模板消息。一次请求即可指明发送所用的 WhatsApp 号码、客户的电话号码、模板及其变量。

客户回复后，会话会像其他会话一样进入您的 MonoChat 收件箱。该应用没有自己的页面：一切都通过三个 API 接口完成。

亮点​

  • 一次 API 调用。 按名称和语言发送模板，并用您的数据填充标题、正文、按钮和轮播变量。
  • 直达聊天。 每次发送都会返回会话 ID 和指向 MonoChat 中该会话的直达链接。
  • 欢迎新客户。 如果该电话号码还不是客户，会用您发送的姓名创建客户。

安装与设置​

  1. 将您的 WhatsApp Business 号码连接到 MonoChat，并确保它已通过验证，且已有获 Meta 批准的模板。
  2. 在 设置 › MonoStore › 应用 中安装 WhatsApp Template API，或打开安装链接 app.monochat.ai/apps/K6u29LpbwCHBozZ8o。如果您还没有 MonoChat 账号，通过该链接可以先注册，并自动为您安装应用。
  3. 在 个人资料 › API 令牌 下创建 API 令牌。令牌只会显示一次，请立即复制。
  4. 调用 template/list.js，查看已获批准的模板及其变量。
  5. 使用客户的号码和变量值调用 template/send.js，发送您的第一个模板。
MonoChat 设置中的 MonoStore 应用列表，其中包含 WhatsApp Template API
MonoStore 中的 WhatsApp Template API 详情页和安装按钮
备注
  • 每条消息的计费方式与从 MonoChat 发送的任何模板消息相同。
  • 在 WhatsApp 获取文件之前，媒体 URL 必须保持可访问。
  • 请只发送给同意接收您消息的客户：消息被屏蔽或被举报的号码可能会被 WhatsApp 限制。

功能​

列出模板​

某个 WhatsApp 号码已获批准的模板，包含语言、类别、状态和变量，让您的系统知道可以发送什么。

发送模板​

按模板名称和语言，带有标题、正文、按钮和轮播变量。缺少任何值都会中止发送，因此不会有填写一半的消息发给客户。

分配给客服​

提供客服的邮箱，会话就会以其名义打开。

媒体标题​

获取短期有效的上传凭证，把图片、视频或文档放到 MonoChat 的存储中，并把其 URL 用作模板的标题。

每次发送都会返回会话 ID、消息 ID 和在 MonoChat 中打开该会话的链接。

清晰的错误提示​

调用失败时会说明出了什么问题，例如“Channel not found”或“Variable missing”。

开始之前​

  • 您的 WhatsApp Business 号码已连接到 MonoChat 并通过验证。请参阅 渠道。
  • 您要发送的模板已获 Meta 批准。模板是您主动联系客户、或在 24 小时窗口之外联系客户的方式。请参阅 模板消息。
  • 您已有来自 个人资料 › API 令牌 的 API 令牌。请参阅 API 令牌。
  • 您知道自己的 租户 slug：您的 MonoChat 地址中 /tenants/ 之后的部分。在 https://app.monochat.ai/tenants/mybusiness 中，slug 是 mybusiness。

API 参考​

该应用没有自己的页面。一切都通过三个接口完成，每个接口都是带有 JSON 请求体的 POST：

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
接口作用
template/list.js列出您某个 WhatsApp 号码的模板及其变量。
template/send.js向客户发送模板，并返回指向会话的链接。
upload/get-token.js为标题图片、视频或文档提供短期有效的上传凭证。

电话号码始终带国家区号书写，且不带 +，例如 905334445566。调用成功时返回 200，该接口的数据位于 result 下。

1. 列出模板​

POST /api/<slug>/custom-functions/template-app/api/template/list.js

列出指定 WhatsApp Business 号码的所有模板：名称、语言代码、类别、组成部分（标题、正文、页脚、按钮）、变量类型和审核状态。

字段是否必填说明
phoneNumber是您在 MonoChat 中的 WhatsApp Business 号码，含国家区号，不带 +。
options否分页和筛选，例如 { "pagination": { "currentPage": 1, "pageItems": 50 } }。
POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

响应（已精简）：

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

如何阅读：

  • name：发送模板时使用的系统名称。
  • languageCode：发送所用的语言。
  • category：WhatsApp 类别（MARKETING、UTILITY、AUTHENTICATION）。
  • components：模板的组成部分。
组件内容说明
HEADERIMAGE、VIDEO、DOCUMENT 或文本对于媒体会给出 format；变量显示在 variables 下。
BODY带变量的文本消息正文，带有 {{1}}、{{2}} 等占位符。
FOOTER文本通常没有变量。
BUTTONSURL、快速回复……按钮文本及其变量（如有）。

上面的示例模板需要一张图片作为标题，以及两段文本作为正文（客户姓名和产品名称）。页脚是固定的（“Teşekkürler”），并且没有按钮。

2. 发送模板​

POST /api/<slug>/custom-functions/template-app/api/template/send.js

向客户发送已获批准的模板。如果该电话号码还不是客户，会创建客户；会打开（或复用）会话，并在其中发送模板。

字段是否必填说明
phoneNumber是发送所用的 WhatsApp Business 号码。它必须已连接到 MonoChat 并通过验证。
templateMessageName是模板的 name，与列表返回的完全一致。
languageCode是模板的语言，与列表返回的一致（例如 tr-TR）。
customerPhoneNumber是客户的 WhatsApp 号码。
variables模板有变量时必填模板变量的值（见下文）。
customerFirstName, customerLastName否当客户在 MonoChat 中是新客户时使用。
agentEmailAddress否把会话分配给使用该邮箱的客服。

变量。 variables 数组中的每一项都有一个 type 和一个 parameters 列表，按模板占位符的顺序给出：

typeparameters
HEADER标题的文本变量，或标题图片、视频或文档的公开 URL。
BODY正文中按顺序排列的 {{1}}、{{2}} 等。
BUTTONS每个带变量的按钮对应一个值（例如 URL 按钮的动态部分或优惠码），按按钮顺序排列。
CAROUSEL不使用 parameters，而是使用 cards 数组，每张轮播卡片对应一项，每项有自己的 components。
{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

缺少任何值都会以 Variable missing 中止发送，因此不会有填写一半的消息发给客户。FOOTER 很少有变量。

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

响应：

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}
  • url：在 MonoChat 中打开该会话，适用于已登录且有权查看的人。
  • sessionId：会话 ID。
  • messageId：该消息在 MonoChat 中的 ID。它的送达和已读状态会像其他消息一样显示在聊天中。

模板中的媒体。 WhatsApp 会从您提供的 URL 下载标题媒体，因此该 URL 必须有效且可公开访问。需要登录的链接无法使用。如果您通过 upload/get-token.js 上传了文件，请使用根据该返回结果构建的文件 URL。

3. 上传标题媒体​

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

当模板的标题是图片、视频或文档时，文件需要有一个 WhatsApp 可以下载的公开地址。该接口会为您提供把文件放到 MonoChat 存储中的短期权限。

字段是否必填说明
fileName是带扩展名的文件名，例如 product.jpg 或 promo.pdf。

文件始终存放在您工作区的 chat-assets 文件夹中；发送 key 字段的旧示例仍然有效，但不再需要该值。

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

返回结果会告诉您文件应放在哪里，并提供用于上传的凭证：

字段说明
bucket, region, path文件存放的位置。
temporaryCredentials仅用于该路径的上传专用凭证，有效期 15 分钟。
baseUrl存储的公开地址。文件的 URL 为 baseUrl + / + path。

请立即使用任意 S3 客户端和这些凭证上传文件，然后在发送模板时把它的 URL 作为 HEADER 参数传入。过大的文件或 WhatsApp 不支持的格式（它接受常见的图片、视频和 PDF 格式）会失败。

示例：带图片标题的模板​

假设您有一个已获批准的模板 new_product_announcement，它有一个图片标题和两个正文变量（客户姓名和产品名称），您想把它发送给某位客户。

  1. 列出模板。 使用您的 WhatsApp 号码调用 template/list.js，找到 new_product_announcement。它的组件显示标题中有一个 IMAGE 变量，正文中有两个 TEXT 变量。
  2. 上传图片。 使用 { "fileName": "urun.jpg" } 调用 upload/get-token.js，用返回的凭证上传文件，并根据 baseUrl 和 path 构建其 URL。
  3. 发送模板。 调用 template/send.js，把文件 URL 作为 HEADER 参数，把 ["Ayşe", "XYZ Telefon"] 作为 BODY 参数（{{1}} → Ayşe，{{2}} → XYZ Telefon）。如果模板有按钮变量，则以同样方式添加一个 BUTTONS 项。
  4. 打开聊天。 返回结果中的 url 会打开该会话；客户回复后，会话会在您的 MonoChat 收件箱中继续。

错误​

失败的调用会返回错误状态和一条说明问题的消息。请在您的系统中记录这些消息，并在需要时向您的用户显示有意义的提示。

消息原因
phoneNumber field is required调用 template/list.js 时没有传入 phoneNumber。
phoneNumber, templateMessageName, customerPhoneNumber fields are required缺少 template/send.js 的必填字段。
Channel not found该 phoneNumber 不是您工作区中的 WhatsApp 号码。
Channel is not verified该 WhatsApp 号码已连接但未通过验证。
Template message not found该号码上没有使用该名称和语言的已批准模板。请检查拼写和 languageCode。
Template message is not approved模板存在，但未获 Meta 批准。
Variable missing: …variables 与模板不匹配，例如模板需要两个正文值而您只发送了一个。
Agent user not found没有与 agentEmailAddress 中邮箱对应的客服。
Customer Channel not found无法创建或找到该客户的 WhatsApp 身份。

您可能看到的 HTTP 状态码：

  • 401 Unauthorized：缺少 Authorization: Bearer <API_TOKEN> 请求头，或令牌错误或已过期。请使用您账号中的有效令牌。
  • 403 Forbidden：该令牌无权访问此工作区或应用，例如租户 slug 有误。
  • 404 Not Found：接口地址有误。请检查完整路径 /api/<slug>/custom-functions/template-app/api/...。
  • 500 Internal Server Error：MonoChat 或 WhatsApp 服务商出现意外问题，或被 WhatsApp 拒绝（该号码未使用 WhatsApp、客户屏蔽了您、质量或频率限制）。请稍后重试，如果问题持续，请联系 MonoChat 支持团队。

截图​

通过 MonoChat，用一次 API 调用从 CRM、ERP 或电商系统发送已获批准的 WhatsApp 模板通过 MonoChat，用一次 API 调用从 CRM、ERP 或电商系统发送已获批准的 WhatsApp 模板已获批准的 WhatsApp 模板及其变量列表已获批准的 WhatsApp 模板及其变量列表向新号码发送模板会自动创建客户向新号码发送模板会自动创建客户同一个模板以多种语言发送同一个模板以多种语言发送带有图片、视频、文档和 PDF 标题的模板带有图片、视频、文档和 PDF 标题的模板

常见问题​

WhatsApp Template API 有用户界面吗？​

不是。它是仅提供 API 的应用，有三个接口：列出模板、发送模板，以及获取媒体标题的上传凭证。

使用前需要准备什么？​

一个已连接到 MonoChat 并通过验证的 WhatsApp Business 号码、已获 Meta 批准的模板，以及来自 个人资料 › API 令牌 的 API 令牌。

客户回复后会怎样？​

会话会像其他会话一样进入您的 MonoChat 收件箱。每次发送还会返回指向该会话的直达链接，您也可以通过邮箱把它分配给客服。

我可以发送给还不是客户的号码吗？​

可以。如果该电话号码还不是客户，会用您发送的姓名创建客户。

模板消息的费用是多少？​

每条消息的计费方式与从 MonoChat 发送的任何模板消息相同。Meta 按类别和收件人所在国家对模板定价；可使用 WhatsApp 群发消息费用计算器估算一次发送的费用。