インテグレーションをエンドツーエンドで構築する

このガイドでは、ダッシュボードを一度も開くことなく、独自のコードから Your AI Connector を実行するために必要なすべてを順を追って説明します。最後まで進めると、以下の機能を備えた最小限のインテグレーションが構築できます。

APIキーで認証する
AIエージェントを作成し、アシスタントの動作を設定する
メッセージングチャネル（ここでは例としてWhatsApp Webを使用）を接続し、エージェントに紐付ける
連絡先をインポートする
メッセージの送受信を行う
分析データを読み取る
リアルタイムイベントのWebhookを購読する

各ステップには詳細なリソースガイドへのリンクが記載されているため、必要に応じて詳細を確認できます。このページは地図であり、リソースガイドが実際の領域となります。

開始する前に。 APIアクセスは有料機能です。ご利用のプランに含まれていない場合、すべてのリクエストは 403 を返します。有効になっているか確認するには APIアクセスを、キーを渡す方法については認証を参照してください。

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

https://api.youraiconnector.com/v1

ステップ 1 — APIキーを取得して最初のリクエストを行う

APIキーは、アプリ内の 設定 → 統合 → APIキー にあります。これは「統合」セクション内の独立した項目であり、Webhookとは別物です。プランでAPIアクセスが有効になっている場合にのみ表示されます。キーを生成してコピーし、安全な場所（サーバー側のシークレットストアや環境変数など。ブラウザコード内には絶対に保存しないでください）に保管してください。詳細な手順は APIアクセスを参照してください。

キーを取得したら、ヘルスチェックエンドポイントを呼び出して動作を確認します。キーを送信する方法はいくつかありますが、最も簡単なのは ?apiKey= クエリパラメータを使用する方法です。ただし、実際のコードでは、キーがサーバーログやブラウザの履歴に残らないよう、X-API-Key ヘッダーを使用することを推奨します。

cURL

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

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

すべての成功したレスポンスは同じエンベロープ（success: true フィールドと結果データ）でラップされます。エラーが発生した場合は、success: false とともに error メッセージおよび error_code が返されます。完全なリストや、?limit および ?cursor を使用したリストエンドポイントのページネーションについてはエラーとページネーションを参照してください。

レート制限。 認証済みリクエストは1分間に300回まで（アカウントごとに最大1,200回/分まで）に制限されています。制限を超えると 429 が返されます。リクエストを控え、時間を置いて再試行してください。

ステップ 2 — AIエージェントの作成

AIエージェントは、アシスタントの動作（指示、目標、稼働時間、連絡先との対話方法など）を保持する単位です。会話に応答するのはこのエージェントであるため、最初に作成するのが自然な流れです。

POST /agents を使用して作成します。name は最初に送信すべき唯一のフィールドです。その他の設定は、以下のボット設定呼び出しで行うことができます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

作成に成功すると、新しいIDを含む 201 が返されます。

{
  "success": true,
  "agent_id": "abc123agent"
}

agent_id を保存してください。チャネルをルーティングする際に参照することになります。

アシスタントの設定

PUT /agents/{agentId}/bot-config はアシスタントの動作を設定します。送信したフィールドは既存の設定とマージされるため、省略した項目はそのまま維持されます。

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

PUT /agents/{agentId}/active-hours で稼働時間を設定すると、アシスタントは営業時間内のみ応答するようになります。営業時間外は自動応答しません。

ナレッジベース。 アシスタントに独自のコンテンツから回答させるには、FAQを添付してください。FAQガイドを参照してください。

レガシー：クラシックキャンペーン。 まだ キャンペーン ページがあるアカウントでは、代わりにキャンペーン上で同様のアシスタント動作を作成します（POST /campaigns に type と bot オブジェクトを指定し、その後 PUT /campaigns/{campaignId}/bot-config を実行）。キャンペーンの全フィールドリストとライフサイクル制御については、キャンペーンガイドを参照してください。新規に構築する場合は、エージェントを作成してください。

ステップ 3 — チャネルを接続する

エージェントには、メッセージを送受信する手段が必要です。APIからは、WhatsApp Business、WhatsApp Web、InstagramとMessenger（共通のMetaフロー）、Instagram個人アカウント、Telegram、LINE、Viberの7つの接続フローを制御できます。SMS、メール、チャットウィジェット、カスタムチャネルなどのその他のチャネルは、REST経由ではなくダッシュボードで設定します。一度接続すれば、メッセージング、連絡先、ルーティングのエンドポイントはすべて同じように機能します。GET /channels は、特定のアカウントで実際に何が接続されているかを確認するための最新のソースです。

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

