チャネル接続API #

このガイドでは、APIを使用してメッセージングチャネルをアカウントに接続する方法を説明します。統合やラッパーを構築する開発者向けに作成されているため、正確なリクエスト、リクエストを行う順序、および返されるレスポンスに焦点を当てています。

ここで扱うほぼすべてのチャネルに適用されるため、最初に理解しておくべきパターンが1つあります。

接続とポーリングのパターン #

ほとんどのチャネルは、単一のAPI呼び出しで接続することはできません。WhatsApp、Instagram、またはMessengerを接続するには、アカウント所有者が自身のプロバイダーアカウントにログインし、アクセスを承認する必要があります。その承認にはヘッドレス（完全自動化）なパスは存在しません。実際のユーザーがブラウザでURLを開くか、スマートフォンでQRコードをスキャンする必要があります。

そのため、フローは常に以下のようになります。

1. POST で接続を開始します。レスポンスとして、開くべきURLまたは表示するQRコードが返されます。
2. それをエンドユーザーに渡します。ブラウザでURLを開いてもらうか、画面にQRコードを表示してスキャンしてもらいます。
3. ステータスが接続済みになるまで、短い間隔（数秒ごと）で GET を使用してステータスエンドポイントをポーリングします。

統合の役割は、そのループを駆動することです。URLやQRコードを表示し、完了するまでポーリングします。ポーリングに合わせてUIを設計してください。「ブラウザでの操作が完了するのを待機しています」というメッセージとともにスピナーを表示するのが効果的です。

Instagram + Messenger (Meta) #

InstagramとMessengerはどちらもFacebookページ上で動作するため、1つのフローでまとめて接続されます。アカウント所有者がFacebookを通じて承認を行い、管理しているページのリストを取得し、接続するページを選択します。

ステップ 1 - Instagram + Messenger 接続を開始する #

POST /channels/meta/connect

これにより、同意URLが返されます。このリクエストでは認証情報は送信されません。接続はすべてブラウザ内で承認されます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

レスポンス

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

エンドユーザーのブラウザで oauth_url を開き、Facebookにログインしてアクセスを承認してもらいます。接続試行は expires_at （約30分）で期限切れになります。期限が切れた場合は最初からやり直してください。state_token は短期間有効なシークレットとして扱い、ログには記録しないでください。

Instagram + Messenger の最も簡単なオプション: connect_url を引き渡す #

レスポンスには、すぐに使える connect_url も含まれています。これは、アカウント所有者のための全フローを実行するホスト型ページです。所有者がこのページを開いてFacebookにログインすると、ページが複数ある場合はリストが表示され、接続するページを選択できます。その後、自動的に成功が報告されます。自分で oauth_url を開いたり、ページ選択機能を構築したり、ポーリングを行ったりする代わりに、このリンクをアカウント所有者に渡してください。このリンクは約30分間有効です (connect_url_expires_at)。期限が切れた場合は、新しい接続を開始してください。以下の手動手順は、フローを制御し、独自のページ選択機能をレンダリングしたい統合向けです。

ステップ 2 - ページが読み込まれるまでステータスをポーリングする #

GET /channels/meta/status

ユーザーがFacebookログインを完了した後、数秒おきにこのエンドポイントをポーリングします。statusフィールドは以下のステップで遷移します：

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

レスポンス（ページ読み込み完了時）

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

ステップ 3 - ページをリスト表示する（オプション） #

ページリストを単独で取得したい場合（ピッカーを表示する場合など）は、以下を使用します：

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

これはステータスエンドポイントと同じpages配列を返します。（statusエンドポイントにはすでにページが含まれているため、この呼び出しは便宜上のものです。）

ステップ 4 - 接続するページを選択する #

POST /channels/meta/select-page

ユーザーが選択したページのpage_idを送信します。そのページにリンクされているInstagramアカウントが自動的に接続されます。使用するInstagramアカウントを上書きしたい場合のみ、instagramオブジェクトが必要です。

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

レスポンス

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

チャネルが接続されました。後続のGET /channels/meta/statusでstatus: "connected"が報告されます。

接続されたページの投稿を一覧表示する #

GET /channels/meta/posts?platform=instagram

接続したページの最近の投稿（InstagramメディアまたはFacebook投稿）を返します。これは、特定の投稿へのコメントに反応するエントリーポイントを設定する際に、ピッカーをレンダリングするためのものです。

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType は Instagram 独自のラベル（REELS、FEED、STORY、または形式 - IMAGE、VIDEO、CAROUSEL_ALBUM）です。Facebook の場合は常に POST となります。nextCursor は最後のページにある null です。

リストできるものがない場合でも、呼び出しは connected: false と空の posts 配列を含む 200 を返し、さらに理由を示す reason を返します：

Instagram + Messenger の接続を解除する #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "disconnected": true }

