APIアクセス #

API（Application Programming Interface）とは、異なるソフトウェアシステム同士が通信するための手段です。Your AI Connector APIを使用すると、ダッシュボードを使わずに、連絡先の自動作成、メッセージの送信、リストの管理、カスタムチャネルからの受信メッセージの受け取りなどを、あなた（または開発者）が行えるようになります。

APIを使用する理由： アプリを組み込みの統合機能がないツールに接続したい場合や、反復的なタスクを大規模に自動化する必要がある場合に、APIが最適な手段となります。

APIキーの生成 #

1. 左側のサイドバーで Settings（歯車アイコン）をクリックします。
2. 設定サイドバーの Integrations グループの下にある API Key をクリックします。

3. まだキーをお持ちでない場合は、Generate API keyをクリックしてください。
4. すでにキーをお持ちの場合は、Your keyの下にマスクされた状態で表示されます。キーが対応している場合は、Showをクリックして表示し、Copyをクリックしてコピーしてください。確認のトースト通知が表示されます。
5. キーは安全な場所に保管してください。すべてのAPIリクエストで必要になります。

チームメンバーの方へ: APIキーはアカウント所有者に帰属します。そのため、招待されたチームメンバー（管理者を含む）としてサインインしている場合、このセクションにはキーの代わりに注記が表示されます。キーの表示、コピー、再生成を行うには、アカウント所有者としてサインインしてください。これはスコープ付きキーにも適用されます。

場所： API Key は、Settings → Integrations 内の Webhooks とは別のセクションにあります。ガイドや同僚から「Webhooks」セクションでキーを探すように言われた場合は、隣のセクションを確認してください。

スコープ付きキー: 特定のタスク専用の追加キー #

メインキーはすべての操作が可能であるため、レポート、クライアントダッシュボード、あるいは個別のサンドボックスや開発環境に渡すキーとしては適していません。そのような場合には、Your key（メインキー）の下にある API Key セクションの Scoped keys（スコープ付きキー）カードで、スコープ付きキーを作成してください。

1. New key をクリックします。
2. 後で識別しやすい Name（名前）を付けます（例: 「Sandbox」や「Acmeクライアントダッシュボード」など）。
3. What it can see（アクセス範囲）で、必要な領域のみにチェックを入れます。
4. What it can do（権限）では、ツールが変更を行う必要がない限り、Read only（読み取り専用）のままにします。変更可能なキーは、メッセージの送信や設定の編集ができてしまいます。
5. 必要に応じて、Requests per minute（1分あたりのリクエスト数。独自の制限を設定することで、他の統合環境の速度低下を防げます）や Expires on（有効期限）を設定します。
6. Create key をクリックし、すぐにキーをコピーしてください。スコープ付きキーは一度しか表示されません。紛失した場合は、そのキーを無効化（Revoke）してから新しく作成してください。

必要な数だけ作成できます。リスト内の各キーには最終使用日時が表示され、Revoke key をクリックすると即座に使用が停止されます。スコープ付きキーを作成または無効化しても、メインキーには一切影響しません。特定のサブアカウントに制限されたキーを含むすべてのオプションについては、APIリファレンスのAPIキーページを参照してください。

ベースURL #

すべてのAPIリクエストは、以下のベースWebアドレスを使用します。

https://api.youraiconnector.com/v1/

認証 #

プラットフォームがあなたを識別できるように、すべてのリクエストにはAPIキーを含める必要があります。最も簡単な方法は、Webアドレスの末尾に追加することです：

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

また、URLではなくリクエストヘッダーとしてキーを送信することもできます（キーがサーバーログに残らないため、本番環境ではこちらが推奨されます）：

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

開発者向けガイドの全文をお探しですか？ このページは、最も一般的な操作を網羅したクイックイントロダクションです。すべてのリソースを網羅し、cURL、JavaScript、Pythonの例を含む完全なステップバイステップガイドについては、APIの利用開始およびAPIリファレンスを参照してください。

一般的なAPI操作 #

連絡先の作成 #

リクエスト:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

必須フィールド： 連絡先を作成するには、常に phoneNumber（国番号付き）が必要です。メールアドレスだけでは不十分であり、有効な電話番号がないリクエストは拒否されます。メールアドレスは任意です。

レスポンス:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

data.contactId を保存してください。「Add a Contact to a List」の呼び出しで必要になります。

リストへのコンタクトの追加 #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

アプリの 連絡先 → リスト からリストの行メニュー（リストIDをコピー）を使用して、リストのIDを確認します。

連絡先を更新する #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

含めたフィールドのみが変更されます。これは、インポート後にカスタムフィールドの値を一括読み込みする方法でもあります。詳細はカスタムフィールド、リードプロファイル、メモを参照してください。詳細は連絡先APIに記載されています。

メッセージの送信（カスタムチャネル） #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

受信メッセージの受け取り（カスタムチャネル） #

外部システムからのメッセージをカスタムチャネルとして受け取ります。GoHighLevelのような統合機能がYour AI Connectorにメッセージを送信する仕組みはこれに基づいています。詳細については、カスタムチャネルを参照してください。

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

利用可能な操作の概要 #

レート制限 #

APIは、プラットフォームの安定性を確保するためにレート制限を設けています。制限を超えると 429 Too Many Requests が返されます。その場合はリクエストを控え、レスポンスヘッダーに示された時間が経過してから再試行してください。大量のデータ処理（一括インポート）を行う場合は、組み込みの インポート機能 を使用するか、hi@youraiconnector.com までメールでガイダンスをお問い合わせください。

ベストプラクティス #

• APIキーを安全に保管してください — パスワードマネージャーやサーバー側の設定を使用し、ブラウザの訪問者が読み取れるようなクライアント側のコードには決して含めないでください。
• 電話番号には必ず国番号を含めてください (米国は +1、英国は +44、オランダは +31)。
• エラーを適切に処理してください — ステータスコードを確認し、返されたエラーメッセージを読み取ってください。
• 重複を処理してください — 電話番号が重複している場合、新しい連絡先の代わりに { "success": false, "error_code": 409 } が返され、既存の連絡先のIDが contactId に含まれます。
• 一括操作を実行する前に、小さなデータセットでテストしてください。

エラーレスポンス #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

次のステップ #

• Webhook — アプリからリアルタイムの通知を受け取ります（APIキーとは別のセクションです）。
• AIアシスタントの接続 (MCP) — 同じAPIキーを使用して、Claudeでアカウントを操作できるようにします。
• Facebookリードフォーム — 自動化プラットフォームでAPIを使用してリードを獲得します。
• GoHighLevel統合 — 完全な双方向API統合の例です。