API入門 #

Your AI Connector REST APIを使用すると、アカウント上で独自の統合を構築できます。連絡先の作成や検索、キャンペーン、FAQ、タスク、予定の管理、メッセージの送信、Webhookの登録、分析の読み取り、メッセージングチャネルの接続など、ダッシュボードでできるすべての操作をコードで実行できます。

ここはAPIドキュメントのハブページです。Your AI Connectorをすでに組み込み統合機能を持つツールに接続している場合、APIは不要かもしれません。APIは、カスタム統合や大規模な自動化のためのものです。

ベースURL #

すべてのリクエストは同じベースWebアドレスに送信されます。これらのドキュメント内のすべてのパスは、そのアドレスからの相対パスです。

https://api.youraiconnector.com/v1

つまり、キャンペーンのエンドポイントはhttps://api.youraiconnector.com/v1/campaigns、連絡先のエンドポイントはhttps://api.youraiconnector.com/v1/contactsのようになります。

すべてのリクエストは安全な接続（HTTPS）を使用する必要があります。通常のHTTPリクエストは拒否されます。

APIキーの取得 #

APIアクセスは有料機能です。ご利用のプランに含まれていない場合、すべてのリクエストは以下の本文を含む403を返します。

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

プランでAPIアクセスが有効になったら、ダッシュボードからキーを生成してください。詳細な手順はAPIアクセスに記載されています。簡単に説明すると、設定 → インテグレーション → APIキーに移動して、キーの生成または再生成を行います。「APIキー」はインテグレーション内の独立したセクションであり、Webhookとは別になっています。また、APIアクセスがプランで有効になっている場合にのみ表示されます。キーはパスワードと同様に扱い、アカウントへのフルアクセス権を与えるものとして管理してください。

認証 #

APIキーは4つの方法で送信できます。いずれの方法も、APIキー認証を受け入れるすべてのエンドポイントで機能します。

本番環境では、キーがサーバーログやブラウザ履歴に残らないよう、ヘッダー形式のいずれかを使用することをお勧めします。クエリパラメータ形式は常に機能し、単発のテストには最も簡単です。

各メソッドの詳細、例、および使用時期に関するガイダンスについては、認証を参照してください。

最初のリクエスト #

アカウント上のキャンペーンを一覧表示する、完全で動作可能な呼び出しの例を以下に示します。これはAPIキーを使用し、最新のキャンペーンから順に返します。

cURL

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

JavaScript

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

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

成功時のレスポンスは以下のようになります。

{
  "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": null
}

成功およびエラーレスポンス #

すべてのJSONレスポンスには success フラグが含まれているため、ステータスコードを解析することなく条件分岐を行うことができます。

成功時のレスポンスは success: true に加えて、そのエンドポイントのデータが含まれます（フィールド名は campaigns、contacts、data など、エンドポイントによって異なります）。

{
  "success": true,
  "campaigns": []
}

失敗時のレスポンスは success: false となり、人間が判読可能な error メッセージと、HTTPステータスと一致する数値の error_code が含まれます。

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

データを読み取る前に、必ず success （またはHTTPステータス）を確認してください。ステータスコードの完全な表や、大きな結果セットをページングする方法については、「Errors & Pagination」を参照してください。

レート制限 #

認証済みリクエストは、APIキーごとに1分あたり300リクエストに制限されています。また、アカウント全体では1分あたり1,200リクエストというより広い上限が設けられており、そのアカウントに対して行われたすべての認証済みリクエストがカウントされます。

いずれかの制限を超えた場合、429レスポンスが返されます：

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

少し待ってから再試行してください。また、GET https://api.youraiconnector.com/v1/api-keys/usage を使用して現在の使用状況をいつでも確認できます。これには、現在のウィンドウで使用したリクエスト数とリセット時刻が返されるため、クライアント側のスロットリングを構築する際に役立ちます。「API Keys」を参照してください。

リソースガイド #

以下のリソースグループには、それぞれ正確なパス、リクエストフィールド、レスポンスの形式をまとめたガイドが用意されています。

エージェント、エントリーポイント、ブロードキャスト #

AIエージェント、エントリーポイント、ブロードキャストはすべて公開されているOpenAPI仕様に含まれているため、APIエクスプローラーで正確なフィールドを確認し、ライブリクエストを実行できます。それぞれに専用のガイドがあります：AIエージェント、エントリーポイント、ブロードキャスト。

Markdown形式でのドキュメントの閲覧 #

このドキュメントのすべてのページには、プレーンなMarkdown形式の対となるページが存在します。ページのアドレスの末尾に /index.md を追加してください。したがって、このページも https://docs.youraiconnector.com/api/getting-started/index.md で利用可能であり、Webページではなくプレーンテキストとして取得されます。AIアシスタントにページを貼り付けたり、スクリプトに取り込んだりする場合に便利です。

全体を確認するには、公開しているすべてのページが一覧表示されている https://docs.youraiconnector.com/sitemap.xml から始めてください。ドキュメントは意図的に検索エンジンから除外されているため、コードからアクセスする場合は、これらのアドレスを直接取得する方法が推奨されます。

現時点では、キーで保護されたドキュメントエンドポイントや一括ダウンロード機能はありません。Markdown形式のページとサイトマップがインターフェースのすべてであり、どちらもAPIキーを必要としません。

次のステップ #

• 認証 — 統合に適した認証方法を選択します。
• エラーとページネーション — 失敗の処理と結果のページネーションを行います。
• APIアクセス — キーを生成し、動作例を確認します。