これにより、InstagramとMessengerの両方のインバウンドルーティングが停止します。これはべき等であり、何も接続されていない状態で呼び出しても成功します。

WhatsApp Business #

これは公式のWhatsApp Business番号を接続するものです。接続を呼び出す前に、その番号がアカウント上に既に存在している必要があります。Metaと同様に、アカウント所有者がブラウザで承認を行い、その後、番号が ONLINE と報告されるまでポーリングを行います。

ステップ 1 - WhatsApp Business 接続を開始する #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

レスポンス

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

アカウント所有者のブラウザで oauth_url を開き、承認を行います。承認されると、バックグラウンドで登録が完了します。

ステップ 2 - ONLINEになるまでステータスをポーリングする #

GET /channels/whatsapp/connect/{phoneNumber}/status

status が ONLINE になるまで、これをポーリングします。

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

レスポンス

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

status フィールドには以下の値が入ります:

live: true はステータスがプロバイダーに対してリアルタイムで確認されたことを意味し、false は最後にキャッシュされた状態から取得されたことを意味します。

WhatsApp Business 番号の接続を解除する #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

番号自体はアカウントに残るため、後で再接続することができます。

WhatsApp Web #

WhatsApp Webは、WhatsAppアプリでデバイスをリンクするのと同様に、QRコードをスキャンすることで通常のWhatsApp番号をリンクします。フローは、セッションを開始し、QRコードを取得して表示し、ステータスが connected になるまでポーリングするという流れです。

ステップ 1 - WhatsApp Web ペアリングセッションを開始する #

POST /channels/whatsapp-web/connections

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

WhatsApp Web の最も簡単なオプション: connect_url を引き渡す #

レスポンスには、すぐに使える connect_url が含まれています。これは、QRコードを表示し、回転に合わせて自動的に更新し、番号がリンクされた瞬間に成功メッセージに切り替わるホスト型ページです。このリンクをアカウント所有者に渡す（ブラウザで開く、送信する、またはQRコードやボタンとして表示する）だけで、WhatsAppでスキャンしてもらえます。QRコードを取得したり、自分でポーリングしたりする必要はありません。このリンクは約30分間有効です（connect_url_expires_at）。完了前に期限が切れた場合は、新しい接続を開始して新しいリンクを取得してください。

これは、ユーザーがリンクを開ける場合に推奨される方法です。以下の手動手順（自分でQRコードを取得し、ステータスをポーリングする）は、独自のインターフェース内にQRコードを表示したい統合のためのものです。

レスポンスには、使用すべき正確な poll_qr_path と poll_status_path も含まれているため、自分で構築する必要はありません。

ステップ 2 - QRコードの取得と表示 #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

レスポンス

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

ユーザーが携帯電話でスキャンできるようにQRコードを表示します（WhatsApp > リンクされたデバイス > デバイスをリンク）：

• qr_data_url はそのまま使用できる画像です。<img src> に直接配置してください。
• qr_code は、自分で画像を生成したい場合の生のペイロードです。

QRコードの有効期限は短いです。セッション開始直後にこの呼び出しを行うと、「QRコードがまだ利用できません」という 404 が返される場合があります。少し待ってから再試行してください。410（「QRコードの有効期限切れ」）が返された場合は、接続を最初からやり直して新しいコードを取得してください。

ステップ 3 - 接続されるまでステータスをポーリング #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

レスポンス

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

WhatsApp Web セッションを切断する #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

これによりデバイスのリンクが解除され、接続が削除されます。常にローカル状態をクリーンアップするため、基盤となるセッションが既に存在しない場合でも冪等（べきとう）です。

Telegram #

利用可能状況: Telegram は他のチャネルと同様に接続でき、すべてのアカウントで利用可能です。有効にする必要はありません。Telegram がアカウントのプランに含まれていない場合、以下の Telegram エンドポイントは 403 を返すことがあり、その場合のエラーは "This channel is not included in your current plan. Upgrade to unlock it." となります。

Telegramは、電話番号とワンタイムログインコード（アカウントに設定されている場合は二段階認証パスワード）を使用して個人アカウントを接続します。フローは、セッションの開始、コードの送信、必要に応じてパスワードの送信、そしてステータスによる確認という手順になります。

ステップ 1 - Telegram 接続セッションを開始する #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

code モードでは、アカウントはTelegramでログインコードを受け取り、status は code_required となります。（qr モードでは、レスポンスにスキャン表示用の login_token と qr_url も含まれ、status は qr_required となります。）

Telegram の最も簡単なオプション: connect_url を引き渡す #

