WhatsAppテンプレートAPI

WhatsAppメッセージテンプレートは、通常の24時間の会話ウィンドウ外で送信するために承認された、あらかじめ作成されたメッセージです（例：ウェルカムメッセージ、予約リマインダー、再エンゲージメントの通知など）。このAPIを使用すると、テンプレートのリスト取得、作成、編集、送信、確認、削除、および送信をプログラムで行うことができます。

以下のすべてのパスは、APIベースURLからの相対パスです。

https://api.youraiconnector.com/v1

すべてのリクエストには認証が必要です。受け入れられる4つの方法については、認証を参照してください。このページの例では X-API-Key ヘッダー（およびcURL用のクエリパラメータ形式）を使用しています。

注: テンプレートはWhatsApp Business APIチャネルを利用するため、このAPI機能を使用するにはAPIアクセス権とWhatsAppチャネルを含むプランの両方が必要です。これらがない場合、リクエストは403で拒否されます。

サブアカウント（代理店）の操作

承認状態

開いている会話の外で送信されるメッセージは、まずWhatsAppによるレビューを受ける必要があるため、すべてのテンプレートには承認 status が付与されます。

ステータス	意味
`draft`	作成または保存済みですが、レビュー用に送信されていません。まだ編集可能です。
`received`	送信済みで、レビューキューに入っています。
`pending`	レビュー中です。
`approved`	送信が許可されています。
`rejected`	却下されました。`rejection_reason` フィールドに理由が記載されています。修正してから再度送信してください。

draft および rejected のテンプレートのみが編集または（再）送信可能です。テンプレートが approved になるとロックされます。変更が必要な場合は新しく作成してください。

自動承認: 一部のチャネルでは外部レビューの手順が不要です。そのようなチャネル上のキャンペーン用に作成または送信されたテンプレートは、コンテンツID (sid) なしで、直ちに approved として保存されます。

Meta接続アカウントでのテンプレート

これらのエンドポイントは、アカウントがどのWhatsApp接続で実行されているかに関わらず同様に機能しますが、その背後で起こる処理は異なります。

管理されたWhatsApp接続では、テンプレートはメッセージングプロバイダーに登録され、sid はプロバイダーのコンテンツID（HXXXXXXXX…）となります。
独自のWhatsApp Businessアカウントで番号を運用しているアカウント（いずれかのMeta接続オプション）では、テンプレートはその WhatsApp Businessアカウント内で作成および審査され、sid はMeta独自のテンプレートID（"3394843740694756" のような数値文字列）となります。status は引き続き上記の表の値を使用し、rejection_reason には引き続きMetaによる説明が記載されます。

これには2つの追加エンドポイントが存在します。1つは現在どの接続を使用しているかを確認するためのもの、もう1つはテンプレートリストをWhatsApp Businessアカウントと照合するためのものです。WhatsApp Businessアカウントに既に存在するテンプレートは、同期によってライブラリにインポートされるため、その後のGET /whatsapp-templatesでは他のテンプレートと同様にそれらがリスト表示されます。

テンプレートが実行されている接続を確認する

GET /whatsapp-templates/provider

フィールド	説明
`provider`	テンプレートが管理型メッセージングプロバイダーに登録されている場合は`twilio`、独自のWhatsApp Businessアカウントにある場合は`meta`となります。
`lane`	使用されているMeta接続 — `meta_cloud_api`（独自のMetaアプリ）または`meta_embedded`（当社のMetaアプリ経由で接続）。管理型接続の場合は`null`となります。
`waba_id`	テンプレートが作成されるWhatsApp Businessアカウント、または`null`。
`templates_enabled`	Meta接続がまだ完了していない（WhatsApp Businessアカウントやアクセストークンが保存されていない）場合は`false`となります。完了するまで、テンプレートの作成や送信は`400`で失敗します。

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

Metaからテンプレートを同期する

WhatsApp Businessアカウントにあるすべてのテンプレートの承認ステータスを更新し、そこに存在するもののまだライブラリにないテンプレートをインポートします。何度呼び出しても安全です。管理型接続の場合は同期するものがないため、呼び出しは何もしないか、単にテンプレートの数を報告するだけです。

