WhatsApp Template API

開発者 API

承認済みの WhatsApp テンプレートを、1 回の API 呼び出しで自社システムから送信できます。その後の会話は MonoChat で続けられます。

WhatsApp
REST API
API 専用

概要

WhatsApp Template API を使うと、CRM、ERP、EC サイト、または任意のバックエンドから、MonoChat 経由で承認済みの WhatsApp テンプレートメッセージを顧客に送信できます。1 回のリクエストで、送信元の WhatsApp 番号、顧客の電話番号、テンプレートとその変数を指定します。

顧客が返信すると、その会話は他の会話と同じように MonoChat の受信トレイに届きます。このアプリには専用の画面はなく、すべて 3 つの API エンドポイントを通じて行います。

主な特長

1 回の API 呼び出し。 テンプレートを名前と言語で指定し、ヘッダー、本文、ボタン、カルーセルの変数にお客様のデータを入力して送信します。
チャットに直結。 送信のたびに、会話の ID と MonoChat 内の会話への直接リンクが返されます。
新規顧客にも対応。 電話番号がまだ顧客として登録されていない場合は、送信された名前で顧客が作成されます。

インストールと設定

WhatsApp Business 番号を MonoChat に接続し、認証済みで、Meta に承認されたテンプレートがあることを確認します。
設定 › MonoStore › アプリ から WhatsApp Template API をインストールするか、インストールリンク app.monochat.ai/apps/K6u29LpbwCHBozZ8o を開きます。MonoChat アカウントをお持ちでない場合は、リンクから先にサインアップすると、アプリが自動的にインストールされます。
プロフィール › APIトークン で API トークンを作成します。トークンは一度しか表示されないため、すぐにコピーしてください。
template/list.js を呼び出して、承認済みテンプレートとその変数を確認します。
顧客の電話番号と変数の値を指定して template/send.js を呼び出し、最初のテンプレートを送信します。

MonoChat の設定にある MonoStore のアプリ一覧と WhatsApp Template API

MonoStore の WhatsApp Template API の詳細とインストールボタン

注記

各メッセージには、MonoChat から送信されるテンプレートメッセージと同様に料金が発生します。
メディアの URL は、WhatsApp がファイルを取得するまでアクセス可能な状態にしておく必要があります。
配信に同意いただいた顧客に送信してください。メッセージがブロックまたは報告された番号は、WhatsApp によって制限される場合があります。

機能

テンプレートを一覧取得

WhatsApp 番号の承認済みテンプレートを、言語、カテゴリー、ステータス、変数とともに取得します。これにより、システム側で送信可能なテンプレートを把握できます。

テンプレートを送信

テンプレート名と言語を指定し、ヘッダー、本文、ボタン、カルーセルの変数を渡します。値が不足している場合は送信が停止されるため、入力が不完全なメッセージが顧客に届くことはありません。

担当者に割り当て

担当者のメールアドレスを指定すると、その担当者の名前で会話が開始されます。

メディアヘッダー

有効期限の短いアップロード用認証情報を取得し、画像、動画、ドキュメントを MonoChat のストレージに置いて、その URL をテンプレートのヘッダーとして使用します。

会話リンク

送信のたびに、セッション ID、メッセージ ID、MonoChat で会話を開くリンクが返されます。

わかりやすいエラー

失敗した呼び出しでは、「Channel not found」や「Variable missing」など、問題の内容が示されます。

始める前に

WhatsApp Business 番号が MonoChat に接続され、認証済みであること。チャネルをご覧ください。
送信したいテンプレートが Meta に承認されていること。テンプレートは、こちらから先にメッセージを送る場合や、24 時間のウィンドウ外の顧客に連絡する場合に使います。テンプレートメッセージをご覧ください。
プロフィール › APIトークン で取得した API トークンがあること。APIトークンをご覧ください。
テナントスラッグ を把握していること。MonoChat のアドレスのうち /tenants/ の後ろの部分です。https://app.monochat.ai/tenants/mybusiness の場合、スラッグは mybusiness です。

API リファレンス