レスポンスには、接続を自動的に完了させるホスト型ページである、すぐに使える connect_url が含まれています。code モードでは、アカウント所有者がログインコードを入力し、アカウントに2段階認証パスワードが設定されている場合はそれも入力します。qr モードでは、ページに自動更新されるQRコードが表示され、Telegramアプリからスキャンできます。いずれの場合も自動的に成功が報告されるため、独自のUIを構築してポーリングを行う代わりに、このリンクをアカウント所有者に提供するだけで済みます。このリンクは約30分間 (connect_url_expires_at) 有効です。期限が切れた場合は、新しい接続を開始して新しいリンクを取得してください。

以下の手動手順（コードを自分で収集して送信し、ステータスをポーリングする、または qr_url をレンダリングしてポーリングする）は、独自のUIをレンダリングしたい統合のためのものです。

ステップ 2 - ログインコードを送信する #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

status が connected であれば完了です。アカウントで二段階認証が有効になっている場合、status は代わりに password_required となります。その場合はステップ3に進んでください。

ステップ 3 - 二段階認証パスワードを送信する（必要な場合のみ） #

POST /channels/telegram/connect/{phoneNumber}/verify-password

これはステップ2で password_required が返された場合にのみ呼び出してください。

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Telegram のステータスを確認する #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status は connected、code_required、password_required、initializing、disconnected、not_initialized、または error になります。

Telegram の接続を解除する #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

冪等性 - 繰り返し呼び出しても成功します。

Instagram（個人アカウント） #

限定公開のベータ機能であり、アカウントごとに有効化されます。これは、ユーザー名とパスワードを使用してログインすることで個人のInstagramアカウントを接続します（公式のビジネスAPIではありません）。アカウントでベータ版が有効になっていない場合、接続呼び出しは権限エラーを返します。

これにはアカウント所有者自身のInstagramログインが必要となるため、最も簡単な方法は、ホスト型の connect_url を渡し、そこで資格情報を入力してもらうことです。統合側でパスワードを扱う必要はありません。

ステップ 1 - Instagram（個人）接続を開始する #

POST /channels/instagram-private/connect

Instagramの username と password を送信します。

レスポンス

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

アカウントで二要素認証が有効になっている場合や、Instagram がチェックポイントを表示した場合、status は two_factor_required または challenge_required として返されます。コードを以下の /connect/{id}/verify-2fa または /connect/{id}/verify-challenge に送信し、connected になるまで /connect/{id}/status をポーリングしてください。{id} は、上記のレスポンスで account_id/username として返される正規化された Instagram ユーザー名です。以下のすべてのステップで使用してください。

ステップ 2 - 二要素認証コードを送信する（要求された場合） #

POST /channels/instagram-private/connect/{id}/verify-2fa

ステップ 1（またはステップ 3）が two_factor_required を返した場合にのみ、これを呼び出してください。

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

レスポンス

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status は connected（完了）、two_factor_required（コードが間違っています。再試行してください）、または challenge_required（Instagramがチェックポイントコードを要求しています。ステップ 3 に進んでください）のいずれかを返します。

ステップ 3 - チェックポイント確認コードを送信する（要求された場合） #

POST /channels/instagram-private/connect/{id}/verify-challenge

前のステップが challenge_required を返した場合にのみ、これを呼び出してください。リクエストとレスポンスの形式は上記のステップ 2 と同じです。

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Instagram（個人）のステータスを確認する #

GET /channels/instagram-private/connect/{id}/status

status が connected になるまで、または最終的なエラーが報告されるまで、これをポーリングしてください。

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status は connected、two_factor_required、challenge_required、initializing、disconnected、not_initialized、または error になります。live: true は、これがキャッシュされた値ではなく、接続ワーカーからライブで読み取られたことを意味します。

Instagram（個人）の最も簡単なオプション: connect_url を引き渡す #

レスポンスには connect_url が含まれています。これは、アカウント所有者がInstagramのユーザー名とパスワード（およびInstagramから要求された場合は2FAまたはチェックポイントコード）を入力するためのホスト型ページで、自動的に成功が報告されます。資格情報は直接Instagramに送信され、保存されることはありません。独自のUIでパスワードを収集する代わりに、このリンクをアカウント所有者に渡してください。このリンクは約30分間有効です (connect_url_expires_at)。

Instagram（個人）の接続を解除する #

DELETE /channels/instagram-private/{id}

冪等性 - 繰り返し呼び出しても成功します。

フォロワーの同期 #

POST /channels/instagram-private/{id}/sync-followers

接続済みアカウントのフォロワー同期を手動でトリガーします。これはバックグラウンドで自動実行されるジョブと同じもので、オンデマンドの「フォロワーを更新」アクションとして公開されています。アカウントの現在のフォロワーリストを取得して新規フォロワーを記録し、（ライブキャンペーンでフォロワーへのアウトリーチが有効になっている場合）1日の上限に達するまで、新規フォロワーに最初のDMを送信します。

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

