Bulk Template Message API ドキュメント

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

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

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

主な機能

1 回のリクエストで 1～5,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 件、最大 5,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 配列の各項目は、テンプレートのコンポーネントに対応します。コンポーネントの種類（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}}、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/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`	1 人の受信者に複数の識別子が指定されたか、必須のペイロードが不足しています
`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	1 ページあたりのレコード数（最大：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：レコードの詳細と一覧

一斉メッセージのすべての配信レコードを一覧表示します。各レコードは、受信者に送信された 1 件のメッセージを表します。

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 など）とペイロードを 1 回の照会で確認できます。

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 を使用します
1 ページあたりの最大レコード数（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 を返します

主な機能​

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

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

受信者の構造​

アクションの構造​

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

変数の構造​

パラメーターの形式​

HEADER コンポーネント​

BODY コンポーネント​

BUTTONS コンポーネント​

CAROUSEL コンポーネント​

例​

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

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

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

4. URL ボタンの変数​

5. スケジュール配信​

レスポンス​

エラーレスポンス​

Stats：配信統計​

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

レスポンス​

Stats のフィールド​

参照 ID​

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

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

レスポンス​

Message Stats のフィールド​

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

Options のフィールド​

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

フィルタリングの構造​

ソートの構造​

組み合わせた使用例​

Records：レコードの詳細と一覧​

List：レコード一覧​

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

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

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

レスポンス​

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

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

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

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

レスポンス​

レコードのフィールド​

List と List-With-Messages の比較​

Stop：配信のキャンセル​

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

レスポンス​

主な機能

リクエストパラメーター

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

受信者の構造

アクションの構造

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

変数の構造

パラメーターの形式

HEADER コンポーネント

BODY コンポーネント

BUTTONS コンポーネント

CAROUSEL コンポーネント

例

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

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

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

4. URL ボタンの変数

5. スケジュール配信

レスポンス

エラーレスポンス

Stats：配信統計

リクエストパラメーター

レスポンス

Stats のフィールド

参照 ID

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

リクエストパラメーター

レスポンス

Message Stats のフィールド

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

Options のフィールド

ページネーションの構造

フィルタリングの構造

ソートの構造

組み合わせた使用例

Records：レコードの詳細と一覧

List：レコード一覧

リクエストパラメーター

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

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

レスポンス

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

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

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

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

レスポンス

レコードのフィールド

List と List-With-Messages の比較

Stop：配信のキャンセル

リクエストパラメーター

レスポンス