Bulk Template Message API ドキュメント — v2

この API を使うと、WhatsApp チャネルを通じて複数の受信者へテンプレートメッセージを同時に送信できます。

メッセージの配信は非同期で処理されます。API リクエストはすぐに bulkOperationId を返し、メッセージはキューに入れられてバックグラウンドで処理されます。

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

レスポンスの形式

このドキュメントのすべてのエンドポイントは custom function です。HTTP レスポンスボディには関数自体のフィールド（_id、title、pathString…）が含まれ、エンドポイントの実際のレスポンスは result の中にあります。このドキュメントのレスポンス例は result の内容を示しています。

{
  "_id": "function_id",
  "title": "Show",
  "pathString": "/bulk-message-api-app/api/v2/bulk-operation/show.js",
  "result": {
    "bulkOperation": { "_id": "abc123xyz789", "status": "running" }
  }
}

v1 からの移行

v2 は v1 と並行して動作するため、ご都合に合わせて移行できます。v1 のエンドポイント（/api/bulk-message/…、/api/bulk-message-records/…）は廃止される予定です。新しい連携では v2 をご利用ください。

エンドポイントのパスを v2 に変更します。…/api/bulk-message/… は …/api/v2/bulk-operation/… に、…/api/bulk-message-records/… は …/api/v2/bulk-operation-items/… になります。send のリクエストボディは変わりません。1 回のリクエストで指定できる受信者は 5,000 件ではなく最大 100,000 件になりました。
リクエストでは bulkMessageId の代わりに bulkOperationId を送信します。
stats.js を show.js に置き換えます。
下の表の新しいフィールド名でレスポンスを読み取ります。

v2 のエンドポイントが扱えるのは、v2 の send で作成された一括操作だけです。切り替え前に v1 で作成した一斉メッセージを追跡するには、そのメッセージについては引き続き v1 のエンドポイントを使用してください。

エンドポイント

v1	v2	レスポンスの変更点
`bulk-message/send.js`	`v2/bulk-operation/send.js`	`{ bulkMessageId }` が `{ bulkOperationId }` になります
`bulk-message/stats.js`	`v2/bulk-operation/show.js`	`{ bulkMessage, stats }` が `{ bulkOperation }` になります
`bulk-message/message-stats.js`	`v2/bulk-operation/message-stats.js`	カウンターは `messageStats` の下ではなくルートにあります
`bulk-message/stop.js`	`v2/bulk-operation/stop.js`	変更なし
`bulk-message-records/list.js`	`v2/bulk-operation-items/list.js`	`bulkMessageRecords` が `bulkOperationItems` になります
`bulk-message-records/list-with-messages.js`	`v2/bulk-operation-items/list-with-messages.js`	`list` と同じで、各アイテムには `session` も含まれます

フィールド名

v1	v2
`stats.success`	`bulkOperation.progress.succeeded`
`stats.pending`、`stats.failed`、`stats.cancelled`、`stats.total`	`bulkOperation.progress.pending`、`.failed`、`.cancelled`、`.total`
—	`bulkOperation.progress.unknown`、`bulkOperation.status`、`bulkOperation.result.outcome`
`bulkMessage`（一斉メッセージ）	`bulkOperation`（一括操作）
`bulkMessageRecord`（レコード）	`bulkOperationItem`（アイテム）
リクエスト、`send` のレスポンス、レコード上の `bulkMessageId`	`bulkOperationId`
送信時のままのレコードの `username` / `userId` / `sessionId`	`payload.username` / `payload.userId` / `payload.sessionId`
レコードの `referenceId`	`payload.referenceId`
レコードの `payload`（受信者のテンプレートペイロード）	`payload.payload`
送信後のレコードの `userId`、`sessionId`、`messageId`	`result.userId`、`result.sessionId`、`result.messageId`
レコードのステータス `success`	`succeeded`
失敗したレコードの `errorMessage`	`error.message`（`error.code` と `error.retryable` も併せて返されます）
—	`position`（`recipients` 内での受信者のインデックス）
フィルター `{"status": "success"}`	`{"status": "succeeded"}`
フィルター `{"referenceId": "…"}`	`{"payload.referenceId": "…"}`
`send` のエラー `schema-error`、`invalidRequest`	`zod-schema-error`（メッセージに無効なフィールドのパスが含まれます）

主な機能

