批量模板消息 API 文档

通过该 API，您可以经由 WhatsApp 渠道同时向多个收件人发送模板消息。

消息投递为异步处理：API 请求会立即返回 bulkMessageId，消息则在后台排队并处理。

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js

主要功能

• 单次请求即可向 1–5,000 位收件人 批量发送模板消息
• 为每位收件人提供 个性化变量（HEADER、BODY、BUTTONS、CAROUSEL）
• 所有收件人共用 defaultPayload，并可通过 isMerge 与各收件人专属的 payload 合并
• 定时发送（scheduleAt）
• 可使用 username（电话号码）、userId 或 sessionId 指定收件人
• 在一次批量请求中向 同一用户发送多条消息
• 可选的 referenceId，用于与外部系统的记录对应追踪
• 发送后自动把会话分配给某位用户或某个工作组（action）

注意

该 API 只能发送 已获 Meta 批准 的模板。

模板名称和语言代码必须与在 Meta Business Manager 中注册的模板完全一致。

请求参数

顶层参数

参数	类型	是否必填	说明
channelUsername	string	是	用于发送消息的 WhatsApp 渠道号码（例如 "908506669933"）
connectorBrand	string	是	渠道连接器品牌。当前支持的值："whatsapp"
title	string	否	活动标题。用于在控制台中显示。默认值："-"
scheduleAt	string (ISO 8601)	否	定时发送的日期和时间（例如 "2026-06-10T10:00:00.000Z"）。如果省略，消息会立即发送。
defaultPayload	object	有条件*	应用于所有收件人的默认模板载荷。如果某位收件人没有提供自己的 payload，则为必填。
recipients	array	是	收件人列表。最少 1 位，最多 5,000 位。
action	object	否	发送后对会话执行的操作。assign-to-user 或 assign-to-workgroup。

*如果每位收件人都提供了自己的 payload，则 defaultPayload 为可选。

收件人结构

每位收件人必须 且只能 提供 username、userId 或 sessionId 中的一个。不能同时使用多个标识符，一个都不提供则会报错。

若要在一次批量请求中向同一用户发送多条消息，请在收件人列表中多次添加同一个标识符。

字段	类型	说明
username	string	收件人的电话号码（例如 "905554443322"）。如果该用户在系统中不存在，会自动创建。
userId	string	系统中已有用户的 ID。
sessionId	string	系统中已有会话的 ID。
referenceId	string	可选的引用 ID（最多 256 个字符），用于与外部系统记录（CRM、订单、工单等）对应。如果提供，在同一次批量请求中必须唯一。
payload	object	收件人专属的模板载荷（可选）。如果 isMerge: true，则与 defaultPayload 合并。
isMerge	boolean	覆盖该收件人的合并行为（可选）。如果省略，则使用 defaultPayload.isMerge。

操作结构

字段	类型	说明
action.key	string	"assign-to-user" 把会话分配给指定的客服；"assign-to-workgroup" 把会话分配给某个工作组。
action.value	string	目标用户或工作组的 ID。

---

模板载荷结构

defaultPayload 和收件人专属的 payload 使用相同的结构。对于模板消息，必须指定 type: "template"。

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}

字段	类型	是否必填	说明
type	string	是	载荷类型。模板消息为："template"
template.templateName	string	是*	在 Meta 中注册的模板名称。当使用 isMerge: true 时，在收件人载荷中为可选（继承自默认载荷）。
template.languageCode	string	否	模板语言代码（例如 "tr"、"en"、"tr-TR"、"en-US"）。必须与 Meta 中注册的语言完全一致。
template.variables	array	否	应用于模板组件的变量列表。详见下文。
isMerge	boolean	否	true：收件人载荷与 defaultPayload 深度合并。false 或省略：收件人载荷完全替换 defaultPayload。

isMerge 的行为

• 如果 defaultPayload.isMerge: true 且收件人提供了自己的 payload，则执行深度合并。
• 使用深度合并时，收件人可以只提供 variables；templateName 和 languageCode 继承自默认载荷。
• 收件人的 isMerge 字段会覆盖 defaultPayload.isMerge。
• 如果收件人没有提供 payload，则始终使用 defaultPayload。

---

变量结构

variables 数组中的每一项对应一个模板组件。同一个组件类型（type）在数组中只能出现一次。

type	说明	parameters	cards
"HEADER"	模板标题组件。文本变量或媒体 URL（图片、视频、文档）	是	—
"BODY"	模板正文的文本变量	是	—
"BUTTONS"	按钮的动态 URL 后缀变量	是	—
"CAROUSEL"	轮播模板的卡片组件	—	是

参数格式

parameters 字段可以使用三种不同的格式提供：

// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }

应该使用哪种格式？

