キャンペーン API

キャンペーンは、AIボットが連絡先と対話するために必要なすべて（指示、実行するチャネル、稼働時間、フォローアップの動作など）をまとめたものです。キャンペーンAPIを使用すると、ダッシュボードではなく独自のコードからキャンペーンの一覧表示、作成、更新、複製、有効化、アーカイブ、微調整を行うことができます。

以下のすべてのエンドポイントは、ベースURL https://api.youraiconnector.com/v1 に対する相対パスです。すべてのリクエストは認証されている必要があります。APIキーの取得方法と渡し方については、APIアクセスおよび認証を参照してください。APIアクセスは有料機能です。これがない場合、リクエストは 403 で拒否されます。

注意: 一部の例ではシンプルな ?apiKey=YOUR_API_KEY クエリ形式を使用し、他の例では X-API-Key ヘッダーを使用しています。どちらもどこでも機能します。設定に適したものを使用してください。

キャンペーンタイプ

キャンペーンを作成する際は、以下のいずれかのタイプを選択する必要があります：

タイプ	用途
`Incoming from Unknown Contacts`	初めてメッセージを送ってきたユーザーに対してボットが返信します。
`Outgoing`	キャンペーンに追加した連絡先に対してボットが会話を開始します。
`Keywords`	不活性 - 使用しないでください。 `Keywords` キャンペーンは不活性です。下位互換性のために受け入れられていますが、すべてのチャネルにおいてインバウンドルーティングからは認識されず、トリガーキーワードも読み込まれません。代わりに、AIエージェントのキーワードタイプの「エントリーポイント」を使用してください。
`Combined`	インバウンドとアウトバウンドの動作を組み合わせたものです。

大文字と小文字は区別されません。 type、status、booking_provider、first_response_mode、bot.anthropic_model、およびbot.ai_speedはすべて大文字・小文字を区別せず、"live"、"Live"、"LIVE"はすべて同じものとして扱われます。値は正規化された形式で保存され、キャンペーンを読み取った際にその形式で返されます。唯一の例外は一時停止のペアです。"Paused"と"paused"は完全に異なる状態であるため、"PAUSED"のような曖昧な綴りは400で拒否され、どちらかを選択するよう求められます。

2つの停止状態

ステータス	書き込み元	意味
`Paused`	プラットフォーム独自の安全チェック（エンゲージメントの低下、繰り返される送信エラー、制限到達）および新しいエージェントとブロードキャストのサーフェス	キャンペーンが保留されています。スケジュールされたスイープにより、理由が解消されれば安全のための停止が自動的に解除されることがあります。
`paused`	ダッシュボードの「一時停止」ボタン、および再開時の `resumed`	人の手によって一時停止されました。スケジュールされた送信は、再開時に破棄され、再構築されます。

どちらの状態でもキャンペーンは停止します。インバウンドルーティングは、ステータスが正確に Live である場合にのみ実行されます。APIから一時停止するには Paused を、再開するには Live を使用してください。小文字のペアはダッシュボードボタン用として存在しており、引き続き機能します。

これらは、1つの会話内でAIが返信を停止した場合の動作とは異なります。これは連絡先ごとのスイッチであり、連絡先上の is_bot_active です。人間が対応を引き継いだとき、連絡先がオプトアウトしたとき、またはAIがチャットを終了したときに設定されます。キャンペーン自体のステータスは影響を受けず、キャンペーン内の他のすべての会話は実行され続けます。1つの連絡先に対してAIを一時停止または再開するを参照してください。

キャンペーンを作成しても、誰がチャネルに応答するかは決定されません。 ルーティングはキャンペーンではなく、AIエージェントの エントリーポイント によって処理されます。各チャネルには、そのチャネルで新規かつ未知の連絡先に応答するエージェントを指定するチャネルデフォルトのエントリーポイントが1つあります。設定は PUT /entry-points/channel-defaults、アカウントでラダーが有効かどうかを確認するには GET /entry-points/routing-status、クリアするには DELETE /entry-points/channel-defaults を使用します。POST /channels/campaign は引き続きレガシーなチャネルごとのキャンペーンルーティングマップを書き込みますが、そのマップはどのチャネルのインバウンドルーティングでも参照されなくなりました。これはロールバック目的でのみ保持されています。これに基づいた構築は行わないでください。両方のインターフェースを並べて確認するには、チャネルをキャンペーンにルーティングするを参照してください。

キャンペーンの一覧表示

GET /campaigns

キャンペーンを新しい順に返します。archived=true を渡さない限り、アーカイブされたキャンペーンは除外されます。

クエリパラメータ