これらの5つのフィールドは、このページで snake_case ではなく camelCase が返される唯一の箇所です。これは誤植ではなく、現在のエンドポイントの仕様です。isBaselineSeed: true は、接続後初めての同期であることを意味します。この初回同期では、開始時のフォロワーリストを記録するだけで、アウトリーチDMは送信されません（そのため、その実行時には dmsSent は常に 0 となります）。

アカウントの初回呼び出しには時間がかかる場合があります（フォロワーリスト全体を走査するため）。以降の呼び出しは、新規フォロワーとの差分のみが処理されるため高速です。404 はアカウントが接続されていないことを意味し、412 は接続の初期化がまだ完了していないことを意味します。しばらく待ってから再試行してください。

LINE #

LINEは、ブラウザのリダイレクトやポーリングが不要なため、最も簡単に接続できるチャネルです。顧客がLINE DevelopersコンソールでMessaging APIチャネルを作成し、2つの値をコピーして、それを1回の呼び出しで送信します。その後、コンソールに貼り付けるためのWebhook URLを顧客に提供します。

ステップ 1 - チャネル認証情報での接続 #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

次のステップにおいて重要なフィールドは2つあります。

• webhook_url - 顧客はこれをLINE DevelopersコンソールのLINEチャネルの Webhook URL フィールドに貼り付ける必要があります（「Webhookの利用」を有効にする必要があります）。これを行わない限り、インバウンドメッセージは届きません。これを顧客に目立つように表示してください。
• chat_mode_ok - false の場合、公式アカウントは「チャット」モードになっており、LINE公式アカウントマネージャーで「ボット」モードに切り替えるまでメッセージの送受信が行われません。このフラグに基づいてオンボーディングを制御し、顧客にモードを切り替えるよう伝えてください。

channel_access_token と channel_secret は、どのエンドポイントからも返されません。再度必要な場合は自社側で保存してください。そうでない場合は、LINEコンソールから再度貼り付けてください。

ここで返される bot_user_id は、以下のステータス、検証、および切断の呼び出しで使用する接続識別子です。

ステップ 2 - Webhook設定後の再検証 #

POST /channels/line/{botUserId}/verify-webhook

顧客がWebhook URLの設定を完了し、ボットモードに切り替えた後、これを呼び出して保存されたトークンを再検証し、キャッシュされたチャットモードを更新します。

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

token_valid が false の場合、保存されたアクセストークンは認証されなくなります。コンソールで再発行し、新しいトークンを使用して再度 POST /channels/line を呼び出すよう顧客に依頼してください。

LINEのステータスを確認する #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINEにはライブステータスフィードがないため、ここでは live は常に false となります。値は接続時（または前回の検証時）に取得された状態を反映しています。

LINEの接続を解除する #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

ViberはLINEと同じ方法で接続します。Viber管理パネルからボットの認証トークンを1回の呼び出しで貼り付けます。ただし、1つ知っておくべき違いがあります。接続時に、その場でボットのWebhookを登録するため、後でコンソールで別の手順を行う必要はありません。つまり、接続試行はトークン自体が間違っている場合だけでなく、当社のイングレスがViberの同期Webhookチェックに応答できない場合にも失敗する可能性があります。

ステップ 1 - ボットの認証トークンで接続する #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

レスポンス

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

認証トークンはどのエンドポイントからも返されません。再入力が必要になる場合に備えて、お客様側で保存しておいてください。bot_id は、以下のステータス確認、検証、切断の各呼び出しで使用される接続識別子です。

Viberのステータスを確認する #

GET /channels/viber/{botId}/status

保存されている接続状態を報告します。?live=true を追加すると、Viberに対してボットを再チェックし、キャッシュされたWebhook登録を更新することもできます。ボットが反応しない場合に、実際に壊れていると判断する前に役立ちます。

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false は、ボットのWebhookが当社を指していないことを意味し、受信メッセージは処理されません。これは通常、別のツールが後から同じボットに接続したことを意味します（ViberのWebhook登録は後勝ちです）。以下の再検証呼び出しで修正してください。お客様にトークンを再入力してもらう必要はありません。live は、応答がViberに対する最新のチェックではなく、最後にキャッシュされた状態である場合に false となります。

Webhookを再登録する #

POST /channels/viber/{botId}/verify-webhook

webhook_ok: false に対する修復アクションです。保存済みの認証トークンを使用して、ボット上のWebhookを再登録します。

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false は、保存されたトークンが機能しなくなったことを意味します。POST /channels/viber と新しいトークンを使用して再接続してください。

Viberの接続解除 #

DELETE /channels/viber/{botId}

Viber側でWebhookの登録を解除し（ベストエフォート）、接続を削除します。

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

利用可能性: 限定ベータ版であり、アカウントごとに有効化されます。アカウントが有効化されるまで、TikTokを接続すると権限エラーが返されます。