• 如果您的 Meta 模板使用 {{1}}、{{2}} 这样的占位符，请使用数组格式或数字键对象格式。
• 如果您的模板使用 {{firstName}} 或 {{orderTotal}} 这样的命名占位符，请使用命名键对象格式。
• 使用数组时顺序很重要：第一个元素对应 {{1}}，第二个对应 {{2}}，依此类推。

HEADER 组件

当模板标题包含媒体（图片、视频、文档）或动态文本时，请使用 HEADER 组件。

// Media header (image URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Text header variable
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

BODY 组件

用于模板正文中的动态文本变量。

// Array format — when the template uses {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Named format — when the template uses {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

BUTTONS 组件

用于带有动态 URL 后缀的按钮。如果模板包含多个 URL 按钮，则只有带变量的按钮会按顺序编号（没有变量的按钮或 FLOW 按钮会被忽略）。

// Single URL button suffix variable
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Multiple URL button suffix variables (first URL button, second URL button)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

CAROUSEL 组件

对于轮播模板，需要为每张卡片分别定义组件变量。

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product A", "99.00 USD"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product B", "149.00 USD"]
        }
      ]
    }
  ]
}

注意

cards 数组的长度必须与模板中定义的卡片数量完全一致。

示例

1. 简单模板：无变量，所有收件人内容相同

这是向多位收件人发送不带变量的静态模板的最简单方式。

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'

提示

• 通过 username 指定的收件人，如果在系统中尚不存在，会被自动创建
• 所有收件人使用同一个 defaultPayload；不需要任何收件人专属数据
• 未指定 isMerge 时，每位收件人直接使用 defaultPayload

---

2. 带共用正文变量的模板

使用相同的变量值，把同一个模板发送给所有收件人。模板包含 {{1}} 和 {{2}} 等占位符。

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Summer Campaign",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30%", "July 31, 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}

提示

• 在这个示例中，模板正文可能包含这样的内容：“活动期间享受 {{1}} 折扣！优惠有效期至 {{2}}。”
• parameters[0] 替换 {{1}}，parameters[1] 替换 {{2}}

---

3. 个性化模板：使用 isMerge 为每位收件人设置变量

每位收件人使用不同的变量值。在 defaultPayload 中设置 isMerge: true 后，收件人只需提供 variables；templateName 和 languageCode 继承自默认载荷。

在这个示例中，模板同时包含媒体标题和个性化的正文变量。

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Personal Order Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "order_confirmation",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-a.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Ahmet", "ORD-001", "150.00 TRY"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289.00 TRY"]
            }
          ]
        }
      }
    }
  ]
}

提示

• 得益于 isMerge: true，不必在每位收件人的载荷中重复 templateName
• 每位收件人的 variables 数组完全相互独立
• 标题媒体的 URL 必须可公开访问
• 如果收件人载荷中省略了 type，则继承 defaultPayload.type

---

4. URL 按钮变量

当模板包含带动态 URL 后缀的按钮时，请使用 BUTTONS 组件。例如，把运单号附加到基础 URL https://example.com/track/ 之后。

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Shipment Tracking Notification",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "shipment_tracking",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Ahmet", "TK-98765"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-98765"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Recep", "TK-12345"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-12345"]
            }
          ]
        }
      }
    }
  ]
}

提示

• BUTTONS 参数按带变量的按钮的顺序进行匹配
• FLOW 按钮和没有变量的按钮会被忽略；编号只适用于动态 URL 按钮
• 如果模板按钮的 URL 是 https://example.com/track/{{1}}，则 parameters[0] 替换 {{1}}

---

5. 定时发送

安排消息在未来的某个日期和时间发送。scheduleAt 必须以 ISO 8601 UTC 时间戳的形式提供。

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Morning Campaign Message",
  "scheduleAt": "2026-06-10T07:00:00.000Z",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "morning_campaign",
      "languageCode": "en-US"
    },
    "isMerge": true
  },
  "action": {
    "key": "assign-to-workgroup",
    "value": "WORKGROUP_ID"
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Ahmet", "discountRate": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Zeynep", "discountRate": "40" }
            }
          ]
        }
      }
    }
  ]
}

提示

• scheduleAt 必须使用 UTC 时区提供（例如，土耳其时间上午 10:00 应使用 07:00:00.000Z）
• 这个示例使用命名参数格式；模板应包含 {{name}} 和 {{discountRate}} 等占位符
• 通过 action，消息投递所产生的会话会自动分配给指定的工作组

---

响应

请求成功时会返回 bulkMessageId，可用于跟踪投递过程：

{
  "bulkMessageId": "abc123xyz789"
}

错误响应