パラメータ	必須	説明
`limit`	いいえ	返すキャンペーンの最大数。デフォルトは `50`、最大は `100` です。
`cursor`	いいえ	ページネーションカーソル。次のページを取得するには、前回のレスポンスから `next_cursor` の値を渡します。
`archived`	いいえ	アーカイブされたキャンペーンを含めるには `true` に設定します。

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

レスポンス

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

next_cursor が null の場合、最後のページに到達しています。

キャンペーンの取得

GET /campaigns/{campaignId}

ライブボット設定（bot）、フォローアップ設定、有効なチャネル、およびキーワードを含む、キャンペーンの完全なドキュメントを返します。タイムスタンプはエポックミリ秒で返されます。

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

レスポンス

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

注: 別の所有アカウントのキャンペーンは 404 Campaign not found を返します（403 ではありません）。そのため、ID が別のアカウントに存在するかどうかを判別することはできません。

キャンペーンの作成

POST /campaigns

新しいキャンペーンを作成します。name と type は必須ですが、それ以外はすべて任意です。同じリクエストに他のキャンペーンフィールド（例：language、ai_mode、または完全な bot 設定オブジェクトなど）を含めることができ、それらは新しいキャンペーンとともに保存されます。所有者と作成時間は自動的に設定されます。

リクエストフィールド

フィールド	必須	説明
`name`	はい	キャンペーン名。
`type`	はい	上記4つのキャンペーンタイプのいずれか。
`language`	いいえ	ボットが返信する言語（例: `"en"`）。
`ai_mode`	いいえ	AIモードがオンかどうか（`true`/`false`）。AIエージェントが回答するキャンペーンでは、読み取り値は保存された値ではなく、エージェントのアクティブトグルを返します。以下の更新に関する注記を参照してください。
`bot`	いいえ	ボット設定オブジェクト（ボット設定フィールドを参照）。
`list_id`	いいえ	関連付ける連絡先リストのID。
`event_id`	いいえ	AIが予約可能なイベントタイプのID。
`event_ids`	いいえ	イベントタイプIDの配列として、複数のイベントタイプを一度に指定します。最初のIDがデフォルトとなります。`event_id`または`event_ids`のいずれかを送信してください。両方を同時に送信することはできません。

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

キャンペーンの更新

PUT /campaigns/{campaignId}

キャンペーンを部分的に更新します。変更したいフィールドのみを送信してください。これが唯一の一般的な更新用動詞です。PATCH /campaigns/{campaignId} は存在しません（2つの PATCH ルートは、限定的な有効化およびアーカイブの切り替えです）。

変更可能なフィールド。 キャンペーンエディターが書き込むすべての項目（name、status、type、language、ai_mode、enabled_channels、トリガーおよびドリップ設定、予約およびフォローアップフラグ、Instagram/Facebook監視フィールド、および bot 設定全体を含む）が対象です。IDと所有権はキャンペーンの存続期間中ロックされます。user、id、created_at は拒否され、エンドポイントが認識しないフィールド名も同様です。拒否はフィールド単位ではなくリクエスト単位で行われます。1つでも不明なキーが含まれていると 400 が返され、そのリクエスト内の何も書き込まれません。

エージェントがバックエンドにあるキャンペーンのai_modeは、エージェントの状態を反映します。 キャンペーンがAIエージェントによって回答される場合、キャンペーンを読み取ると、そのエージェントの有効トグル（AIが応答するかどうかを実際に決定するスイッチ）から派生したai_modeが返されます。そのようなキャンペーンに対してai_modeを書き込むことは可能ですが、読み取り値は変更されません。代わりに（ダッシュボードまたはAgents APIを使用して）エージェントの有効トグルをオンまたはオフにしてください。エージェントのない従来のキャンペーンでは、ai_modeはこれまで通り保存された値を読み書きします。

ボットフィールドは上書きではなくマージされます。 ボット設定は、ドット付きキー（"bot.instructions": "..."）またはネストされたオブジェクト（"bot": { "instructions": "..." }）として送信してください。どちらもリーフ単位で書き込まれるため、省略したフィールドは現在の値を保持します。bot.instructions、bot.goal、bot.rules、bot.personality はすべてこの方法で編集可能であり、ボット設定フィールドにリストされている他のすべてのボット設定も同様です。test_bot、frequency、follow_up_config についても同様です。

ボット設定を全面的に置き換える（送信しなかったフィールドを削除する）には、完全なオブジェクトを指定して bot_replace（または test_bot_replace）を使用してください。同じリクエスト内で同じオブジェクトに対して置換とマージを組み合わせることはできません。それを行うと 400 が返されます。

注意: API経由で bot.* を書き込むと、ライブキャンペーンに即座に反映されます。ダッシュボードエディターの動作は異なり、そこでの編集は下書きとして保存され、クライアントが「公開」をクリックしたときにのみライブになります。そのため、クライアントが公開していないダッシュボードの変更がある場合、それらは test_bot に留まり、bot のAPI読み取りではAIが現在使用している内容が正しく表示されます。