各チャネルの接続/切断フローの全セットはチャネルガイドに記載されています。以下では、最も興味深いパターンである WhatsApp Web のエンドツーエンドの手順を説明します。これは、ラッパー側でレンダリングとポーリングを行う必要がある QR コードペアリングフローです。

実践例: QR コードによる WhatsApp Web のペアリング

WhatsApp Web のペアリングは、「開始」、「QR コードの取得」、「接続されるまでポーリング」という 3 つのステップで行われます。

1. ペアリングセッションを開始する。 接続したい番号を E.164 形式で渡します。

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. QR コードを取得してユーザーに表示する。 10～15 秒ごとにポーリングを行います。レスポンスには生の qr_code ペイロード（QR 画像としてレンダリングしてください）と、そのまま表示可能な qr_data_url が含まれています。

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

ラッパーの UI で、qr_data_url をそのまま <img src="..."> に配置し、ユーザーにスマートフォンの WhatsApp → リンクされたデバイス からスキャンするように依頼してください。QR コードの有効期限が切れた場合（410 レスポンス）、ステップ 1 からやり直して新しいコードを取得します。

3. 接続されるまでステータスをポーリングする。 ユーザーがスキャンした後、ステータスが connected になるまでステータスエンドポイントへのポーリングを続けます（サービスが open を返す場合もあります）。disconnected および not_initialized は致命的なエラーとして扱ってください。

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

注意。 接続された各 WhatsApp Web 番号には、切断するまで定期的な月額メンテナンス料金が発生します (DELETE /channels/whatsapp-web/connections/{phoneNumber})。

チャネルをエージェントにルーティングする

チャネルを接続すると機能するようになりますが、ルーティングを設定することで、そのチャネルで発生した新規の受信会話に「どのAIエージェント」が応答すべきかをプラットフォームに伝えます。チャネルのデフォルトエントリーポイントを設定し、ステップ2で作成したエージェントを指定します。

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

この呼び出しをチャネルごとに繰り返してください（チャネルにつき1つのデフォルト設定）。チャネルでエージェントが応答しないようにするには DELETE /entry-points/channel-defaults?channel=whatsapp_web を呼び出し、アカウントでエントリーポイントの階層が有効かどうかを確認するには GET /entry-points/routing-status を呼び出します。古い POST /channels/campaign マップはロールバック用にのみ保持されており、インバウンドルーティングには使用されません。その他のチャネルタイプやWhatsApp Business OAuthフローについては、チャネルガイドを参照してください。

ステップ4 — 連絡先をインポートする

チャネルが稼働したら、連絡を取りたい相手を読み込みます。インポートエンドポイントは、1回の呼び出しにつき最大500件のレコードを受け付けます。各レコードには国際形式の phone_number が必要で、それ以外はすべてオプションです。無効な番号、サポートされていないチャネル、または既に存在する番号を持つレコードはスキップされます。各スキップはインデックスと理由とともに報告されるため、失敗した分だけを再試行できます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

レスポンスには、何が起こったかが正確に示されます：

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

1件ずつの作成、リスト/検索、リスト、タグ、カスタムフィールドについては、連絡先ガイドを参照してください。

ステップ5 — メッセージの送信と読み取り

メッセージを送信する

最もシンプルな送信方法は チャネル非依存 です。連絡先のIDとメッセージ本文を指定すれば、プラットフォームがその連絡先が利用しているチャネルでメッセージを配信します。contact_id でターゲットを指定するか、channel と一致するIDフィールド（WhatsApp/WhatsApp Web/SMSの場合は phone_number、Instagramの場合は instagram_id など）を組み合わせて指定できます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

配信は 非同期 です。201 は、メッセージが 受け付けられ、キューに入れられた ことを意味し、まだ配信されたわけではありません。（おやすみモードやプライベートモードがオンになっている連絡先は、422 で拒否されます。）

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

会話を読む

メッセージを読み返すには、連絡先ごとに、新しい順にカーソルページネーションを使用してリスト化します。あるレスポンスの next_cursor を次のレスポンスの cursor として渡すことで、履歴を遡ることができます。

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