状态	说明
Channel not found	未找到与 channelUsername 和 connectorBrand 匹配的已验证渠道
Channel is not verified	匹配的渠道存在，但尚未通过验证
invalidRequest	为某位收件人提供了多个标识符，或缺少必需的载荷
channelNotFound	未找到与所提供的 channelId 匹配的活动渠道
schema-error	请求体中的某个字段未通过结构校验（缺少必填字段、类型不正确或值不受支持）

返回的 bulkMessageId 可用于下方的接口，以查询投递统计并停止投递。

---

Stats：投递统计

获取批量消息的当前投递状态。返回待处理、成功、失败和已取消记录的数量。

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js

请求参数

参数	类型	是否必填	说明
bulkMessageId	string	是	要跟踪的批量消息 ID（由 createBulkPerRecipient 返回）

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

响应

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "title": "Campaign Title",
    "channelUsername": "908506669933",
    "connectorBrand": "whatsapp",
    "connectorSlug": "whatsapp-cloud",
    "payload": {
      "recipientCount": 100,
      "defaultPayloadType": "template",
      "jobId": "job_abc123"
    },
    "schedule": {
      "date": "2026-06-10T07:00:00.000Z",
      "type": "later"
    },
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-08T10:30:00.000Z"
  },
  "stats": {
    "pending": 45,
    "success": 42,
    "failed": 3,
    "cancelled": 10,
    "total": 100
  }
}

Stats 字段

字段	类型	说明
stats.pending	number	仍在队列中等待的记录数
stats.success	number	已成功处理并投递的记录数
stats.failed	number	投递时出错的记录数
stats.cancelled	number	已取消的记录数
stats.total	number	记录总数（pending + success + failed + cancelled）

备注

stats.success 表示系统已成功交出该消息。它 并不 保证 Meta 已把消息送达收件人。Meta 随后产生的状态更新（例如 delivered、read 或 failed）不会影响该计数器，也不会反映在这里。

Stats 与 Message Stats 的区别

• stats 接口：显示投递任务的状态（pending、success、failed、cancelled）
• message-stats 接口：显示消息的实际状态（pending、sending、sent、delivered、read、error 等）
• 任务可能已成功，但消息可能尚未送达或被阅读

---

引用 ID

referenceId 是一个可选字段，您可以用它把投递记录与您自己系统中的 ID（例如订单号、工单 ID）对应起来，便于追踪。

如果提供，则在同一次批量请求中必须唯一（最多 256 个字符）。

重要

• 并非必须使用
• 在同一条批量消息中不能重复
• 可以在不同的批量消息中重复使用

---

Message Stats：WhatsApp 消息状态

获取批量消息的消息状态统计。与 stats 接口不同，它显示每条记录实际的 message.status，而不是任务状态。

可能的消息状态：pending、sending、sent、delivered、read、deleted、warning、error、unknown、not-sended

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js

请求参数

参数	类型	是否必填	说明
bulkMessageId	string	是	要查询的批量消息 ID

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

响应

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "type": "perRecipient",
    "title": "Campaign Title"
  },
  "messageStats": {
    "pending": 5,
    "sending": 2,
    "sent": 10,
    "delivered": 45,
    "read": 30,
    "deleted": 2,
    "warning": 1,
    "error": 3,
    "unknown": 0,
    "not-sended": 2,
    "no-message": 10,
    "total": 120
  }
}

Message Stats 字段

字段	类型	说明
pending	number	尚未发送的消息
sending	number	正在发送的消息
sent	number	已交给 WhatsApp、但尚未送达的消息
delivered	number	已送达收件人手机的消息
read	number	收件人已阅读的消息
deleted	number	已删除的消息
warning	number	带有警告的消息
error	number	出错的消息
unknown	number	状态未知的消息
not-sended	number	无法发送的消息
no-message	number	尚无消息的记录（仍在排队）
total	number	记录总数

使用提示

• no-message 数量较高，表示投递仍在进行中
• delivered 数量显示消息成功送达的情况
• read 数量可用于衡量活动的互动程度
• 您可以定期轮询该接口，以实时跟踪

---

Options 结构：分页、筛选和排序

list 和 list-with-messages 接口中使用的 options 参数，为分页、筛选和排序提供了标准结构。

Options 字段

字段	类型	是否必填	说明
pagination	object	否	分页设置
filtering	object	否	筛选条件
sorting	object	否	排序设置（例如 {"createdAt": -1}）

分页结构

字段	类型	默认值	说明
currentPage	number	1	要获取的页码
pageItems	number	50	每页记录数（最大值：50）

筛选结构

筛选使用 MongoDB 查询格式。您可以按记录字段筛选。在 list-with-messages 接口中，还可以按消息字段筛选（例如 message.status）。