TikTokビジネスメッセージングはMetaと同様の完全なOAuthチャネルですが、ポーリングの面ではよりシンプルです。TikTokがリダイレクトされ接続が書き込まれると接続済みアカウントが自動的に表示されるため、構築すべき専用のステータス・ポーリング手順はありません。以下のステータスエンドポイントは、接続中にループさせるためのものではなく、オンデマンドで状態を確認するため（サポートツールやヘルスチェック用）に存在します。

ステップ 1 - TikTok接続を開始する #

POST /channels/tiktok/connect

認証情報は不要です。アカウント所有者がブラウザ上で完全に承認を行います。

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

アカウント所有者のブラウザで oauth_url を開き、TikTokにログインしてアクセスを承認してもらいます。状態は expires_at （約30分）で期限切れになります。期限が切れた場合は最初からやり直してください。TikTokには connect_url のホストページショートカットはありません。oauth_url を自分で開くのが唯一の方法です。

TikTokステータスの確認 #

GET /channels/tiktok/{openId}/status

openId はTikTokビジネスアカウントの open_id であり、OAuthコールバックが実行されると判明します。

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTokには簡易的なライブヘルスチェックがないため、live は常に false となります。各フィールドは接続（または前回のトークン更新）時に書き込まれた内容を反映しています。status_reason が設定された status: "reauth_required" は、アカウントが再度接続プロセスを経る必要があることを意味します。TikTokのトークンは1年ごとのローテーションで自動的に更新されますが、そのローテーションが失敗した場合にこの状態が表示されます。

TikTokの接続解除 #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) はメッセージングチャネルではなくCRM統合です。新しいチャネルを追加するのではなく、アカウントの既存チャネルを利用するため、接続してもプランのチャネル枠を消費しません。また、このページで唯一 一度に複数の接続を保持できる 統合です。顧客がアプリをインストールするGHLサブアカウント（「ロケーション」）ごとに、個別のエントリが作成されます。

ステップ 1 - GHL接続を開始する #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

アカウント所有者のブラウザで oauth_url を開き、GHLのロケーションを選択してアクセスを承認できるようにします。この状態は expires_at（約30分）で期限切れになります。

GHL接続の一覧表示 #

GET /channels/ghl/status

他のチャネルとは異なり、これは単一の接続ステータスではなく、アカウントが接続しているすべてのロケーションを一覧表示します。

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

GHLロケーションの接続解除 #

DELETE /channels/ghl/{locationId}

ここでの接続を削除すると、そのロケーションのすべての同期とトリガーが停止します。これはGHL側でアプリをアンインストールするものではありません。顧客がそれも希望する場合は、GHLマーケットプレイスのインストール済みアプリから削除する必要があります。

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

電話番号（購入および解放） #

既存の番号を接続する代わりに、WhatsApp対応の新しい番号を直接購入できます。利用可能な番号を検索して購入し、プロビジョニングが完了するまでポーリングしてください。

ステップ 1 - 利用可能な番号を検索する #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

各結果には、1回限りの purchase_credits と定期的な monthly_credits が表示されます。プラットフォームが提供する番号は月額最低50クレジットかかり、通信事業者の月額料金に応じて変動し、購入時および更新のたびに課金されます。検索結果で返される purchase_credits / monthly_credits を引用してください。自分で料金を算出しないでください。新しいアカウントでの最初の検索では基盤となるリソースがプロビジョニングされるため、その後の検索よりも少し時間がかかる場合があります。

ステップ 2 - 番号を購入する #

POST /phone-numbers

検索結果から phone_number を使用します。

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

番号は PURCHASED 状態で開始されます。その後、WhatsAppの登録がバックグラウンドで進行します: PURCHASED -> PENDING -> ONLINE。

ビジネス住所の不足やその他の必要な詳細が設定されていないために購入が失敗した場合、説明的な error を含む 400 が返されます。不足している詳細を設定してから再試行してください。

ステップ 3 - ONLINEになるまでポーリングする #

GET /phone-numbers/{phoneNumber}/status

これは共有の電話番号ステータスエンドポイントです。購入したWhatsApp番号だけでなく、接続されている他の番号にも使用できます。

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

レスポンス

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

ステップ 4 - 番号を解放する #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "phone_number": "+14155551234", "released": true }

この操作の結果は、その番号が誰のものかによって異なります。

プラットフォームを通じてレンタルされた番号の場合、完全な解放となります。WhatsApp送信者は登録解除され、番号は通信事業者に返却されてアカウントから削除されます。7日間のクールダウン期間が適用され、その間は誰もその番号を再購入できず、クレジットの返金も行われません。