いくつかのフィールドは直接書き込むのではなく、専用のキーを通じて設定されます。list_idは連絡先リスト、event_idはイベントタイプ（またはAIが複数予約できるようにするevent_ids、順序付きのイベントタイプID配列。最初のものがデフォルトとなり、空の配列はすべてリンク解除されます）、contact_ids（連絡先IDの配列）はキャンペーンの連絡先に使用します。ナレッジベースのエントリは、このエンドポイントではなくFAQs APIを通じて管理されます。

タグはマージされず、置き換えられます。 tags を完全な配列として送信すると、それがキャンペーンのタグセットになります。フィールドや単一のタグを追加・編集するエンドポイントについては、キャンペーンタグを参照してください。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

キャンペーンの削除

DELETE /campaigns/{campaignId}

キャンペーンを完全に削除します。この操作は取り消せません。キャンペーンを後で必要になる可能性がある場合は、代わりにアーカイブしてください。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { 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/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true
}

キャンペーンを複製する

POST /campaigns/{campaignId}/duplicate

すべての設定を保持したままキャンペーンのコピーを作成します。コピーは無効な状態で作成され、名前に (copy) というサフィックスが付加されるため、明示的に有効化するまでメッセージが送信されることはありません。

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

レスポンス

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

同一アカウント内での重複コピー。

キャンペーンを有効化または無効化する

PATCH /campaigns/{campaignId}/enabled

キャンペーンのオン/オフを切り替えます。無効化されたキャンペーンは連絡先への関与を停止しますが、すべての設定は保持されます。

リクエストフィールド

フィールド	必須	説明
`enabled`	はい	`true` で有効、`false` で無効にします。ブール値である必要があります。

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

キャンペーンのアーカイブまたは復元

PATCH /campaigns/{campaignId}/archived

キャンペーンをアーカイブまたは復元します。アーカイブされたキャンペーンはデフォルトのキャンペーン一覧には表示されませんが、すべてのデータは保持され、いつでも復元可能です。

リクエストフィールド

フィールド	必須	説明
`archived`	はい	`true` でアーカイブ、`false` で復元します。ブール値である必要があります。

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

ボット設定の更新

PUT /campaigns/{campaignId}/bot-config

これは、個々のボット設定を変更するための安全な方法です。送信した各フィールドは既存のボット設定にマージされるため、省略したフィールドはそのまま保持されます。ボットの一部のみを調整したい場合は、campaign-updateエンドポイントの代わりにこちらを使用してください。

フィールドキーには、英数字、アンダースコア、ハイフンのみを使用してください。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

ボット設定フィールド

すべてのボットフィールドは任意です。設定したいフィールドのみを送信してください。ここに記載されている以外の追加のボットフィールドも受け入れられ、そのまま保存されます。

フィールド	型	説明
`instructions`	string	ボットが連絡先とどのように会話するかを制御する主要な指示です。
`rules`	string	ボットが常に従わなければならない厳格なルールです。
`goal`	string	各会話においてボットが目指すべき成果です。
`personality`	string	ボットの口調や性格の説明です。
`ai_speed`	string	返信する前にAIが適用する推論の度合いです。`fast`、`fast_thinker`、`balanced`、`thorough` のいずれかです。
`anthropic_model`	string	このキャンペーンの返信に使用されるAI品質ティアです。`standard`、`economy`（非推奨）、`max`、`mini` のいずれかです。`max` および `mini` は、それらのティアを利用可能なアカウントでのみ有効になります。
`max_messages`	integer	1会話あたりのボットの最大メッセージ数です。
`alert_human_when`	string	ボットが人間のチームメンバーに通知を送る条件です。
`availability`	object	ボットの稼働時間スケジュールです。ここで設定するか、専用の稼働時間エンドポイントを使用できます。
`follow_up_config`	object	フォローアップ動作の設定であり、提供された通りに保存されます。

ボットの稼働時間の設定

PUT /campaigns/{campaignId}/active-hours

ボットの利用可能スケジュールを設定します。設定された時間外では、ボットは自動的に返信しません。これはボット設定の availability フィールドを書き換えます。

リクエストフィールド

フィールド	必須	説明
`availability`	はい	曜日をキーとするオブジェクト。許可されるキーは `monday` から `sunday` までです。それ以外のキーを指定すると `400` が返されます。省略した曜日の設定は変更されません。

各曜日には、単一の時間枠、または時間枠の配列を指定します。時間枠には、24時間形式の HH:MM で表される start_time と end_time が含まれます。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

キャンペーンのカスタム関数を一覧表示する

GET /campaigns/{campaignId}/custom-functions