// Filter by record status
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Filter by message status (only list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filter by multiple statuses using $in (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Exclude specific statuses using $nin (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

排序结构

排序使用 MongoDB 排序格式。1 表示升序，-1 表示降序。

// Sort by creation date descending (newest first)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Sort by multiple fields
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

组合使用示例

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "createdAt": -1
    }
  }
}

这个示例按从新到旧的顺序对已送达的消息排序。

实用提示

• 组合使用 filtering 和 pagination 以进行有针对性的查询
• 响应中包含 options.pagination.totalCount 和 options.pagination.totalPages，便于翻页
• message.status 筛选只在 list-with-messages 接口中有效

---

Records：记录详情与列表

列出某条批量消息的所有投递记录。每条记录代表发送给一位收件人的一条消息。

List：记录列表

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list.js

请求参数

参数	类型	是否必填	说明
bulkMessageId	string	是	要列出的批量消息 ID
options	object	否	分页、筛选、排序选项。详见 Options 结构。

请求：基本用法

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

请求：按指定状态筛选

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "success"
    }
  }
}

仅列出投递成功的记录（record.status = "success"）。

响应

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "slug": "my-workspace",
      "userId": "user_123",
      "sessionId": "session_456",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "createdAt": "2026-06-10T10:00:00.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

List With Messages：带消息详情的列表

具有与 list 接口相同的功能（分页、筛选、排序）。唯一的区别：如果某条记录有 messageId，还会返回相关的 message 对象。这样您只需一次查询，就能看到消息状态（delivered、read、error 等）和载荷。

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list-with-messages.js

请求：基本用法

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

请求：按消息状态筛选

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    }
  }
}

这个示例只获取状态为 “delivered” 的消息。

请求：列出失败的消息

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "error"
    }
  }
}

用于查看遇到投递错误的消息。

响应

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "userId": "user_123",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "message": {
        "_id": "msg_789",
        "status": "delivered",
        "payload": {
          "type": "template",
          "template": {
            "templateName": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z",
        "deliveredAt": "2026-06-10T10:01:05.000Z"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

记录字段

字段	类型	说明
_id	string	记录 ID
bulkMessageId	string	该记录所属的批量消息 ID
userId	string	收件人用户 ID
sessionId	string	会话 ID
messageId	string	已发送消息的 ID（尚未发送时为 null）
referenceId	string	可选的引用 ID（如已提供）
status	string	记录状态：pending、success、failed、cancelled
message	object	消息详情（仅在 list-with-messages 中）

List 与 List-With-Messages 对比

功能	list	list-with-messages
分页	是	是
筛选	是（仅限记录字段）	是（记录字段 + 消息字段）
消息对象	否	是（如果存在 messageId）
性能	快	中等（执行 JOIN）
message.status 筛选	不可用	可用

使用场景

• list：快速列出所有记录、按 referenceId 筛选、查看记录状态
• list-with-messages：查看 WhatsApp 消息状态（delivered、read），检查消息载荷
• 筛选示例：
  • {"status": "failed"} — 投递失败的记录
  • {"referenceId": "ORDER-123"} — 特定的引用 ID
  • {"message.status": "delivered"} — 已送达的消息（仅限 list-with-messages）
  • {"message.status": "read"} — 已阅读的消息（仅限 list-with-messages）
  • {"message.status": "error"} — 出错的消息（仅限 list-with-messages）
  • {"message.status": {"$in": ["delivered", "read"]}} — 已送达或已阅读的消息（仅限 list-with-messages）
  • {"message.status": {"$nin": ["error", "not-sended"]}} — 排除出错和未发送的消息（仅限 list-with-messages）
  • {"status": {"$in": ["success", "pending"]}} — 成功或待处理的记录

性能与使用说明

• list 接口更快；一般的状态检查请优先使用它
• 需要消息详情时，请使用 list-with-messages
• 每页最大记录数（pageItems）为 50；未指定时默认为 50
• message.status 筛选只在 list-with-messages 中有效
• messageId 为 null 的记录，其 message 对象也为 null

---

Stop：取消投递

停止正在进行的批量消息投递。排队的任务会被取消，所有 pending 记录都会变为 cancelled 状态。已按 success 或 failed 处理的记录不受影响。

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js

注意

该操作无法撤销。已停止的投递无法恢复。

请求参数

参数	类型	是否必填	说明
bulkMessageId	string	是	要停止的批量消息 ID

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

响应

请求成功时，响应体为空。HTTP 200 状态表示操作已成功完成。

{}

提示

• 只有通过该 API 创建的批量消息才能被停止
• 停止投递后，您可以使用 stats 接口核实已取消的记录数量
• 如果找不到该批量消息，API 会返回错误：bulkMessageNotFound