アカウントが独自に持ち込んだ番号（独自のTwilioアカウント、独自のMetaアプリまたはWhatsApp Businessアカウント、あるいはAndroid SMSゲートウェイ）の場合、同じ呼び出しを行っても、その番号がアカウントから削除されるだけです。アップストリームのプロバイダー側で何かが解放されたり、クールダウンが設定されたりすることはないため、番号はすぐに再接続可能です。WhatsApp送信者の登録については、もし登録済みであった場合、そのまま残ることもあれば削除されることもあります。ティアダウン（破棄）処理では、アカウントのプラットフォーム管理下にあるTwilio認証情報を使用して送信者の削除を試みます。管理されたセットアップのままのアカウントでは、その認証情報は有効であり送信者は削除されるため、再接続には再登録が必要となります。独自のTwilioに切り替えたアカウントでは、削除時の認証が失敗するため、送信者はそのアカウントに登録されたままとなります。その場合、再接続は既存の送信者を再アタッチするだけで完了します。

所有済みの番号を追加する (BYO) #

POST /phone-numbers/byo

上記の検索・購入フローを完全にスキップします。アカウントがプラットフォーム経由で番号をレンタルするのではなく、独自の番号（独自のTwilio、独自のMeta WhatsApp Businessアカウント、またはAndroid SMSゲートウェイ）を持ち込む場合に使用します。これは番号を記録するだけで、クレジットは請求されず、プロバイダー側で何もプロビジョニングされません。アカウント所有者がWhatsApp OAuthを完了して送信者を登録するまで（ダッシュボードの「独自の番号を持ち込む」ボタンで開始されるフローと同じ）、番号は非アクティブのままです。

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

