# APIアクセス

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


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

::: note
**注意：** このページは技術的な内容を含みます。あなたがビジネスオーナーで開発者ではない場合は、このページを技術チームやフリーランスの開発者に共有することをお勧めします。
:::


---

## APIキーの生成

::: note
**注意：** APIアクセスは、対象プランで利用可能な有料機能です。プランに含まれていない場合、APIリクエストは `403` レスポンスで拒否されます。APIアクセスが有効かどうか不明な場合は、プランを確認するか、サポートにお問い合わせください。
:::


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


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


::: note
**注意:** 一部のアカウントでは、Show/Copyコントロールの代わりに「Your key can't be displayed」と表示されることがあります。これは、アプリがキーを再表示できるようになる前に作成されたキーで発生します。キーは通常通り機能します。プレーンテキストを再度確認する必要がある場合にのみ、**Regenerate**（キーカードの下、同じセクション内）を使用してください。再生成を行うと古いキーは直ちに無効となり、それを使用しているすべての統合が機能しなくなります。新しいキーを貼り付けるまで利用できなくなるため、再生成後はすぐに統合設定を更新してください。
:::


::: warning
**重要：** APIキーはパスワードのようなもので、アカウントへの完全なアクセス権を付与します。公開したり、他人が見られる場所に投稿したりしないでください。キーが漏洩したと思われる場合は、直ちに再生成してください。
:::


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

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

---

## ベース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/getting-started.md)および[APIリファレンス](../api/reference.md)を参照してください。

---

## 一般的なAPI操作

### 連絡先の作成

**リクエスト:**

```http
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`（国番号付き）が必要です。メールアドレスだけでは不十分であり、有効な電話番号がないリクエストは拒否されます。メールアドレスは任意です。

**レスポンス:**

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

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

::: note
**注意：** 同じ電話番号を持つ連絡先がすでに存在する場合、APIはその連絡先を作成または返しません。代わりに `{ "success": false, "error_code": 409 }` を返します。先に `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...` を使用して既存の連絡先を検索してください。
:::


---

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

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

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

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

---

### 連絡先を更新する

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

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

含めたフィールドのみが変更されます。これは、インポート後にカスタムフィールドの値を一括読み込みする方法でもあります。詳細は[カスタムフィールド、リードプロファイル、メモ](../get-started/custom-contact-fields.md#bulk-loading-custom-fields)を参照してください。詳細は[連絡先API](../api/contacts.md)に記載されています。

---

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

```http
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"
  }
}
```

| フィールド | 必須 | 説明 |
|---|---|---|
| `customData.fromId` | はい | お客様のプラットフォームにおけるコンタクトのID |
| `customData.customChannel` | はい | カスタムチャネルの名前 |
| `customData.body` | はい | 送信するメッセージテキスト |
| `customData.campaignId` | いいえ | メッセージを特定のキャンペーンにルーティングする |
| `customData.firstName` | いいえ | コンタクトの名（新しいコンタクトを作成する場合に使用） |
| `customData.lastName` | いいえ | コンタクトの姓 |
| `customData.email` | いいえ | コンタクトのメールアドレス |

::: note
**注:** このエンドポイントはカスタムチャネルメッセージ用です。WhatsApp、SMS、Instagram、Messengerの場合、メッセージはブロードキャスト、キャンペーン、AIエージェントを通じて送信されます。
:::


---

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

外部システムからのメッセージをカスタムチャネルとして受け取ります。GoHighLevelのような統合機能が<span data-t="appName">Your AI Connector</span>にメッセージを送信する仕組みはこれに基づいています。詳細については、[カスタムチャネル](../messaging-channels/custom-channels.md)を参照してください。

```http
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"
}
```

| フィールド | 必須 | 説明 |
|---|---|---|
| `customData.messageSid` | はい | このメッセージの一意のID（重複を防ぎます）。`customData.id` を使用することもできます。 |
| `customData.fromId` | はい | 外部システムにおける送信者のID。 |
| `customData.toId` | はい | ビジネス識別子。 |
| `customData.body` | はい | メッセージのテキスト。 |
| `customData.channel` | いいえ | ソースのラベル（例: `"email"`、`"livechat"`、`"custom"`）。 |
| `customData.status` | いいえ | メッセージのステータス。デフォルトは `"received"` です。 |
| `messageType` | いいえ | テキストメッセージの場合は `"text"`、絵文字リアクションの場合は `"reaction"`。 |

---

## 利用可能な操作の概要

| アクション | メソッド | アドレス | 説明 |
|---|---|---|---|
| 連絡先の作成 | `POST` | `/contacts` | アカウントに新しい連絡先を追加する |
| 連絡先詳細の取得 | `GET` | `/contacts?phoneNumber=X` または `/contacts?email=X` | 電話番号またはメールアドレスで連絡先を検索する |
| 連絡先の更新 | `PUT` | `/contacts/{contactId}` | 既存の連絡先の任意のフィールドを更新する |
| リストへの連絡先追加 | `POST` | `/contacts/lists` | 既存の連絡先を特定のリストに追加する |
| メッセージの送信 | `POST` | `/send_custom_channel_message` | カスタムチャネル経由でメッセージを送信する |
| メッセージの受信 | `POST` | `/incoming_custom_channel_message` | 外部システムからのメッセージを受け入れる |

---

## レート制限

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## ベストプラクティス

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

---

## エラーレスポンス

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

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## 次のステップ

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