このキャンペーンにリンクされているカスタム関数を、完全な定義に解決して返します。カスタム関数は、ボットが会話中に呼び出せる外部のHTTPアクションです（例：ストアの在庫確認やCRMでのレコード作成など）。

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

レスポンス

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

カスタム関数をキャンペーンにリンクする

POST /campaigns/{campaignId}/custom-functions

既存のカスタム関数をこのキャンペーンにリンクし、ボットが会話中にその関数を呼び出せるようにします。すでにリンクされている関数をリンクしようとしても、何も起こりません。

フィールド	必須	説明
`custom_function_id`	はい	リンクするカスタム関数のID。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

カスタム関数をキャンペーンからリンク解除する

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

リンクされていない関数をリンク解除しようとしても、何も起こりません。

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

ナレッジベースソースをキャンペーンにリンクする

POST /campaigns/{campaignId}/kb-sources

ナレッジベースソース（FAQs API経由で作成）をこのキャンペーンにリンクし、ボットが回答時にそれを参照できるようにします。すでにリンクされているソースをリンクしようとしても、何も起こりません。

フィールド	必須	説明
`kb_source_id`	はい	リンクするナレッジベースソースのID。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

ナレッジベースソースをキャンペーンからリンク解除する

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

リンクされていないソースをリンク解除しようとしても、何も起こりません。

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

MCPサーバーをキャンペーンにリンクする

POST /campaigns/{campaignId}/mcp-servers

MCPサーバーをこのキャンペーンにリンクし、会話中にボットがそのサーバーのツールにアクセスできるようにします。すでにリンクされているサーバーをリンクしようとしても、何も起こりません。

フィールド	必須	説明
`mcp_server_id`	はい	リンクするMCPサーバーのID。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

キャンペーンからMCPサーバーのリンクを解除する

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

リンクされていないサーバーのリンクを解除しようとしても、何も起こりません。

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

キャンペーンメディアライブラリ

メディアライブラリには、会話中にボットが送信できる画像、動画、ドキュメント、音声メモが保持されます。

キャンペーンのメディアライブラリを一覧表示する

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url はアップロード時に取得された署名付きURLです。読み取り時にはすでに期限切れになっている可能性があります。ダッシュボードは必要に応じて再署名を行います。

メディアアイテムをアップロードする

POST /campaigns/{campaignId}/media-library

フィールド	必須	説明
`base64Data`	はい	base64エンコードされたファイル（data-URLプレフィックスなし）。
`mimeType`	はい	ファイルのMIMEタイプ（例: `image/png`）。
`title`	はい	ライブラリおよびAIプロンプトに表示される短いラベル。
`description`	はい	ボットがこのアイテムを送信するタイミングを指示する命令。
`fileName`	いいえ	ストレージオブジェクト名の作成に使用される元のファイル名。
`sendMessage`	いいえ	ボットがこのアイテムを送信する際に使用すべき推奨文言。
`maxSendsPerConversation`	いいえ	会話内でボットが1人の連絡先に対してこのアイテムを送信できる最大回数。デフォルトは `1` です。
`sendAsVoiceNote`	いいえ	音声アップロードの場合、WhatsAppの音声メモにトランスコードします。デフォルトは `false` （通常の音声ファイルとして保存）です。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

レスポンス

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

メディアアイテムの更新

PATCH /campaigns/{campaignId}/media-library/{itemId}

アイテムのメタデータのみを編集します。ファイル自体を置き換えるには、アイテムを削除して新しいものをアップロードしてください。

フィールド	説明
`title`	短いラベル。
`description`	送信タイミングの指示。
`send_message`	ボットが使用する推奨文言。
`max_sends_per_conversation`	負ではない整数、または上限を解除する場合は `null`。

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

メディアアイテムの削除

DELETE /campaigns/{campaignId}/media-library/{itemId}

すでに削除されているアイテムを削除しようとしても、何も起こりません。

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

レスポンス

{ "success": true, "deleted": true }

キャンペーンタグ

キャンペーンタグとは、会話中にボットが連絡先に適用するように設定するラベルのことです（例: hot-lead、not-interested、booked-a-call）。各タグには3つの要素があります。

フィールド	型	説明
`name`	string, 必須	ラベルそのものです。これはボットが連絡先に適用し、後で照合に使用するものであるため、短く固定したものにしてください。
`description`	string	ボットにこのタグを適用するタイミングを指示する命令です。これが実際に機能する部分です。「ユーザーがコミュニティへの参加を確認した」といった具体的な内容を使用し、「ホットリード」のような抽象的なものは避けてください。
`webhook`	string	タグが連絡先に適用された瞬間に `POST` を受け取るURLです。不要な場合は省略してください。
`tag_id`	string	オプション。このエントリをアカウント内の既存のタグにリンクさせます（新規作成ではありません）。以下の単一タグ用エンドポイントを使用して後でこの特定のタグを操作したい場合に指定してください。

