# インテグレーションをエンドツーエンドで構築する このガイドでは、ダッシュボードを一度も開くことなく、独自のコードから Your AI Connector を実行するために必要なすべてを順を追って説明します。最後まで進めると、以下の機能を備えた最小限のインテグレーションが構築できます。 1. APIキーで認証する 2. AIエージェントを作成し、アシスタントの動作を設定する 3. メッセージングチャネル（ここでは例としてWhatsApp Webを使用）を接続し、エージェントに紐付ける 4. 連絡先をインポートする 5. メッセージの送受信を行う 6. 分析データを読み取る 7. リアルタイムイベントのWebhookを購読する 各ステップには詳細なリソースガイドへのリンクが記載されているため、必要に応じて詳細を確認できます。このページは地図であり、リソースガイドが実際の領域となります。 > **開始する前に。** APIアクセスは有料機能です。ご利用のプランに含まれていない場合、すべてのリクエストは `403` を返します。有効になっているか確認するには [APIアクセス](../integrations/api-access.md) を、キーを渡す方法については [認証](authentication.md) を参照してください。 以下のすべてのパスは、ベースURLからの相対パスです。 ``` https://api.youraiconnector.com/v1 ``` --- ## ステップ 1 — APIキーを取得して最初のリクエストを行う APIキーは、アプリ内の **設定 → 統合 → APIキー** にあります。これは「統合」セクション内の独立した項目であり、Webhookとは別物です。プランでAPIアクセスが有効になっている場合にのみ表示されます。キーを生成してコピーし、安全な場所（サーバー側のシークレットストアや環境変数など。ブラウザコード内には絶対に保存しないでください）に保管してください。詳細な手順は [APIアクセス](../integrations/api-access.md) を参照してください。 キーを取得したら、ヘルスチェックエンドポイントを呼び出して動作を確認します。キーを送信する方法はいくつかありますが、最も簡単なのは `?apiKey=` クエリパラメータを使用する方法です。ただし、実際のコードでは、キーがサーバーログやブラウザの履歴に残らないよう、`X-API-Key` ヘッダーを使用することを推奨します。 **cURL** ```bash curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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` を使用したリストエンドポイントのページネーションについては [エラーとページネーション](errors-and-pagination.md) を参照してください。 > **レート制限。** 認証済みリクエストは**1分間に300回**まで（アカウントごとに最大1,200回/分まで）に制限されています。制限を超えると `429` が返されます。リクエストを控え、時間を置いて再試行してください。 --- ## ステップ 2 — AIエージェントの作成 **AIエージェント**は、アシスタントの動作（指示、目標、稼働時間、連絡先との対話方法など）を保持する単位です。会話に応答するのはこのエージェントであるため、最初に作成するのが自然な流れです。 `POST /agents` を使用して作成します。`name` は最初に送信すべき唯一のフィールドです。その他の設定は、以下のボット設定呼び出しで行うことができます。 **cURL** ```bash 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** ```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** ```python res = requests.post( f"{BASE}/agents", headers=HEADERS, json={"name": "Inbound WhatsApp Leads", "language": "en"}, ) agent_id = res.json()["agent_id"] ``` 作成に成功すると、新しいIDを含む `201` が返されます。 ```json { "success": true, "agent_id": "abc123agent" } ``` **`agent_id` を保存してください**。チャネルをルーティングする際に参照することになります。 ### アシスタントの設定 `PUT /agents/{agentId}/bot-config` はアシスタントの動作を設定します。送信したフィールドは既存の設定と*マージ*されるため、省略した項目はそのまま維持されます。 ```bash 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ガイド](faqs.md) を参照してください。 > **レガシー：クラシックキャンペーン。** まだ **キャンペーン** ページがあるアカウントでは、代わりにキャンペーン上で同様のアシスタント動作を作成します（`POST /campaigns` に `type` と `bot` オブジェクトを指定し、その後 `PUT /campaigns/{campaignId}/bot-config` を実行）。キャンペーンの全フィールドリストとライフサイクル制御については、[キャンペーンガイド](campaigns.md) を参照してください。新規に構築する場合は、エージェントを作成してください。 --- ## ステップ 3 — チャネルを接続する エージェントには、メッセージを送受信する手段が必要です。APIからは、WhatsApp Business、WhatsApp Web、InstagramとMessenger（共通のMetaフロー）、Instagram個人アカウント、Telegram、LINE、Viberの7つの接続フローを制御できます。SMS、メール、チャットウィジェット、カスタムチャネルなどのその他のチャネルは、REST経由ではなくダッシュボードで設定します。一度接続すれば、メッセージング、連絡先、ルーティングのエンドポイントはすべて同じように機能します。`GET /channels` は、特定のアカウントで実際に何が接続されているかを確認するための最新のソースです。 ```bash curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY" ``` 各チャネルの接続/切断フローの全セットは [チャネルガイド](channels.md) に記載されています。以下では、最も興味深いパターンである **WhatsApp Web** のエンドツーエンドの手順を説明します。これは、ラッパー側でレンダリングとポーリングを行う必要がある QR コードペアリングフローです。 ### 実践例: QR コードによる WhatsApp Web のペアリング WhatsApp Web のペアリングは、「**開始**」、「**QR コードの取得**」、「**接続されるまでポーリング**」という 3 つのステップで行われます。 **1. ペアリングセッションを開始する。** 接続したい番号を E.164 形式で渡します。 ```bash 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" }' ``` ```javascript await fetch(`${BASE}/channels/whatsapp-web/connections`, { method: "POST", headers, body: JSON.stringify({ phone_number: "+15551230000" }), }); ``` ```python requests.post( f"{BASE}/channels/whatsapp-web/connections", headers=HEADERS, json={"phone_number": "+15551230000"}, ) ``` **2. QR コードを取得してユーザーに表示する。** 10～15 秒ごとにポーリングを行います。レスポンスには生の `qr_code` ペイロード（QR 画像としてレンダリングしてください）と、そのまま表示可能な `qr_data_url` が含まれています。 ```bash curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY" ``` ```json { "success": true, "phone_number": "+15551230000", "status": "qr_pending", "qr_code": "2@abc...", "qr_data_url": "data:image/png;base64,iVBORw0KGgo..." } ``` ラッパーの UI で、`qr_data_url` をそのまま `` に配置し、ユーザーにスマートフォンの **WhatsApp → リンクされたデバイス** からスキャンするように依頼してください。QR コードの有効期限が切れた場合（`410` レスポンス）、ステップ 1 からやり直して新しいコードを取得します。 **3. 接続されるまでステータスをポーリングする。** ユーザーがスキャンした後、ステータスが `connected` になるまでステータスエンドポイントへのポーリングを続けます（サービスが `open` を返す場合もあります）。`disconnected` および `not_initialized` は致命的なエラーとして扱ってください。 ```python 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) ``` ```javascript 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で作成したエージェントを指定します。 ```bash 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フローについては、[チャネルガイド](channels.md) を参照してください。 --- ## ステップ4 — 連絡先をインポートする チャネルが稼働したら、連絡を取りたい相手を読み込みます。インポートエンドポイントは、**1回の呼び出しにつき最大500件のレコード**を受け付けます。各レコードには国際形式の `phone_number` が必要で、それ以外はすべてオプションです。無効な番号、サポートされていないチャネル、または既に存在する番号を持つレコードはスキップされます。各スキップはインデックスと理由とともに報告されるため、失敗した分だけを再試行できます。 **cURL** ```bash 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** ```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** ```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") ``` レスポンスには、何が起こったかが正確に示されます： ```json { "success": true, "imported": 2, "contact_ids": ["contactId1", "contactId2"], "skipped": [] } ``` 1件ずつの作成、リスト/検索、リスト、タグ、カスタムフィールドについては、[連絡先ガイド](contacts.md)を参照してください。 --- ## ステップ5 — メッセージの送信と読み取り ### メッセージを送信する 最もシンプルな送信方法は **チャネル非依存** です。連絡先のIDとメッセージ本文を指定すれば、プラットフォームがその連絡先が利用しているチャネルでメッセージを配信します。`contact_id` でターゲットを指定するか、`channel` と一致するIDフィールド（WhatsApp/WhatsApp Web/SMSの場合は `phone_number`、Instagramの場合は `instagram_id` など）を組み合わせて指定できます。 **cURL** ```bash 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** ```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** ```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` で拒否されます。） ```json { "success": true, "message_id": "aB3dE5fG7hI9jK1lM2nO", "contact_id": "contact123", "channel": "whatsapp_web" } ``` ### 会話を読む メッセージを読み返すには、連絡先ごとに、新しい順にカーソルページネーションを使用してリスト化します。あるレスポンスの `next_cursor` を次のレスポンスの `cursor` として渡すことで、履歴を遡ることができます。 ```bash curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY" ``` ```python 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`) でフィルタリングすることも可能です。[メッセージガイド](messages.md)では、メディアの添付、メッセージの既読マーク、セッションごとのメッセージ表示について説明しています。 > **返信をポーリングしないでください。** タイマーでメッセージをリスト化する方法も機能しますが、リクエストを浪費し、遅延が発生します。着信メッセージには、代わりにWebhookを使用してください。それがステップ7です。 --- ## ステップ 6 — 分析データの読み取り メッセージの送受信が開始されると、分析サマリーで指定した期間の集計数（送信数、到達数、開封数、返信数、予約数、作成された連絡先数、消費/チャージされたクレジット数）を確認できます。期間の合計値と、日ごとの詳細データ（ゼロ埋め済み）の両方が取得できるため、ダッシュボードのグラフ作成に最適です。オプションで `campaign_id` を使用して特定のキャンペーンに絞り込むことも可能です（以下の例ではプレースホルダーのキャンペーンID `abc123campaign` を使用しています）。このパラメータを省略すると、アカウント全体の合計が表示されます。 ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY" ``` ```javascript 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(); ``` ```python 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コストの内訳については、[分析ガイド](analytics.md)を参照してください。 --- ## ステップ 7 — Webhookを購読してリアルタイムイベントを受信する 簡易的なスクリプトであればポーリングでも問題ありませんが、本格的な統合を行う場合は**プッシュ型**にする必要があります。Webhookを使用すると、新しい連絡先の追加、返信、予約の確定、チャットの終了など、何らかのイベントが発生した瞬間にプラットフォームから*お客様の*サーバーを呼び出すことができます。 まず、購読可能な正確なイベント名を確認します。 ```bash curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY" ``` ```json { "success": true, "events": [ "Contact Created", "Human Alerted", "Appointment Booked", "Replies", "New Message", "Chat Concluded", "Task Created", "Daily Summary Created" ] } ``` 次に、お客様のサーバー上のHTTPS URLを指定してサブスクリプションを作成します。上記の呼び出しで得られた正確なイベント文字列を使用してください。 **cURL** ```bash 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** ```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** ```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"] ``` ```json { "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ガイド](webhooks.md)および統合レベルの[Webhook](../integrations/webhooks.md)ページを参照してください。 --- ## 全体のまとめ 全体の流れは以下の通りです。 | ステップ | 目標 | 主要な呼び出し | |---|---|---| | 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に組み込むだけで実現できます。そこから必要に応じて、リソースごとのガイドを参照して機能を追加してください。 - [キャンペーン](campaigns.md) · [連絡先](contacts.md) · [FAQ](faqs.md) · [メッセージ](messages.md) · [予約](appointments.md) - [チャネル](channels.md) · [テンプレート](templates.md) · [分析](analytics.md) · [Webhook](webhooks.md) · [APIキー](api-keys.md) - 初めての方へ: [はじめに](getting-started.md) · [認証](authentication.md) · [エラーとページネーション](errors-and-pagination.md) Stuck on something this guide does not cover? Email [hi@youraiconnector.com](mailto:hi@youraiconnector.com).