レスポンス (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

有効なE.164番号ではない phone_number（または、実際の顧客にメッセージを送ることができないMetaのWhatsAppテスト番号のように見えるもの）は、400 を返します。すでにアカウントに存在する番号を追加しようとすると（メキシコの +52 と +521 の形式のように、わずかに表記が異なる場合でも）、重複した行を作成するのではなく 409 を返します。

番号をプライマリに設定する #

POST /phone-numbers/{phoneNumber}/set-primary

1つの番号を is_active: true に、アカウント上の他のすべての番号を is_active: false にアトミックに変更します。リクエストの途中でアカウントが2つのアクティブな番号を持ったり、番号がなくなったりすることはありません。is_active は一般的な更新エンドポイントからは意図的に設定できないようになっています。この専用の呼び出しが、プライマリ番号を変更する唯一の方法です。

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

ここでの phone_number は文字列だけでなく、完全な番号オブジェクト（GET /phone-numbers が返すのと同じ形状）です。アカウントに存在しない phoneNumber は 404 を返します。

番号のレコードを削除する（解放はしない） #

DELETE /phone-numbers/{phoneNumber}/record

このアカウント上の番号レコードを単純に削除します。プロバイダー側での解放や登録解除は行われず、上記の解放ステップのような7日間のクールダウンも適用されません。これは、管理された解放フローを経由せずに、BYO、WhatsApp Web、Telegram、LINEのレコードや古いエントリをクリアする場合に使用します。解放とは異なり、アカウントに存在しない番号を削除すると、正常終了として扱われるのではなく 404 が返されます。

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

レスポンス

{ "success": true, "phone_number": "+14155551234", "deleted": true }

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

チャネルを接続すると、メッセージがアカウントに取り込まれます。どのAIエージェントが応答するかは、これによって決定されるわけではありません。

ルーティングはキャンペーンではなく、AIエージェント上のエントリーポイントによって処理されます。各チャネルには、そのチャネルで初めての未知の連絡先に応答するエージェントを指定する、チャネルデフォルトのエントリーポイントが1つあります。

チャネルにエントリーポイントが設定されるまで、話したことのない相手からの最初のメッセージは保存されますが、それを取得するものはなく、アシスタントからの返信もありません。これはほとんどの統合で見落とされるステップです。Instagramを接続してエージェントを作成するだけでは不十分であり、チャネルをエージェントに向ける必要があります。WhatsApp番号ごとのエージェント、キーワード、コメントルールなどを含む呼び出しの全セットについては、Entry Points APIを参照してください。

POST /channels/campaign は引き続き、以下に文書化されているレガシーのチャネル別キャンペーンルーティングマップを書き込みますが、そのマップはどのアカウントのインバウンドルーティングでも参照されなくなりました。これはロールバック目的でのみ保持されています。これに基づいた構築は行わないでください。

1つ以上のチャネルをルーティングする（レガシーキャンペーンルーティングマップ） #

POST /channels/campaign

リクエストフィールド

ルーティングスロットとキャンペーンの enabled_channels リストは1つのアトミックな操作で同時に更新されるため、不整合が生じることはありません。別のキャンペーンにすでにルーティングされているチャネルは、単にこのキャンペーンに向け直されます。

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

レスポンス

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

ルーティングが実際に機能するための条件 #

レガシーキャンペーンルーティングマップを読み取るアカウントでは、ルーティングはAPI呼び出しとして成功しますが、実際のインバウンドメッセージに応答するかどうかはキャンペーン上の3つの要素によって決定されます。ルーティングされたチャネルが反応しない場合は、これら3つすべてを確認してください。

キーワードマッチングは現在エントリーポイントに移行しています。応答させるべきAIエージェント上に keyword 型のエントリーポイントを作成してください。

1チャネルにつき1キャンペーン #

各チャネルは、レガシーのルーティングスロットを正確に1つ保持します。同じチャネルに2つ目のキャンペーンをルーティングすると、スロットがサイレントに再指定され 200 が返されます。競合エラーは発生しません。以前のキャンペーンはすでに保持している連絡先の処理を継続しますが、新しい連絡先の受信は停止します。

チャネルのルーティングをクリアする #

DELETE /channels/campaign/{channel}

単一チャネルのルーティングを削除します。現在どのキャンペーンを指しているかに関係なく、そのチャネルをキャンペーンの enabled_channels から外します。そのチャネル上の新しい不明な連絡先は、どのキャンペーンにも取り込まれなくなります。すでにキャンペーンに含まれている連絡先は、これまで通り継続されます。

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

これはべき等です。ルーティングが設定されていないチャネルをクリアしても、200 が返され、cleared: false と campaign_id: null が返されます。このエンドポイントには、プランの 着信キャンペーン 機能が必要です。これがない場合、403 が返されます。

独自のMetaアプリを使用する (Instagram + Messenger) #

デフォルトでは、Instagram + Messenger接続はプラットフォームのMetaアプリを経由して実行されるため、Facebookの同意画面にはそのアプリ名が表示されます。同意画面に貴社のブランド名を表示したい場合は、独自のMetaアプリを登録し、フロー全体をそのアプリ経由でルーティングすることができます。設定が完了すると、貴社のアカウントに適用されます。上記の接続呼び出しにおいて、ブランディング以外に変更はありません。

これはInstagram + Messengerのみを対象としています。 WhatsApp、WhatsApp Web、Telegram、およびLINEの接続は、カスタムMetaアプリの影響を受けません。

アプリに必要な準備 #

この手順には時間がかかり、すべてMeta側で行う必要があります。

1. MessengerおよびInstagramプロダクトを追加した、ビジネスタイプのアプリ。
2. 以下の権限に対する高度なアクセス権（Metaアプリ審査経由）: pages_show_list、pages_messaging、pages_manage_metadata、pages_read_engagement、instagram_basic、instagram_manage_messages。高度なアクセス権がない場合、アプリのロールを持つユーザーしか接続を完了できず、クライアントの接続は失敗します。アプリ審査には通常数週間かかり、ビジネス認証が必要です。
3. アプリ内で作成された、同じ権限を付与するFacebookログイン for Businessの設定。その数値設定IDはアプリごとに異なるため、独自に作成する必要があります。

アプリに必要な権限が不足している場合、接続時に不足している権限を明示したエラーが発生します（/status ポーリングで byo_app_missing_permissions として確認可能）。接続は成功したように見えて最初のメッセージ送信で失敗する、といった事態にはなりません。

ステップ 1 - アプリを保存する #

PUT /account-config/meta-app

これら3つはすべて、Facebookログインフローに必要です。以下で説明するInstagramログインのトークンプッシュレーンのみを実行する場合は、これらを完全に省略できます。

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

レスポンス

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

ステップ 2 - アプリが弊社と通信できるように設定する #

Metaアプリのダッシュボードにて：

1. Webhook - InstagramおよびMessengerの両プロダクトについて、コールバックURLにレスポンスから取得した対応する webhook_urls 値を設定し、確認トークンに verify_token を設定します。messages、messaging_postbacks、および comments フィールドを購読してください。
2. 有効なOAuthリダイレクトURI - 同意フローが戻れるように https://api.youraiconnector.com/v1/auth-meta-callback-handler を追加します。

GET /account-config/meta-app はいつでも同じセットアップ情報を返します。DELETE /account-config/meta-app はアプリを削除します（今後の接続はプラットフォームのアプリに戻ります。アプリ内のWebhook購読も削除してください）。

ステップ 3 - 通常通り接続する #

その他の変更はありません。POST /channels/meta/connect （およびホストされている connect_url ページ）は、貴社のアカウントに対して自動的に貴社のアプリを使用します。レスポンスの uses_byo_meta_app: true は、同意画面にどのアプリが表示されるかを確認するものです。メッセージの送信、ページの選択、および切断はこれまで通り機能します。

独自のInstagramログインアプリを使用する（トークンプッシュ） #

上記のセクションでは、Facebookページを通じてアカウントを接続するFacebookログインフローについて説明しました。Metaは、Instagramログインを利用したInstagram API（Instagram向けビジネスログイン）も提供しています。これを使用すると、Facebookアカウントやページを介さず、アカウント所有者がInstagram上で直接認証を行えます。

お客様のプラットフォームですでにそのプロダクトを利用した独自のMetaアプリを運用している場合、弊社側でOAuthフローを実装する必要は一切ありません。クライアントがお客様のアプリを承認し、アカウントごとの完了した認証情報を弊社にプッシュするだけで済みます。

1. Instagramアプリの認証情報を一度保存します（弊社がウェブフックを検証できるようにするため）。
2. アカウントごとに、InstagramプロフェッショナルアカウントIDと、アプリで取得したInstagram長期アクセストークンをプッシュします。
3. アプリのInstagramメッセージングウェブフックの送信先を弊社に設定します。プッシュされていないアカウントのイベントは受信確認され、無視されます。
4. トークンのライフサイクルはお客様が管理します。自社システムでトークンを更新し、更新のたびに同じ呼び出しで新しいトークンをプッシュしてください。弊社側でプッシュされたトークンを更新することはありません。

アプリに必要な準備 #

• Metaアプリに追加されたInstagramプロダクト（「Instagramログインを利用したAPI設定」）。このプロダクトには、FacebookアプリID/シークレットとは別の、独自のアプリIDとアプリシークレットのペアがあります。プロダクトの設定パネルで確認してください。
• instagram_business_basicおよびinstagram_business_manage_messagesに対する高度なアクセス権（Metaアプリ審査経由）。コメント自動化を使用する場合はinstagram_business_manage_commentsも追加してください。これがない場合、アプリのロールを持つユーザーのみが承認を行えます。

ステップ 1 - Instagramアプリの認証情報を保存する #

上記と同じエンドポイントを使用し、InstagramのペアをPUT /account-config/meta-appに送信します。このレーンではFacebookフィールドは不要です。Instagramログインのみを実行する場合はペアのみを送信し、両方を実行する場合はFacebookフィールドと一緒に送信してください。保存操作は常に設定全体を記述するため、省略したセットは削除されます。

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

レスポンス — InstagramログインのWebhook URLが含まれます（instagramおよびmessengerのURLは、Facebookフィールドも保存されている場合にのみ表示されます）：

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

アプリのInstagramプロダクト用ウェブフックパネルで、コールバックURLをwebhook_urls.instagram_loginに、検証トークンをverify_tokenに設定し、messagesおよびcommentsフィールドをサブスクライブします。

ステップ 2 - アカウントごとにトークンをプッシュする #

PUT /channels/instagram-login/token

他のすべてのルートと同様にsub_account_idで動作するため、エージェンシーキーを使用して全アカウントを一括でプロビジョニングできます。

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

レスポンス

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

プッシュの一環として、弊社はお客様のアプリをそのアカウントのウェブフックにサブスクライブします（プッシュされたトークンを使用してsubscribed_appsを実行）。これにより、お客様側で追加の呼び出しを行わなくてもメッセージの送受信が開始されます。

更新 - 更新されたトークンを同じ ig_user_id を持つ同じエンドポイントにプッシュします。これにより、保存されているトークンと有効期限がその場で更新されます。

競合 - 1つのInstagramアカウントを2つの接続で同時にライブ状態にすることはできません。アカウントが他の場所ですでに接続されている場合、またはFacebookページフローを通じてこのアカウント自体で接続されている場合、プッシュは最初に切断すべき接続を通知する 409 を返します。Facebookフローによる接続は、Messengerのサービスも提供している可能性があるため、自動的に置き換えられることはありません。

ステップ 3 - クライアントが離脱した際の切断 #

DELETE /channels/instagram-login/token（同じ認証と sub_account_id）は、ベストエフォートでWebhookの登録を解除し、保存された認証情報を削除します。トークンがすでに無効になっている場合でも常に成功し、認証情報が削除されると、そのアカウントのWebhookイベントは無視されます。

信頼性の高いラッパーを構築するためのヒント #

• ポーリングは控えめに。 数秒おきで十分です。終了状態（connected / ONLINE、または失敗ステータス）に達したら停止し、ループ全体に適切なタイムアウトを設定してください（ブラウザ/QRステップには有効期限があります。各 expires_at を参照）。
• パス内の電話番号はURLエンコードしてください。 先頭の + は %2B として送信する必要があります。エンドポイントは生の数字も復元できますが、エンコードするのが安全なデフォルトです。
• シークレットが返されることを期待しないでください。 アクセストークン、チャネルシークレット、ページトークンは受け入れまたは保存されますが、レスポンスで返されることはありません。
• 認証ゲートを処理してください。 403 は、APIアクセスがプランに含まれていないか、接続しようとしているチャネルがアカウントのプランに含まれていないことを意味します。APIアクセスを参照してください。
• レート制限に注意してください。 認証済みリクエストは1分間に300回までです。429 は、間隔を空けて再試行する必要があることを意味します。認証を参照してください。

次のステップ #

• 認証 - 4つの承認された認証形式とエラー形式。
• APIアクセス - APIキーの生成と管理。