コンテンツタイプ (?filter=text|media|tool_use) や方向 (?direction=inbound|outbound) でフィルタリングすることも可能です。メッセージガイドでは、メディアの添付、メッセージの既読マーク、セッションごとのメッセージ表示について説明しています。

返信をポーリングしないでください。 タイマーでメッセージをリスト化する方法も機能しますが、リクエストを浪費し、遅延が発生します。着信メッセージには、代わりにWebhookを使用してください。それがステップ7です。

ステップ 6 — 分析データの読み取り

メッセージの送受信が開始されると、分析サマリーで指定した期間の集計数（送信数、到達数、開封数、返信数、予約数、作成された連絡先数、消費/チャージされたクレジット数）を確認できます。期間の合計値と、日ごとの詳細データ（ゼロ埋め済み）の両方が取得できるため、ダッシュボードのグラフ作成に最適です。オプションで campaign_id を使用して特定のキャンペーンに絞り込むことも可能です（以下の例ではプレースホルダーのキャンペーンID abc123campaign を使用しています）。このパラメータを省略すると、アカウント全体の合計が表示されます。

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

期間はデフォルトで過去30日間となっており、最大366日まで指定できます。クレジット単位の利用記録やAIコストの内訳については、分析ガイドを参照してください。

ステップ 7 — Webhookを購読してリアルタイムイベントを受信する

簡易的なスクリプトであればポーリングでも問題ありませんが、本格的な統合を行う場合はプッシュ型にする必要があります。Webhookを使用すると、新しい連絡先の追加、返信、予約の確定、チャットの終了など、何らかのイベントが発生した瞬間にプラットフォームからお客様のサーバーを呼び出すことができます。

まず、購読可能な正確なイベント名を確認します。

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

次に、お客様のサーバー上のHTTPS URLを指定してサブスクリプションを作成します。上記の呼び出しで得られた正確なイベント文字列を使用してください。

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

URLはHTTPSを使用し、パブリックにアクセス可能である必要があります。これ以降、購読したイベントが発生するたびに、お客様のサーバーにPOSTリクエストが送信されます。テスト配信の送信、サブスクリプションの健全性チェック、および繰り返し失敗して自動無効化されたサブスクリプションの再有効化が可能です。ペイロードの形式や検証方法については、Webhookガイドおよび統合レベルのWebhookページを参照してください。

全体のまとめ

全体の流れは以下の通りです。

ステップ	目標	主要な呼び出し
1	認証	`GET /health`
2	アシスタントの作成と調整	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	チャネルの接続とルーティング	`POST /channels/whatsapp-web/connections` → QRコードの読み取りとステータス確認 → `PUT /entry-points/channel-defaults`
4	連絡先の読み込み	`POST /contacts/import`
5	送信と読み取り	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	測定	`GET /analytics/summary`
7	リアルタイムでの対応	`POST /webhooks`

最小限のラッパーは、これら7つの呼び出しをお客様のUIに組み込むだけで実現できます。そこから必要に応じて、リソースごとのガイドを参照して機能を追加してください。

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

インテグレーションをエンドツーエンドで構築する #

ステップ 1 — APIキーを取得して最初のリクエストを行う #

ステップ 2 — AIエージェントの作成 #

アシスタントの設定 #

ステップ 3 — チャネルを接続する #

実践例: QR コードによる WhatsApp Web のペアリング #

チャネルをエージェントにルーティングする #

ステップ4 — 連絡先をインポートする #

ステップ5 — メッセージの送信と読み取り #

メッセージを送信する #

会話を読む #

ステップ 6 — 分析データの読み取り #

ステップ 7 — Webhookを購読してリアルタイムイベントを受信する #

全体のまとめ #

インテグレーションをエンドツーエンドで構築する

ステップ 1 — APIキーを取得して最初のリクエストを行う

ステップ 2 — AIエージェントの作成

アシスタントの設定

ステップ 3 — チャネルを接続する

実践例: QR コードによる WhatsApp Web のペアリング

チャネルをエージェントにルーティングする

ステップ4 — 連絡先をインポートする

ステップ5 — メッセージの送信と読み取り

メッセージを送信する

会話を読む

ステップ 6 — 分析データの読み取り

ステップ 7 — Webhookを購読してリアルタイムイベントを受信する

全体のまとめ