タグ名はキャンペーン内で一意である必要があります。ボットは名前によってタグを適用するため、同じ名前を持つエントリが2つある場合、どちらが適用されるかは定義されません。

キャンペーンの全タグを設定する

PUT /campaigns/{campaignId} を tags 配列とともに使用します。

これにより、キャンペーンのタグが送信した内容に完全に置き換えられます。これは、ダッシュボードの「タグ」タブで保存したときと同じ動作です。毎回完全な配列を送信してください。送信しなかったタグは削除されます。[] を送信すると、すべてのタグがクリアされます。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

タグを読み取るには GET /campaigns/{campaignId} を使用します。

タグを1つ追加する

POST /campaigns/{campaignId}/tags

残りのタグを再送信することなく、タグを1つ追加します。このリクエストで構築していないセットに追加する場合に使用します。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

まったく同じタグを2回投稿しても、2回目は何も起こりません。同じ tag_id を異なる名前や説明で投稿すると、最初のエントリを編集するのではなく、2番目のエントリとして追加されます。その場で編集するには、以下のエンドポイントを使用してください。

タグを1つ更新または削除する

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

これらはtag_idによって1つのエントリを指定するため、それを使用して作成されたタグでのみ機能します。tag_idがないタグの場合は、上記の配列全体を対象とするPUT /campaigns/{campaignId}で変更してください。

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

キャンペーンに含まれていない tagId は、"Tag not found in campaign tags" を伴う 404 を返します。

キャンペーンのチャネルを切り替える

POST /campaigns/{campaignId}/channels

キャンペーンの enabled_channels 配列に対してチャネルの追加や削除を行います。配列全体を再送信するよりも安全で、他のプロセスが同時にキャンペーンを編集している可能性がある場合に PUT /campaigns/{campaignId} よりも適しています。

単一の切り替え、またはバッチ処理のいずれかを送信してください。同じリクエスト内で両方を行うことはできません。

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

フィールド	説明
`channel`	切り替えるチャネルを1つ指定します。`action` と組み合わせて使用してください。
`action`	`"add"` または `"remove"`。`channel` と組み合わせて使用してください。
`add`	追加するチャネルの配列。バッチ形式 — `channel`/`action` の代わりに使用してください。
`remove`	削除するチャネルの配列。バッチ形式。

有効なチャネル: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

これはキャンペーンが宣伝するチャネルを変更するだけであり、誰がチャネルに応答するかを決定するものではありません。その詳細については、上記のキャンペーンタイプおよび以下のキャンペーンをインバウンドチャネルにルーティングするを参照してください。

コメントからDMへ (InstagramおよびFacebook)

「コメントからDMへ」機能は、投稿へのコメントをプライベートな会話へと変換します。ユーザーがコメントするとボットがDMを送信し、そこからキャンペーンが会話を引き継ぎます。これはすべてキャンペーンオブジェクトを通じて設定されるため、UIのみで完結する設定項目はありません。

まずFacebookページを接続してください（チャネル接続を参照）。その後、PUT /campaigns/{campaignId}を使用して以下のフィールドを設定します。

キャンペーンはLiveである必要があります。 コメント監視は、statusがLiveであるキャンペーンのみを対象とします（大文字・小文字は区別されません。キャンペーンタイプを参照してください）。その他のステータスではサイレントに無効化され、"Active"のような存在しないステータスは、保存されるのではなく400で拒否されるようになりました。有効なステータスには、Draft、Pending Approval、Scheduled、Live、Paused、Completed、Sent、Failedが含まれます。

フィールド