このアプリには専用の画面はありません。すべて 3 つのエンドポイントを通じて行い、それぞれ 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 番号の 1 つについて、テンプレートとその変数を一覧取得します。
`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：テンプレートを構成するパーツ。

コンポーネント	内容	説明
`HEADER`	`IMAGE`、`VIDEO`、`DOCUMENT`、またはテキスト	メディアの場合は `format` が指定され、変数は `variables` に表示されます。
`BODY`	変数を含むテキスト	`{{1}}`、`{{2}}` などのプレースホルダーを含むメッセージ本文。
`FOOTER`	テキスト	通常、変数はありません。
`BUTTONS`	URL、クイック返信など	ボタンのテキストと、あればその変数。

上記の例のテンプレートでは、ヘッダーに画像 1 点、本文にテキスト 2 つ（顧客名と商品名）が必要です。フッターは固定（「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 のリストがあり、テンプレートのプレースホルダーの順に指定します。

`type`	`parameters`
`HEADER`	ヘッダーのテキスト変数、またはヘッダーの画像、動画、ドキュメントの公開 URL。
`BODY`	本文の `{{1}}`、`{{2}}`、… を順番に。
`BUTTONS`	変数を持つ各ボタンに 1 つずつの値（例：URL ボタンの動的な部分やクーポンコード）。ボタンの順に指定します。
`CAROUSEL`	`parameters` の代わりに、カルーセルのカード 1 枚につき 1 項目の `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`	その 1 つのパスに対するアップロード専用の認証情報。有効期限は 15 分です。
`baseUrl`	ストレージの公開アドレス。ファイルの URL は `baseUrl` + `/` + `path` です。

この認証情報を使って、任意の S3 クライアントですぐにファイルをアップロードし、テンプレートを送信するときにその URL を HEADER パラメーターとして渡します。サイズが非常に大きいファイルや、WhatsApp が対応していない形式（一般的な画像、動画、PDF 形式に対応）は失敗します。

例：画像ヘッダー付きテンプレート

画像ヘッダーと 2 つの本文変数（顧客名と商品名）を持つ承認済みテンプレート new_product_announcement を、顧客に送信する場合を考えます。

テンプレートを一覧取得する。 お客様の WhatsApp 番号を指定して template/list.js を呼び出し、new_product_announcement を探します。コンポーネントには、ヘッダーに IMAGE 変数が 1 つ、本文に TEXT 変数が 2 つあることが示されています。
画像をアップロードする。 { "fileName": "urun.jpg" } を指定して upload/get-token.js を呼び出し、返された認証情報でファイルをアップロードして、baseUrl と path からその URL を組み立てます。
テンプレートを送信する。 ファイルの URL を HEADER パラメーターに、["Ayşe", "XYZ Telefon"] を BODY パラメーターに指定して template/send.js を呼び出します（{{1}} → Ayşe、{{2}} → XYZ Telefon）。テンプレートにボタンの変数がある場合は、同じ方法で BUTTONS 項目を追加します。
チャットを開く。 レスポンスの 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` がテンプレートと一致していません（例：本文の値が 2 つ必要なのに 1 つしか送信していない）。
`Agent user not found`	`agentEmailAddress` のメールアドレスの担当者が存在しません。
`Customer Channel not found`	顧客の WhatsApp ID を作成または特定できませんでした。

表示される可能性のある HTTP ステータスコード：

401 Unauthorized：Authorization: Bearer <API_TOKEN> ヘッダーがないか、トークンが誤っているか有効期限切れです。お客様のアカウントの有効なトークンを使用してください。
403 Forbidden：トークンにこのワークスペースまたはアプリへのアクセス権がありません（例：テナントスラッグの誤り）。
404 Not Found：エンドポイントのアドレスが誤っています。完全なパス /api/<slug>/custom-functions/template-app/api/... を確認してください。
500 Internal Server Error：MonoChat または WhatsApp プロバイダー側での予期しない問題、もしくは WhatsApp 側による拒否（番号が WhatsApp にない、顧客にブロックされた、品質やレートの制限など）。しばらくしてから再試行し、解決しない場合は MonoChat サポートにお問い合わせください。

スクリーンショット

CRM、ERP、EC システムから、MonoChat 経由で 1 回の API 呼び出しにより承認済みの WhatsApp テンプレートを送信する

承認済み WhatsApp テンプレートと、その変数の一覧

新しい番号にテンプレートを送信すると、顧客が自動的に作成されます

1 つのテンプレートを複数の言語で送信

画像、動画、ドキュメント、PDF のヘッダー付きテンプレート

よくある質問