POST /whatsapp-templates/meta-sync

フィールド	説明
`imported`	この呼び出しによってライブラリに追加された、WhatsApp Businessアカウントで見つかったテンプレート。
`updated`	ステータスや詳細が変更された既存のテンプレート。
`total`	同期後のライブラリ内のテンプレート。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

Metaと直接やり取りする（上級者向け）

上記のエンドポイントで公開されていない機能（テンプレートのヘッダー、フッター、ボタン、または完全に手動で構築されたテンプレートなど）が必要な場合、/v1/meta-templatesを使用すると、テンプレートライブラリに何も保存することなく、リクエストをMetaのテンプレートAPIに直接渡すことができます。これは、番号が独自のWhatsApp Businessアカウントで実行されているアカウントでのみ機能します。管理型接続の場合、すべての呼び出しは、最初にMetaアプリを接続するように求める400を返します。

エンドポイント	機能
`GET /meta-templates`	WhatsApp Businessアカウント上のテンプレートを最新のステータスと共にリスト表示します。`?name=`を追加すると、特定のテンプレート名でフィルタリングできます。`{ "success": true, "templates": [...] }`を返します。
`POST /meta-templates`	テンプレートを作成し、Metaの審査に一度のステップで送信します。`name`、`language`、および`body`（または`body`の代わりに完全な`components`配列）が必要です。オプション：`variables`（文字列の配列）、`category`（`MARKETING`、`UTILITY`、または`AUTHENTICATION`）、`header`、`footer`、`buttons`。`{ "success": true, "template": {...} }`を含む`201`を返します。
`DELETE /meta-templates/{name}`	Meta名でテンプレートを削除します（すべての言語が対象）。MetaのテンプレートIDと共に`?hsm_id=`を追加すると、単一の言語のみを削除できます。`{ "success": true, "name": "..." }`を返します。

Metaによって拒否されたテンプレートは、errorにMeta自身の説明を含む400を返します。

テンプレートのリスト取得

アカウント上のすべてのテンプレートを、それぞれの軽量な概要とともに返します。

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

テンプレートの取得

変数、ステータス、タイムスタンプを含む、単一のテンプレートの詳細をすべて返します。

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

アカウントに存在しないテンプレートを指定すると、{ "success": false, "error": "Template not found" } を伴う 404 が返されます。

テンプレートを作成する

キャンペーンの開始メッセージ用のテンプレートを作成し、承認のために一度の手順で送信します。

POST /whatsapp-templates

フィールド	必須	説明
`campaign_id`	はい	テンプレートが属するキャンペーン。
`name`	はい	テンプレートの名前。
`language`	はい	言語コード（例: `en`、`es`、`de`、`pt_BR`、`zh_CN`）。
`body`	はい	メッセージ本文（最大1024文字）。
`variables`	いいえ	本文で使用される変数名の順序付きリスト。

変数のプレースホルダーは {{first_name}}、{first_name}、または [first_name] として記述できます。これらはすべて二重中括弧の形式に正規化されます。

結果はキャンペーンのチャネルによって異なります。

WhatsApp Business API キャンペーン: コンテンツが WhatsApp の審査に送信されます。レスポンスには campaign_status（received または pending）と template_sid が含まれます。
外部審査ステップのないチャネル: テンプレートが保存され、自動的に承認されます（campaign_status: "approved"、template_sid: null）。
キャンペーンに WhatsApp チャネルがない場合: 何も作成されず、campaign_status は not_applicable となります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

レスポンス（審査のために送信済み）

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

スタンドアロンテンプレートの作成

キャンペーンの開始メッセージに紐付けずに、テンプレートライブラリにテンプレートを作成します。これは、このページの残りの部分で説明するライフサイクルの作成ステップです。ここで作成し、編集し、レビューのために送信し、ステータスをポーリングし、不要になったら削除します。

POST /whatsapp-templates/docs