1 回のリクエストで 1～100,000 件の受信者 に一斉テンプレートメッセージを送信
受信者ごとの パーソナライズ変数（HEADER、BODY、BUTTONS、CAROUSEL）
すべての受信者に共通の defaultPayload と、受信者ごとの payload のマージ（isMerge）
スケジュール配信（scheduleAt）
username（電話番号）、userId、sessionId のいずれかで受信者を指定
1 回の一斉送信リクエスト内で、同じユーザーに複数のメッセージ を送信
外部システムのレコードと紐づけて追跡するための任意の 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 件、最大 100,000 件。
`action`	object	いいえ	送信後に会話へ適用するアクション。`assign-to-user` または `assign-to-workgroup`。

*すべての受信者が独自の payload を指定する場合、defaultPayload は省略できます。

受信者の構造

各受信者には、username、userId、sessionId のうち 1 つだけ を指定する必要があります。複数の識別子を同時に使うことはできず、すべて省略するとエラーになります。

1 回の一斉送信リクエスト内で同じユーザーに複数のメッセージを送信するには、同じ識別子を受信者リストに複数回追加します。

フィールド	型	説明
`username`	string	受信者の電話番号（例：`"905554443322"`）。システムにユーザーが存在しない場合は、自動的に作成されます。
`userId`	string	システムに存在する既存ユーザーの ID。
`sessionId`	string	システムに存在する既存の会話セッションの ID。
`referenceId`	string	外部システムのレコード（CRM、注文、チケットなど）と照合するための任意の参照 ID（最大 256 文字）。指定する場合は、一斉送信内で一意である必要があります。
`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 配列の各要素は、テンプレートのコンポーネントに対応します。1 つのコンポーネントタイプ（type）は配列内に 1 回しか指定できません。

type	説明	parameters	cards
`"HEADER"`	テンプレートのヘッダーコンポーネント。テキスト変数またはメディアの URL（画像、動画、ドキュメント）	はい	—
`"BODY"`	テンプレート本文のテキスト変数	はい	—
`"BUTTONS"`	ボタンの動的 URL サフィックス変数	はい	—
`"CAROUSEL"`	カルーセルテンプレートのカードコンポーネント	—	はい

パラメーターの形式

parameters フィールドは、3 種類の形式で指定できます。

// 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 番目の要素が {{1}}、2 番目が {{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/v2/bulk-operation/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 を指定すると、メッセージの配信によって作成された会話が、指定したワークグループに自動的に割り当てられます

レスポンス

リクエストが成功すると bulkOperationId が返されます。これを使って配信の進行状況を追跡できます。

{
  "bulkOperationId": "abc123xyz789"
}

エラーレスポンス

ステータス	説明
`recipients field is required`	`recipients` フィールドが送信されませんでした
`Channel not found`	`channelUsername` と `connectorBrand` に一致する認証済みチャネルが見つかりませんでした
`Channel is not verified`	一致したチャネルは存在しますが、まだ認証されていません
`zod-schema-error`	リクエストボディのフィールドがスキーマ検証に失敗しました（必須フィールドの不足、型の誤り、サポートされていない値、1 人の受信者に複数の識別子、または `payload` の不足）。メッセージにはフィールド名が示されます。例：`recipients.0.referenceId: referenceId must be unique`

返された bulkOperationId は、以下のエンドポイントで配信統計の照会や配信の停止に使用できます。

Show：一括操作のステータスと統計

一括操作を、現在のステータスとそのアイテムの配信カウンターとともに bulkOperation キーの下で取得します。

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

リクエストパラメーター

パラメーター	型	必須	説明
`bulkOperationId`	string	はい	追跡する一括操作の ID（`send` から返されたもの）

{
  "bulkOperationId": "abc123xyz789"
}

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

レスポンス

{
  "bulkOperation": {
    "_id": "abc123xyz789",
    "type": "send-bulk-message",
    "slug": "my-workspace",
    "userId": "agent_user_id",
    "payload": {
      "title": "Campaign Title",
      "channelUsername": "908506669933",
      "connectorBrand": "whatsapp",
      "connectorSlug": "om2WabVegaCloud",
      "defaultLanguageCode": "tr-TR",
      "sentUser": { "firstname": "John", "lastname": "Doe" },
      "defaultPayload": {
        "type": "template",
        "template": { "templateName": "order_confirmation", "languageCode": "tr-TR" },
        "isMerge": true
      },
      "source": { "type": "recipients", "bulkOperationInputGroupId": "group_id" }
    },
    "status": "running",
    "result": { "outcome": "unknown", "hasErrors": false },
    "progress": {
      "total": 100,
      "pending": 45,
      "succeeded": 42,
      "failed": 3,
      "cancelled": 10,
      "unknown": 0
    },
    "scheduleAt": "2026-06-10T07:00:00.000Z",
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-10T07:00:30.000Z",
    "startedAt": "2026-06-10T07:00:05.000Z"
  }
}

Show のフィールド

フィールドは bulkOperation の下にあります。

フィールド	型	説明
`status`	string	一括操作のステータス：`preparing`、`scheduled`、`pending`、`running`、`stopping`、`stopped`、`completed`、`failed`
`progress.total`	number	アイテムの総数
`progress.pending`	number	キューで待機中のアイテム数
`progress.succeeded`	number	配信処理が正常に完了したアイテム数
`progress.failed`	number	配信でエラーが発生したアイテム数
`progress.cancelled`	number	`stop` によってキャンセルされたアイテム数
`progress.unknown`	number	結果を判定できなかったアイテム数
`result.outcome`	string	一括操作が終了した時点の最終結果：`success`、`partial`、`all-failed`、`cancelled`、`unknown`
`result.hasErrors`	boolean	失敗したアイテムが 1 件以上ある場合は `true`
`scheduleAt`	string	配信予定時刻（スケジュールされた一括操作のみ）
`startedAt`、`completedAt`	string	配信の開始日時と終了日時

注記

progress.succeeded は、メッセージがシステムによって正常に引き渡されたことを示します。Meta が受信者にメッセージを配信したことを保証するものでは ありません。Meta が生成するその後のステータス更新（delivered、read、failed など）は、このカウンターには影響せず、ここには反映されません。

Show と Message Stats の違い

show エンドポイント：アイテムの配信ステータス（pending、succeeded、failed、cancelled、unknown）を表示します
message-stats エンドポイント：実際のメッセージのステータス（pending、sending、sent、delivered、read、error など）を表示します
アイテムが succeeded でも、メッセージはまだ配信または既読になっていない場合があります

参照 ID

referenceId は任意のフィールドで、追跡のために、配信アイテムを自社システムの ID（注文番号、チケット ID など）と照合する目的で使用できます。各アイテムでは payload.referenceId として返されます。

指定する場合は、一斉送信内で一意である必要があります（最大 256 文字）。

重要

使用は必須ではありません
同じ一括操作内で重複させることはできません
別の一括操作では再利用できます

Message Stats：WhatsApp メッセージのステータス

一括操作のメッセージステータスの統計を取得します。show エンドポイントとは異なり、アイテムのステータスではなく、送信されたメッセージの実際の 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/v2/bulk-operation/message-stats.js

リクエストパラメーター

パラメーター	型	必須	説明
`bulkOperationId`	string	はい	照会する一括操作の ID

{
  "bulkOperationId": "abc123xyz789"
}

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

レスポンス

{
  "pending": 5,
  "sending": 2,
  "sent": 10,
  "delivered": 45,
  "read": 30,
  "deleted": 2,
  "warning": 1,
  "error": 3,
  "unknown": 0,
  "not-sended": 2,
  "no-message": 20,
  "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	アイテムの総数

使い方のヒント

一括操作が running の間に no-message の件数が多い場合は、配信がまだ進行中であることを示します
delivered の件数は、メッセージが正常に配信されたことを示します
read の件数は、キャンペーンの反応を測る指標として使えます
このエンドポイントを定期的にポーリングして、リアルタイムで追跡できます

Options の構造：ページネーション、フィルタリング、ソート

list および list-with-messages エンドポイントで使用する options パラメーターは、ページネーション、フィルタリング、ソートの標準的な構造を提供します。

Options のフィールド

フィールド	型	必須	説明
`pagination`	object	いいえ	ページネーションの設定
`filtering`	object	いいえ	フィルタリング条件
`sorting`	object	いいえ	ソートの設定（例：`{"position": 1}`）

ページネーションの構造

pagination を送信しない場合は、最初のページが最大 50 件のアイテムとともに返されます。送信する場合は currentPage が必須です。

フィールド	型	デフォルト	説明
`currentPage`	number	—	取得するページ番号（`pagination` を送信する場合は必須）
`pageItems`	number	50	1 ページあたりのアイテム数（最大：50）

フィルタリングの構造

フィルタリングは、アイテムのフィールドに対して MongoDB のクエリ形式で行い、フィールド名はレスポンスに表示されるとおりに使います（例：status、payload.referenceId、result.messageId）。list-with-messages エンドポイントでは、メッセージのフィールド（例：message.status）でも絞り込めます。

// Filter by item status
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "payload.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"]
      }
    }
  }
}

// List items that have no message (only list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

ソートの構造

ソートは MongoDB のソート形式で行います。1 は昇順、-1 は降順を意味します。position は、リクエストの recipients 配列における受信者の順番です（0 から始まります）。

// Sort in the order the recipients were sent in the request
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

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

組み合わせた使用例

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "position": 1
    }
  }
}

この例では、配信済みメッセージの 2 ページ目を受信者の順番で一覧表示します。

実用的なヒント

filtering と pagination を組み合わせて、目的に合ったクエリを作成できます
レスポンスにはページ移動に使える options.pagination.totalCount と options.pagination.totalPages が含まれます
message.status フィルターは list-with-messages エンドポイントでのみ機能します

Items：アイテムの詳細と一覧

一括操作のすべての配信アイテムを一覧表示します。各アイテムは recipients 配列の 1 つの要素を表します。

List：アイテム一覧

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

リクエストパラメーター

パラメーター	型	必須	説明
`bulkOperationId`	string	はい	一覧表示する一括操作の ID
`options`	object	いいえ	ページネーション、フィルタリング、ソートのオプション。詳細は Options の構造を参照してください。

リクエスト：基本的な使い方

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

リクエスト：特定のステータスで絞り込む

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "failed"
    }
  }
}

失敗した配信アイテムのみを、error 内の理由とともに一覧表示します。

レスポンス

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 0,
      "payload": {
        "username": "905554443301",
        "referenceId": "ORDER-12345",
        "payload": {
          "template": {
            "variables": [{ "type": "BODY", "parameters": ["Ahmet", "ORD-001"] }]
          }
        }
      },
      "status": "succeeded",
      "attempt": 1,
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    },
    {
      "_id": "item_2",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 1,
      "payload": { "username": "905554443302", "referenceId": "ORDER-12346" },
      "status": "failed",
      "attempt": 1,
      "error": { "code": "error", "message": "Variable missing", "retryable": false },
      "result": { "userId": "user_124", "sessionId": "session_457" },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

List With Messages：メッセージの詳細付き一覧

list エンドポイントと同じ機能（ページネーション、フィルタリング、ソート）を備えています。違いは、関連する message と session のオブジェクトが存在する場合、各アイテムにそれらも含まれる点です。これにより、メッセージのステータス（delivered、read、error など）とペイロードを 1 回のクエリで確認できます。

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

リクエスト：基本的な使い方

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

リクエスト：メッセージのステータスで絞り込む

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

この例では、ステータスが "delivered" のメッセージのみを取得します。

リクエスト：失敗したメッセージを一覧表示する

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

配信エラーが発生したメッセージを確認するために使用します。

レスポンス

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "position": 0,
      "payload": { "username": "905554443301", "referenceId": "ORDER-12345" },
      "status": "succeeded",
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "message": {
        "_id": "msg_789",
        "type": "template",
        "status": "delivered",
        "payload": {
          "template": {
            "name": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z"
      },
      "session": {
        "_id": "session_456",
        "status": "opened"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

アイテムのフィールド

フィールド	型	説明
`_id`	string	アイテムの ID
`bulkOperationId`	string	このアイテムが属する一括操作の ID
`position`	number	リクエストの `recipients` 配列における受信者の順番（`0` から始まります）
`payload`	object	リクエストで送信されたとおりの受信者（`username` / `userId` / `sessionId`、`referenceId`、`payload`、`isMerge`）
`status`	string	アイテムのステータス：`pending`、`succeeded`、`failed`、`cancelled`、`unknown`
`error`	object	`failed` のアイテムのみ：`code`、`message`、`retryable`
`result.userId`	string	受信者のユーザー ID
`result.sessionId`	string	会話セッションの ID
`result.messageId`	string	送信されたメッセージの ID（メッセージが送信されていない場合はありません）
`completedAt`	string	アイテムが処理された日時
`message`	object	メッセージの詳細（list-with-messages のみ）
`session`	object	会話の詳細（list-with-messages のみ）

List と List-With-Messages の比較

機能	list	list-with-messages
ページネーション	はい	はい
フィルタリング	はい（アイテムのフィールドのみ）	はい（アイテム + メッセージのフィールド）
Message / Session	いいえ	はい（存在する場合）
パフォーマンス	高速	中程度（JOIN を実行）
message.status フィルター	利用不可	利用可能

利用シナリオ

list：すべてのアイテムをすばやく一覧表示、referenceId で絞り込み、アイテムのステータスを確認
list-with-messages：WhatsApp メッセージのステータス（delivered、read）を確認、メッセージのペイロードを調査
フィルタリングの例：
- {"status": "failed"} — 配信に失敗したアイテム
- {"payload.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 のみ）
- {"message": {"$exists": false}} — メッセージのないアイテム（list-with-messages のみ）
- {"status": {"$in": ["succeeded", "pending"]}} — 成功または保留中のアイテム

パフォーマンスと使用上の注意

list エンドポイントのほうが高速です。一般的なステータス確認にはこちらを使用してください
メッセージの詳細が必要な場合は list-with-messages を使用してください
1 ページあたりの最大アイテム数（pageItems）は 50 です。指定しない場合のデフォルトも 50 です
message.status フィルターは list-with-messages でのみ機能します
result.messageId のないアイテムには message オブジェクトがありません

Stop：配信のキャンセル

進行中の一括操作の配信を停止します。すべての pending アイテムは cancelled ステータスに移り、一括操作は stopped になります。すでに succeeded または failed として処理されたアイテムには影響しません。スケジュールされた一括操作も、scheduleAt の時刻より前に停止できます。

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

警告

この操作は元に戻せません。停止した配信を再開することはできません。

リクエストパラメーター

パラメーター	型	必須	説明
`bulkOperationId`	string	はい	停止する一括操作の ID

{
  "bulkOperationId": "abc123xyz789"
}

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

レスポンス

リクエストが成功した場合、レスポンスボディは空です。HTTP 200 ステータスは、操作が正常に完了したことを示します。

{}

ヒント

停止できるのは、この API で作成された一括操作のみです
配信を停止した後は、show エンドポイントでキャンセルされたアイテム数（bulkOperation.progress.cancelled）を確認できます
一括操作が見つからない場合、API は次のエラーを返します：Bulk operation not found.

v1 からの移行​

エンドポイント​

フィールド名​

主な機能​

リクエストパラメーター​

トップレベルのパラメーター​

受信者の構造​

アクションの構造​

テンプレートペイロードの構造​

変数の構造​

パラメーターの形式​

HEADER コンポーネント​

BODY コンポーネント​

BUTTONS コンポーネント​

CAROUSEL コンポーネント​

例​

1. シンプルなテンプレート：変数なし、全受信者に同じ内容​

2. 共通の本文変数を使うテンプレート​

3. パーソナライズしたテンプレート：isMerge による受信者ごとの変数​

4. URL ボタンの変数​

5. スケジュール配信​

レスポンス​

エラーレスポンス​

Show：一括操作のステータスと統計​

リクエストパラメーター​

レスポンス​

Show のフィールド​

参照 ID​

Message Stats：WhatsApp メッセージのステータス​

リクエストパラメーター​

レスポンス​

Message Stats のフィールド​

Options の構造：ページネーション、フィルタリング、ソート​

Options のフィールド​

ページネーションの構造​

フィルタリングの構造​

ソートの構造​

組み合わせた使用例​

Items：アイテムの詳細と一覧​

List：アイテム一覧​

リクエストパラメーター​

リクエスト：基本的な使い方​

リクエスト：特定のステータスで絞り込む​

レスポンス​

List With Messages：メッセージの詳細付き一覧​

リクエスト：基本的な使い方​

リクエスト：メッセージのステータスで絞り込む​

リクエスト：失敗したメッセージを一覧表示する​

レスポンス​

アイテムのフィールド​

List と List-With-Messages の比較​

Stop：配信のキャンセル​

リクエストパラメーター​

レスポンス​

v1 からの移行

エンドポイント

フィールド名

主な機能

リクエストパラメーター

トップレベルのパラメーター

受信者の構造

アクションの構造

テンプレートペイロードの構造

変数の構造

パラメーターの形式

HEADER コンポーネント

BODY コンポーネント

BUTTONS コンポーネント

CAROUSEL コンポーネント

例

1. シンプルなテンプレート：変数なし、全受信者に同じ内容

2. 共通の本文変数を使うテンプレート

3. パーソナライズしたテンプレート：isMerge による受信者ごとの変数

4. URL ボタンの変数

5. スケジュール配信

レスポンス

エラーレスポンス

Show：一括操作のステータスと統計

リクエストパラメーター

レスポンス

Show のフィールド

参照 ID

Message Stats：WhatsApp メッセージのステータス

リクエストパラメーター

レスポンス

Message Stats のフィールド

Options の構造：ページネーション、フィルタリング、ソート

Options のフィールド

ページネーションの構造

フィルタリングの構造

ソートの構造

組み合わせた使用例

Items：アイテムの詳細と一覧

List：アイテム一覧

リクエストパラメーター

リクエスト：基本的な使い方

リクエスト：特定のステータスで絞り込む

レスポンス

List With Messages：メッセージの詳細付き一覧

リクエスト：基本的な使い方

リクエスト：メッセージのステータスで絞り込む

リクエスト：失敗したメッセージを一覧表示する

レスポンス

アイテムのフィールド

List と List-With-Messages の比較

Stop：配信のキャンセル

リクエストパラメーター

レスポンス