フィールド	型	説明
`monitor_instagram_posts`	boolean	接続されたページのすべてのInstagram投稿を監視します。
`instagram_post_ids`	string[]	指定したInstagram投稿のみを監視します。`monitor_instagram_posts`がオンの場合は設定しないでください。
`instagram_comment_delay_minutes`	number	コメントからDM送信までの待機時間（分単位）。
`monitor_facebook_posts`	boolean	接続されたページのすべてのFacebook投稿を監視します。
`facebook_post_ids`	string[]	指定したFacebook投稿のみを監視します。
`facebook_comment_delay_minutes`	number	DM送信までの遅延時間（分単位）。
`public_comment_reply_instructions`	string	コメント欄に残す公開返信のガイダンス。デフォルトの「DMを確認してください」という文言を上書きします。
`first_response_mode`	string	`"ai"`（デフォルト）は最初のDMと公開返信を生成します。`"exact_text"`はAI生成を行わず、クレジットも消費せずに、指定した文言をそのまま送信します。
`first_response_exact_text`	string	`first_response_mode`が`"exact_text"`の場合に使用される、最初のDMのそのままの文言。そのモードを有効にするために必須です。
`first_response_exact_text_variants`	string[]	最初のDMの追加文言。送信ごとにランダムで1つ選択されるため、繰り返されるDMが完全に同一になることはありません。
`public_comment_reply_exact_text`	string	`"exact_text"`モードにおける、公開返信のそのままの文言。空欄にすると公開返信をスキップし、DMのみを送信します。
`public_comment_reply_exact_text_variants`	string[]	公開返信の追加文言。
`monitor_instagram_followers`	boolean	新しいフォロワーをトリガーとして扱い、最初のDMを送信します（Instagram個人アカウント）。
`follower_outreach_instructions`	string	新規フォロワーへの最初のDMのガイダンス。
`respond_to_instagram_story_replies`	boolean	AIがInstagramストーリーズへの返信に応答するかどうか。デフォルトは`true`です。`false`を設定すると、AIによる返信を行わずに、ストーリーズへの返信を（ストーリーズを添付した状態で）チャットに直接送信します。ライブ設定のため、ドラフトの一部ではなく、公開する必要はありません。

フィールドのクリア

これらのフィールドは、null を送信する際に null に設定するのではなく削除されるため、ボットはデフォルト値（instagram_post_ids、facebook_post_ids、instagram_comment_delay_minutes、facebook_comment_delay_minutes、public_comment_reply_instructions、follower_outreach_instructions、first_response_exact_text、first_response_exact_text_variants、public_comment_reply_exact_text、public_comment_reply_exact_text_variants）にフォールバックします。

不明なキーが1つでもあると、リクエスト全体が拒否されます。 PUT /campaigns/{campaignId} は、許可リストに基づいてリクエストボディ全体を検証します。認識されないキーが含まれている場合、リクエスト全体に対して 400 が返されます。暗黙的に無視されることはなく、そのボディ内の他のフィールドも書き込まれません。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

コメントに残す公開返信には、プランの「コメント返信」機能が必要です。この機能がない場合、DMは送信されますが、公開返信はスキップされます。

AIでキャンペーンを最適化する

POST /campaigns/{campaignId}/optimize

ダッシュボードの「最適化」および低評価フィードバックフローと同じAIリライトを実行します。フィードバックを受け取り、ボットの指示を書き換え、その結果をレビュー用の新しいドラフトリビジョンとしてステージングします。

フィールド	必須	説明
`user_feedback`	この2つのうちいずれか1つが必須	改善点を説明する自由形式のフィードバック。
`thumbs_down_feedback`	この2つのうちいずれか1つが必須	ボットの特定の回答に対する低評価から取得されたフィードバック。
`thumbs_down_message`	いいえ	低評価フィードバックが参照するボットメッセージ。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

レスポンス (202 — リライトはバックグラウンドで実行されます)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

GET /campaigns/{campaignId}をポーリングしてtest_bot.statusを監視します。すぐに"Optimizing"に切り替わり、リライトがtest_botに反映されると"Draft"に戻ります。その後は通常のダッシュボードドラフトと同様に動作します。レビューを行い、ダッシュボードで公開して有効化してください。409は、このキャンペーンに対してすでに最適化が実行中であることを意味します。

最適化には、アカウント上の他のAI操作と同様にクレジットが消費されます。

連絡先をキャンペーンに割り当てる

POST /campaigns/{campaignId}/contacts/{contactId}/assign

既存の連絡先をキャンペーンに追加します。また、必要に応じてキャンペーンの開始メッセージをすぐに送信することもできます。これは、キャンペーンで承認されたWhatsAppテンプレートを1人の連絡先に送信する方法です。キャンペーンで承認されたテンプレートはそのキャンペーンに属しているため、Templates APIライブラリには表示されず、/whatsapp-templates/sendを通じて送信することはできません。

フィールド	必須	説明
`sendOpeningMessage`	いいえ	`true`は、連絡先が割り当てられるとすぐにキャンペーンの開始メッセージ（WhatsAppキャンペーンで承認されたWhatsAppテンプレート）を送信します。デフォルトは`false`です。
`triggerAIResponse`	いいえ	`true`は、代わりにAIが独自の最初のメッセージを作成できるようにします。デフォルトは`false`です。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

レスポンス

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

クレジット: WhatsAppキャンペーンで開始メッセージを送信すると、テンプレート送信と同様に課金され、受信者の国とテンプレートのカテゴリに基づいて価格が決定されます。他のチャネルでは、開始メッセージは通常の送信メッセージとして扱われます。

キャンペーンを受信チャネルにルーティングする