フィールド	必須	説明
`name`	はい	テンプレートの名前。
`language`	はい	言語コード（例: `en`、`es`、`de`、`pt_BR`、`zh_CN`）。
`body`	はい	メッセージテキスト（最大1024文字）。
`variables`	いいえ	本文で使用される変数名の順序付きリスト。
`status`	いいえ	`draft`（デフォルト）は送信せずに保存します。`submitted` はWhatsAppのレビュー用に即座にキューに入れます。
`type`	いいえ	`general`（デフォルト）または `smart_followup`。
`category`	いいえ	`marketing`、`utility`、`authentication`、または `authentication-international`。
`campaign_id`	いいえ	テンプレートをキャンペーンのいずれかにリンクします。

認証（ワンタイムコード）テンプレート。 WhatsAppは自由記述の認証テンプレートを受け付けません。メッセージ本文はWhatsAppによってあらかじめ設定されており、テンプレートには「コードをコピー」ボタンを含める必要があります。category: "authentication"を使用してテンプレートを作成すると、当社がその固定形式で送信します。お客様のbodyはアプリ内に表示されるプレビューとして保持されますが、連絡先が受信するテキストはWhatsApp独自の文言（コード、セキュリティに関する注意喚起、10分間の有効期限に関する注記）となります。変数を1つだけ宣言し（例: ["code"]）、送信時にコードを渡してください（連絡先へのテンプレート送信のvariablesフィールドを参照）。コードは15文字未満である必要があります。

どちらの作成方法を使うべきですか？ 自分で編集して送信できるテンプレートが必要な場合は、これを使用してください。キャンペーンの開始メッセージを設定したい場合は、上記の POST /whatsapp-templates を使用してください。そちらは campaign_id が必要で、キャンペーンに直接書き込まれます。

submitted として作成されたテンプレートはバックグラウンドでWhatsAppのレビューに送信されるため、レスポンスで結果を期待するのではなく、ステータスエンドポイントで結果を確認してください。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

name、language、または body の欠落、サポートされていない言語、draft または submitted 以外の status、不明な type または category、あるいは1024文字を超える本文は、説明付きの error を伴う 400 を返します。キャンペーンのいずれでもない campaign_id は 404 を返します。

テンプレートを更新する

まだ承認されていないテンプレートを編集します。ステータスが draft または rejected のテンプレートのみ編集可能です。name、body、language、variables を組み合わせて指定してください。送信したフィールドのみが変更されます。

PUT /whatsapp-templates/{templateId}

編集を行っても、テンプレートは審査のために再提出されません。その後、submitエンドポイントを使用してください。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "template_id": "template_abc123"
}

すでにapproved状態である（または編集不可である）テンプレートの編集を試みた場合、フィールドを送信しなかった場合、または無効な値を送信した場合は、説明を含むerrorとともに400が返されます。

テンプレートを承認のために提出する

draftまたはrejectedテンプレートを審査のために提出します。外部審査を必要としないチャネル上のテンプレートは即座に承認されます。それ以外のテンプレートはすべてWhatsAppに送信され、返されたstatus（通常はreceivedまたはpending）がテンプレートに保存されます。

POST /whatsapp-templates/{templateId}/submit

フォローアップテンプレートは、提出前に必要な変数を宣言して使用する必要があります。これには、名（first-name）のプレースホルダーと、スマートフォローアップ用の個人コンテキストプレースホルダーが含まれます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

承認ステータスを確認する

テンプレートの現在のステータスをポーリングするための軽量なエンドポイントです。ステータスは保存されたレコードから読み取られます。このレコードはバックグラウンドで定期的に更新されるため、承認や却下が反映されるまでに少し時間がかかる場合があります。

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

テンプレートを削除する

アカウントからテンプレートレコードを削除します。

DELETE /whatsapp-templates/{templateId}

重要: 管理対象の接続では、保存されているレコードのみが削除されます。WhatsAppによってすでに承認済みのコンテンツは、メッセージングプロバイダーに登録されたままになる可能性があります。独自のWhatsApp Businessアカウントで実行されているアカウントでは、テンプレートはそのアカウントからも削除されます。いずれの場合も、キャンペーンでこのテンプレートをまだ使用している場合は、削除する前にそのキャンペーンを別のテンプレートに再設定してください。そうしないと、そのテンプレートに依存する送信は失敗します。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