これらのエンドポイントは、チャネル上の新規かつ未知の連絡先にどのキャンペーンが応答するかを管理します。新しい統合にはエントリーポイントの使用を推奨します（キャンペーンタイプの注記を参照）。これらは、古い方法でルーティングされるキャンペーンを操作する場合や、2つの受信キャンペーン間でのチャネル所有権の競合を解決する場合に引き続き役立ちます。

キャンペーンを受信チャネルに割り当てる

POST /campaigns/{campaignId}/incoming-routing

フィールド	必須	説明
`channels`	はい	このキャンペーンが新規かつ未知の連絡先に対して応答すべきチャネルの配列。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

レスポンス

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channelsには実際にこのキャンペーンにルーティングされたチャネルのみがリストされ、failedにはルーティングされなかったチャネルがリストされます。要求されたすべてのチャネルで失敗した場合、リクエスト自体が失敗します。

キャンペーンの受信ルーティングをクリアする

DELETE /campaigns/{campaignId}/incoming-routing

フィールド	必須	説明
`channelToUnassign`	いいえ	この1つのチャネルのみのルーティングをクリアします。省略した場合は、このキャンペーンが現在応答しているすべてのチャネルをクリアします。

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

レスポンス

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

休止中のキャンペーンを再アクティブ化する

POST /campaigns/{campaignId}/reactivate

キャンペーンを Ended、Completed、Paused、または Draft から復帰させ、そのチャネルを再取得します。Incoming from Unknown Contacts または Combined キャンペーンでのみ機能します。すでに Live 状態のキャンペーンは成功とみなされ、何も行われません。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

別のキャンペーンのエージェントによってすでに取得されているチャネルは、呼び出し全体を失敗させるのではなく channelsBlockedByConflict に表示されます。このキャンペーンでチャネルを引き継ぎたい場合は、まず以下の競合する着信キャンペーンを停止するを使用してチャネルを解放してください。再アクティブ化をサポートしていないキャンペーンタイプや、上記の休止状態以外のステータスに対しては 400 が返されます。

競合する着信キャンペーンを停止する

POST /campaigns/{campaignId}/stop-incoming

このキャンペーンのチャネルを、現在それらを保持している「他の」キャンペーンから解放し、このキャンペーンが次にそれらを取得できるようにします。これは、誰かがすでに応答しているチャネルに対して着信キャンペーンを開始したときに、ダッシュボードが自動的に行う処理の REST バージョンです。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

このキャンペーンが広告するすべてのチャネルをすでに所有している場合、released_channels は空で返されます。引き継ぐべきものはありません。

費用見積もり

キャンペーンを開始する前に、その費用を見積もります。

WhatsApp テンプレートの費用見積もり

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode は管理対象の WhatsApp レーンでは "credits" です。Meta がお客様自身の WhatsApp Business アカウントに直接請求するレーンでは、costPerContact、subtotal、および totalTemplateCost は null として返されます。報告すべきクレジット数値がないため、無料と解釈される 0 になることはありません。

SMS の費用見積もり

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

SMS は常に独自の Twilio アカウントを通じて送信されるため（SMS プロバイダーを参照）、常に Twilio から直接請求されます。estimatedCostUsd はその Twilio 請求額の見積もりであり、クレジット料金ではありません。

制限チェック

送信失敗で気づくのではなく、配信を開始する前に制限を確認します。

キャンペーン単位のチェック

GET /campaigns/{campaignId}/limits/ai-credit-messaging — このキャンペーンを開始またはスケジュールすることで、アカウントのAIクレジットによるメッセージ送信制限を超えるかどうか。

GET /campaigns/{campaignId}/limits/messaging — アカウントの1日あたりのメッセージ送信制限を超えるかどうか。

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

レスポンス (制限を超えていない場合)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

制限を超える場合は代わりに 400 が返され、その理由が error に示されます。

アカウント単位のチェック

GET /campaigns/limits/campaigns — サブスクリプションの月間キャンペーン作成制限に達しているかどうか。

GET /campaigns/limits/contacts — サブスクリプションの連絡先制限に達しているかどうか。

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

キャンペーン統計の合計

GET /campaigns/stats/totals

アカウント内のすべてのキャンペーンおよびすべてのAIエージェントについて、直近の期間における送信数と返信数の合計を取得します。これはキャンペーン一覧ページで各行の横に表示される数値と同じもので、キャンペーンごとにリクエストを送るのではなく、1回の呼び出しで取得できます。

クエリパラメータ	説明
`days`	直近の期間（日数）、1〜365。デフォルトは90。

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent はそれ自体が集計結果であり、byCampaign の合計ではありません。AIエージェント専用アカウントのトラフィックにはキャンペーンが紐付かない場合があるため、その場合はここに含まれなくなってしまいます。

プレイグラウンドでキャンペーンをテストする

プレイグラウンドでは、実際のチャネルや連絡先に触れることなく、キャンペーンのボットと会話を行うことができます。これはダッシュボードの試用パネルと同じサンドボックスであり、API経由で完全に利用可能です。

フローは次の通りです：非表示のテスト用連絡先を作成し、メッセージを送信し、ボットの返信をキャンペーンにポーリングします。返信は非同期で生成されるため、レスポンスボディではなく、キャンペーンの test_messages に到着します。

Playgroundの利用にはAPIコストクレジットが消費されます。 APIキーを使用して開始されたテスト会話は、実際の返信と同様に通常のAIメッセージ料金が課金され、利用履歴に通常の項目として表示されます。ダッシュボードからのテストは無料のままです。この違いは意図的なものです。テスト実行もライブ実行と同じAI処理を行うため、API Playgroundを無制限に利用できるようにすると、他人の費用で無制限にAIを実行できてしまうことになるからです。

ステップ 1 - テスト用連絡先を作成する

POST /campaigns/{campaignId}/try-out/contact

非表示のテスト用連絡先を作成し、キャンペーンにリンクします。すべての本文フィールドは任意です。省略した項目は、組み込みのサンプルID（John Doe）が使用されます。

フィールド	必須	説明
`first_name`	いいえ	テスト用連絡先の名。
`last_name`	いいえ	テスト用連絡先の姓。
`email`	いいえ	テスト用連絡先のメールアドレス。
`phone`	いいえ	テスト用連絡先の電話番号。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

レスポンス

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

ステップ 2 - 受信メッセージを記録する

POST /campaigns/{campaignId}/try-out/messages

テストスレッドにメッセージを追加します。ボットが読み取る会話履歴に表示されるよう、まずは訪問者のメッセージをここに送信してください。

フィールド	必須	説明
`messages`	はい	メッセージオブジェクトの配列（1リクエストにつき最大200件）。
`messages[].body`	はい	メッセージのテキスト。
`messages[].direction`	はい	訪問者の場合は `"inbound"`、ボットの場合は `"outbound"`。
`messages[].timestamp`	いいえ	ISO-8601形式の文字列またはエポックミリ秒。
`messages[].role`	いいえ	オプションのロールラベル。
`messages[].name`	No	オプションの表示名。
`ignoreCounter`	いいえ	整数。同じ書き込みでキャンペーンの無視カウンターをリセットします。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

ステップ 3 - ボットに返信させる

POST /campaigns/{campaignId}/try-out/test-message

メッセージをAIパイプラインに送信します。この呼び出しによって、実際にボットの応答が生成されます。

フィールド	必須	説明
`message`	はい	訪問者の最新のメッセージテキスト。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

レスポンス

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

"Published" はメッセージがAIパイプラインに送信されたことを意味します。"Ignored" は、より新しいテストメッセージがこのメッセージに取って代わったことを意味します。プレイグラウンドでは、実際の会話で相手が入力し終えるのを待つのと同様に、最後のメッセージから約4秒後に、連続したメッセージを1つの返信にまとめます。この折りたたみウィンドウがあるため、この呼び出しが完了するまで数秒かかります。

ステップ 4 - 返信を読み取る

GET /campaigns/{campaignId}

ボットの返信は、キャンペーンの test_messages 配列に追加されます。新しい outbound エントリが表示されるまでキャンペーンをポーリングしてください。

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

プレイグラウンドをリセットする

POST /campaigns/{campaignId}/try-out/reset

サンドボックス全体をクリアします。テスト用連絡先を削除し、test_messages をワイプし、ボットの応答ロックを解除します。テスト実行の合間に使用してください。

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

その他のプレイグラウンドエンドポイント

エンドポイント	説明
`DELETE /campaigns/{campaignId}/try-out/contact`	現在のテスト用連絡先のみを削除してリンクを解除します。`test_messages` はそのまま残ります。連絡先がリンクされていない場合でも成功します。
`POST /campaigns/{campaignId}/try-out/transfer`	既存の会話をシードとして使用し、1回のリクエストで新しいプレイグラウンドを開始します。テスト用連絡先を置き換え、`test_messages` を上書きします。ボディには `first_name`、`last_name`、`messages`（空でも可）、および `ignoreCounter` を指定します。削除、作成、追加を個別に行うとレート制限の消費量が3倍になるため、こちらを優先してください。
`POST /campaigns/{campaignId}/try-out/messages/replace`	`test_messages` を追加ではなく全体的に上書きします。スレッドの切り詰めや巻き戻しに使用してください。
`POST /campaigns/{campaignId}/try-out/contact/reset-ignore-counter`	テスト用連絡先の無視カウンターのみをリセットします。送信後のやり直しや繰り返しフローに使用します。