連絡先へのテンプレート送信

開いている会話がない場合でも、承認済みのテンプレートを連絡先に送信します。これによりチャットセッションが再開されます。contactId または phoneNumber で連絡先を指定し、whatsappTemplateId または templateName でテンプレートを選択できます。

POST /whatsapp-templates/send

フィールド	必須	説明
`contactId`	どちらか一方	連絡先のID。
`phoneNumber`	どちらか一方	連絡先の電話番号（国番号を含め、スペースは入れない）。必要に応じて検索または作成されます。
`whatsappTemplateId`	どちらか一方	テンプレートのID。
`templateName`	どちらか一方	アプリに表示されるテンプレート名。
`firstName`	いいえ	新しく作成された連絡先を埋めるために使用されます。
`lastName`	いいえ	新しく作成された連絡先を埋めるために使用されます。
`email`	いいえ	新しく作成された連絡先を埋めるために使用されます。
`variables`	いいえ	テンプレートの変数に対する明示的な値。変数名をキーとします（例: `{ "code": "482913" }`）。ここで指定された値は、その変数に関して連絡先のフィールドよりも優先されます。指定しなかった変数は、以下に説明するように連絡先の情報から引き続き埋められます。これが、認証テンプレートにワンタイムコードを渡す方法です。

テンプレートの本文は、高度な変数置換をサポートしています。

基本変数: {{first_name}}, {{email}}, {{company}}
デフォルト値: {{first_name|there}} はフィールドが空の場合に there を表示します
変換: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
組み合わせ: {{company|Your Company|uppercase}}

クレジット: テンプレートの送信にはクレジットを消費します。正確なコストは、受信者の国とテンプレートのカテゴリによって異なります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

連絡先識別子とテンプレート識別子の両方が欠落しているリクエストは、400 を返します。アカウントに送信に必要なメッセージング認証情報がない場合、レスポンスは 403 になります。

キャンペーンのライブテンプレートを作成または更新する

キャンペーンの開始テンプレート用の2つ目のエンドポイントセットです。ボディ内の campaign_id ではなく、パスによってスコープが指定されます。これらはすでにライブ状態のキャンペーンに使用するものです。上記のテンプレートの作成とは異なり、ここでの更新はキャンペーンのフォローアップドラフトも審査のために再提出するため、開始テンプレートとそのフォローアップが同期された状態に保たれます。

POST /whatsapp-templates/campaign/{campaignId} はキャンペーンの開始テンプレートを作成します。PUT /whatsapp-templates/campaign/{campaignId} はそれを編集します。キャンペーンにすでにテンプレートが存在している必要があります。存在しない場合、400 が返されます。

フィールド	必須	説明
`name`	はい	テンプレートの名前。
`language`	はい	言語コード（例: `en`、`es`、`de`、`pt_BR`、`zh_CN`）。
`body`	はい	メッセージテキスト（最大1024文字）。
`variables`	はい	本文で使用される変数名の順序付きリスト。テンプレートで変数を使用しない場合は空の配列を渡してください。

cURL (作成)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

編集するには、メソッドを PUT に変更し、同じフィールドを使用します。これにより、開始テンプレート（およびWhatsApp APIキャンペーンの場合はキャンペーンのフォローアップドラフト）が審査のために再提出されます。

アカウントに属していないキャンペーンは 404 を返します。権限のない別のアカウントに属するキャンペーンは 403 を返します。既存のテンプレートがないキャンペーンを編集すると 400 が返されます。

既存の連絡先にテンプレートを送信する

上記の連絡先にテンプレートを送信よりもシンプルな、パススコープの代替手段です。テンプレートと連絡先の両方がすでに存在している必要があります。名前による検索やその場での作成は行われません。

POST /whatsapp-templates/{templateId}/send-to-contact

フィールド	必須	説明
`contactId`	はい	連絡先のID。アカウントに属している必要があります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

クレジット: 送信にはクレジットが消費され、価格は上記のエンドポイントと同じです。存在しない、またはアカウントにない contactId は 403 を返します。存在しない templateId は 404 を返します。

テンプレートを一括送信する

1回の呼び出しで多くの連絡先に1つのテンプレートを送信します。送信前に確認できるコストプレビュー機能があります。

最初にコストを見積もる

何も送信せず、クレジットも消費せずに、宛先国ごとの送信コストの内訳を返します。テンプレートの価格は宛先国ごとに設定されているため、クライアント側での見積もりではなく、実際の連絡先に基づいてサーバー側で計算する必要があります。

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

フィールド	必須	説明
`contactIds`	はい	価格計算対象の連絡先（1回の呼び出しにつき最大500件）。重複は1件としてカウントされます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts は、存在しないID、自分のアカウントのものではないID、または電話番号が登録されていないIDの数をカウントします。見積もりはそれらを除いた残りの連絡先のみを対象とするため、この値が0以外の場合、実際の送信数は選択した連絡先数よりも少なくなります。

バッチ送信

リスト内のすべての連絡先にテンプレートを送信します。連絡先ごとにスマート変数を解決し、送信ごとにクレジットを消費します。

POST /whatsapp-templates/{templateId}/bulk-send

フィールド	必須	説明
`contactIds`	はい	送信先の連絡先（1回の呼び出しにつき最大5000件）。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

失敗した連絡先（見つからない、アカウントに存在しない、または送信エラー）はスキップされ、バッチ処理を停止することなく failed にカウントされます。contactIds が空の場合、送信時に5000件（見積もり時に500件）を超えるIDを指定した場合、または templateId が欠落している場合は 400 が返されます。

失敗したメッセージの再試行

新しいメッセージレコードを作成したり、再度クレジットを消費したりすることなく、失敗したメッセージを再送信するための2つのエンドポイントです。

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template は、失敗したテンプレートメッセージを個別に再試行します。失敗したメッセージにテンプレート内容が含まれていない場合は、キャンペーンからテンプレート内容を再解決します。ステータスが failed で、タイプが template のメッセージのみがこの方法で再試行可能です。

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry はチャネルに依存せず、あらゆる失敗した非テンプレートメッセージ（WhatsApp Webなど）に対して機能し、メッセージのチャネルに基づいて適切な送信経路に振り分けます。ステータス failed、failed_connection、limit_exceeded、または queued_retry を受け入れます。

どちらのエンドポイントもリクエストボディを必要としません。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "Message retry initiated successfully"
}

チャネル非依存バージョンを使用する場合は、パスを .../msg_abc789/retry に変更してください。再試行対象外のステータスのメッセージ、または（テンプレートエンドポイントにおいて）テンプレートメッセージではない場合は 400 が返されます。連絡先またはメッセージが見つからない場合は 404 が返されます。

WhatsApp Business プロフィール

WhatsApp 上の連絡先に表示される WhatsApp Business プロフィール（概要、住所、説明、メールアドレス、ウェブサイト、ビジネスカテゴリ、ロゴ）を管理します。管理された接続と、独自の WhatsApp Business アカウントを実行しているアカウントの両方で機能します。

プロフィールの保存

PUT /whatsapp-templates/profile

フィールド	必須	説明
`phoneNumber`	はい	このプロフィールが属する WhatsApp 番号。アカウントに接続されている必要があります。
`about`	いいえ	プロフィールに表示される短い「概要」テキスト。
`address`	いいえ	ビジネスの住所。
`description`	いいえ	ビジネスの詳細な説明。
`email`	いいえ	プロフィールに表示される連絡先メールアドレス。
`websites`	いいえ	ウェブサイト URL の配列。それぞれ有効な URL である必要があります。
`vertical`	いいえ	ビジネスカテゴリ（例: `Retail` や `Professional Services`）。
`profilePictureHandle`	いいえ	プロフィール写真を設定するために、以下の画像アップロードエンドポイントによって返されるハンドル。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

phoneNumber が欠落している場合、ウェブサイトの URL が無効な場合、または phoneNumber がアカウントに接続されていない場合は、400 または 404 が返されます。

プロフィール写真のアップロード

指定したURLから画像をダウンロードしてWhatsAppにアップロードし、ハンドルを返します。そのハンドルを上記のsave-profile呼び出しの profilePictureHandle として渡すことで、プロフィール写真として設定されます。このエンドポイントは画像のアップロードのみを行い、それ自体で設定を行うわけではありません。

POST /whatsapp-templates/profile/picture

フィールド	必須	説明
`phoneNumber`	はい	このプロフィールが属するWhatsApp番号。
`fileUrl`	はい	アップロードする画像への公開アクセス可能なURL。

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "1234567890123456"
}

data はアップロードされた画像のハンドルです。phoneNumber または fileUrl が欠落している場合、あるいはファイルにWhatsAppアクセストークンがない phoneNumber の場合は 400 が返されます。到達不能または無効な fileUrl の場合は、ダウンロードが失敗した理由を説明するエラーが返されます。

送信者のステータスを確認する

接続されているWhatsApp番号のライブ送信ステータスをメッセージングプロバイダーに対してポーリング（および更新）します。番号が実際に送信可能であることを確認してから利用する場合に便利です。

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "data": "ONLINE"
}

data は ONLINE（通常送信中）、PENDING（検証中）、または DELETED（プロバイダーがこの送信者を認識しなくなったため、番号を再接続してください）のいずれかです。ファイルにWhatsAppビジネス情報がない phoneNumber の場合は 404 が返されます。

AIによるフォローアップテンプレートの生成

当プラットフォームでは、キャンペーンの指示と目標に基づいて、WhatsAppのフォローアップテンプレート（会話が途切れた際に送信する催促メッセージ）をAIが自動作成できます。バックグラウンドで実行されるジョブエンドポイントが1つと、既存の統合との互換性のために保持されている古いエンドポイントが3つあります。いずれもAIクレジットを消費します。

生成ジョブの開始

POST /campaigns/{campaignId}/template-generation

フィールド	必須	説明
`type`	いいえ	`all`（デフォルト）はフォローアップセット全体を作成します。`cold_only`は、返信がなかった連絡先向けのメッセージのみを作成します。

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

レスポンス (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

この呼び出しは、ジョブがキューに入れられるとすぐに返ります。キャンペーン（GET /campaigns/{campaignId}、キャンペーンAPIを参照）を読み取り、完了するまでそのtemplate_generation_statusオブジェクトを監視してください：

フィールド	説明
`status`	ジョブ実行中は`processing`、その後は`completed`または`failed`になります。
`progress`	0から100までの数値。
`current_template`, `total_templates`	ジョブが作成する総数（アウトバウンドまたは複合キャンペーンの場合は11、それ以外は9）のうち、現在までに作成されたテンプレートの数。
`error`	`failed`ジョブが停止した理由（クレジット不足など）。
`started_at`, `completed_at`	ジョブの開始時刻と終了時刻。

生成されたテンプレートは他のテンプレートと同様にキャンペーンに保存されるため、テンプレート一覧に表示され、送信前にWhatsAppの承認プロセスを経る必要があります。400はtypeがallまたはcold_only以外であったことを意味し、404はキャンペーンが存在しないか、別のアカウントに属していることを意味します。

エージェントにはこの呼び出しの対となるPOST /agents/{agentId}/template-generationがあり、エージェント用のフォローアップを作成します。通常、呼び出し中に処理が完了します。AIエージェントAPIのフォローアップメッセージの生成を参照してください。

古い生成エンドポイント

以前の3つのエンドポイントも同様の処理を行いますが、既存の統合を維持するために残されています。新規コードでは、上記のジョブエンドポイントを使用してください。

エンドポイント	機能
`POST /whatsapp-templates/campaign/{campaignId}/generate-async`	キャンペーンのフォローアップ生成をバックグラウンドで開始し、`{ "success": true, "data": { "result": "success", "message": "..." } }`を含む`202`を返します。クレジットは前払いで消費されます（独自のAIキーを使用するアカウントではスキップされます）。キャンペーンの`template_generation_status`は、上記と全く同じように進捗を報告します。
`POST /whatsapp-templates/campaign/{campaignId}/generate-followups`	呼び出し中に9つのフォローアップテンプレートすべてを生成します（自動フォローアップ機能が存在する前に作成されたキャンペーンや、再作成が必要なキャンペーン用）。`data`内に`templatesGenerated`を含む`200`を返します。
`POST /whatsapp-templates/agent/{agentId}/generate-followups`	エージェント向けに行われる同期生成と同じです。レスポンスには`agent_id`、`campaign_id`、`target`が追加されます。テンプレートがエージェントのキャンペーンに書き込まれた場合は`"campaign"`、エージェントにキャンペーンがなくエージェント自体に保存された場合は`"agent"`（`campaign_id: null`を伴う）となります。エージェントが見つからない、または外部のエージェントである場合は`404`となります。

これら3つすべてにおいて、アカウントで自動フォローアップが有効であり、十分なクレジットが必要です。400は不足しているものを特定します。キャンペーンを指定するペアは、キャンペーンが別のアカウントに属している場合に403を返します。

テンプレート API エラー

テンプレートエンドポイントは、標準のエラーエンベロープを返します。

{
  "success": false,
  "error": "Template not found"
}

これらのエンドポイントで 404 が返される場合、通常はリソースが見つからなかったことを意味します。リソースが存在しないか、別のユーザーのアカウントに属しているかのいずれかです。一部のエンドポイント（キャンペーンスコープの作成/更新、および既存の連絡先への送信）では、キャンペーンや連絡先が存在しないのではなく、他人のものである場合に、代わりに 403 を返します。また、一部のエンドポイントには、HTTPステータスを反映した error_code フィールドが含まれています。すべてのエンドポイントで返される可能性のある共通コード（400、401、403（プランにAPIアクセスが含まれていない場合）、429（レート制限）、および 500）については、再試行のガイダンスとともに Errors & Pagination に記載されています。

次のステップ

認証 — リクエストを認証する4つの方法。
エラーとレート制限 — ステータスコードと300リクエスト/分の制限について。
キャンペーンAPI — テンプレートが紐付けられているキャンペーンの管理。

WhatsAppテンプレートAPI #

サブアカウント（代理店）の操作 #

承認状態 #

Meta接続アカウントでのテンプレート #

テンプレートが実行されている接続を確認する #

Metaからテンプレートを同期する #

Metaと直接やり取りする（上級者向け） #

テンプレートのリスト取得 #

テンプレートの取得 #

テンプレートを作成する #

スタンドアロンテンプレートの作成 #

テンプレートを更新する #

テンプレートを承認のために提出する #

承認ステータスを確認する #

テンプレートを削除する #

連絡先へのテンプレート送信 #

キャンペーンのライブテンプレートを作成または更新する #

既存の連絡先にテンプレートを送信する #

テンプレートを一括送信する #

最初にコストを見積もる #

バッチ送信 #

失敗したメッセージの再試行 #

WhatsApp Business プロフィール #

プロフィールの保存 #

プロフィール写真のアップロード #

送信者のステータスを確認する #

AIによるフォローアップテンプレートの生成 #

生成ジョブの開始 #

古い生成エンドポイント #

テンプレート API エラー #

次のステップ #

WhatsAppテンプレートAPI

サブアカウント（代理店）の操作

承認状態

Meta接続アカウントでのテンプレート

テンプレートが実行されている接続を確認する

Metaからテンプレートを同期する

Metaと直接やり取りする（上級者向け）

テンプレートのリスト取得

テンプレートの取得

テンプレートを作成する

スタンドアロンテンプレートの作成

テンプレートを更新する

テンプレートを承認のために提出する

承認ステータスを確認する

テンプレートを削除する

連絡先へのテンプレート送信

キャンペーンのライブテンプレートを作成または更新する

既存の連絡先にテンプレートを送信する

テンプレートを一括送信する

最初にコストを見積もる

バッチ送信

失敗したメッセージの再試行

WhatsApp Business プロフィール

プロフィールの保存

プロフィール写真のアップロード

送信者のステータスを確認する

AIによるフォローアップテンプレートの生成

生成ジョブの開始

古い生成エンドポイント

テンプレート API エラー

次のステップ