> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# インテグレーション

> 任意 — サードパーティ API キーを OneInbox に保存（BYOK）。

## インテグレーションとは

**インテグレーション**は、OneInbox 内に安全に保存されるサードパーティ API キーです。

* OneInbox がキーを **暗号化** して保存
* 作成後、生のキーは **返却されない**
* 他の API 呼び出しでは `id` で参照

***

## いつ使うか

インテグレーションは **完全に任意**です。OneInbox はすべてのものにデフォルトを提供します — LLM、STT、TTS、電話番号 — インテグレーションなしでビルドとテストができます。

以下を持ち込みたい場合のみ追加します：

* **LLM** — **openai**、**shisa**、**custom**（`custom_websocket_url` 経由）はデフォルトで利用できます（キー不要）。**anthropic** と **groq** を使用するには、自分の API キーを持ち込んで先にインテグレーションを作成する必要があります。
* **STT** — すべてのプロバイダー（**deepgram**、**whisper**、**assembly\_ai**、**azure**）はデフォルトで利用できます（キー不要）。自分のプロバイダーアカウントに課金したい場合のみインテグレーションを追加してください。
* **TTS** — すべてのプロバイダー（**cartesia**、**deepgram**、**elevenlabs**、**openai**、**shisa**、**minimax**）はデフォルトで利用できます（キー不要）。自分のプロバイダーアカウントに課金したい場合のみインテグレーションを追加してください。
* **電話番号** — OneInbox のデフォルトの代わりに自分の Twilio または Telnyx アカウントの番号を使用
* **メールまたはカレンダーツール** — `send_email` と `schedule_calendar_event` には Resend/SendGrid または Cal.com アカウントを指す `credential_id` が必要

***

## 作成方法

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production",
    "provider": "openai",
    "api_key": "<your_provider_api_key>"
  }'
```

メール、テレフォニー、カレンダー系プロバイダーはプロバイダー固有の詳細を含む `metadata` オブジェクトも受け付けます：

```bash theme={null}
# メール（Resend / SendGrid）— 認証済みの送信元アドレスが必要
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resend Email",
    "provider": "resend",
    "api_key": "<your_resend_api_key>",
    "metadata": { "from_email": "hello@yourdomain.com" }
  }'
```

```bash theme={null}
# Twilio — 購入した電話番号 + SIP トランク設定が必要
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Twilio Account",
    "provider": "twilio",
    "api_key": "<your_twilio_auth_token>",
    "metadata": {
      "account_sid": "<your_twilio_account_sid>",
      "phone_number": "+15739693824",
      "sip_trunk": "<your_sip_trunk_domain>"
    }
  }'
```

```bash theme={null}
# Cal.com — API キーのみ；event_type_id はインテグレーションではなくツールに設定
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cal.com Bookings",
    "provider": "calcom",
    "api_key": "<your_calcom_api_key>"
  }'
```

***

## Resend のセットアップ

`send_email` ツールを Resend で使用するには、Resend API キーと認証済みの送信ドメインの 2 つが必要です。

### 1 — Resend API キーを取得

1. [resend.com](https://resend.com) にアクセスしてログイン
2. 左サイドバーの **API Keys** を開く
3. **Create API Key** をクリック — 「OneInbox」などの名前を付ける
4. キーをコピー（`re_` で始まる）

### 2 — 送信ドメインを認証

Resend は認証されていないドメインからのメールをブロックします — 送信は HTTP 403 で失敗します。

1. Resend で **Domains** → **Add Domain** へ
2. 送信元にしたいドメインを入力（例：`yourdomain.com`）
3. Resend が追加すべき DNS レコードを表示します — 通常 3 つのレコード：

| タイプ     | 目的                                       |
| ------- | ---------------------------------------- |
| `TXT`   | SPF — Resend があなたの代わりに送信できることを受信サーバーに伝える |
| `CNAME` | DKIM — 送信メッセージが本物であることを暗号的に証明する          |
| `CNAME` | DMARC の整合性（任意だが推奨）                       |

4. DNS プロバイダー（GoDaddy、Cloudflare、Route 53 など）でこれらのレコードを追加
5. Resend で **Verify** をクリック — 通常は数分で伝播する

<Note>
  認証した**正確なドメイン**（またはそのサブドメイン）からのみ送信できます。例えば `yourdomain.com` を認証すると `hello@yourdomain.com` や `noreply@yourdomain.com` から送信できます。`mail.yourdomain.com` はそのサブドメインを別途認証しない限り対象外です。
</Note>

### 3 — インテグレーションを作成

認証済みの送信アドレスを `metadata.from_email` として渡します。これがエージェントが送信するすべてのメールの「From」フィールドに表示されるアドレスです：

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resend Email",
    "provider": "resend",
    "api_key": "<your_resend_api_key>",
    "metadata": { "from_email": "hello@yourdomain.com" }
  }'
```

返却された `id` を保存します — `send_email` ツール作成時に `credential_id` として使用します。

***

## Cal.com のセットアップ

`schedule_calendar_event` ツールを使用するには、Cal.com API キーとエージェントが予約対象とするイベントタイプの ID が必要です。

### イベントタイプとは？

Cal.com のイベントタイプは予約可能な会議です — 時間、空き状況、予約フォーム、確認設定を定義します。例：

| イベントタイプ    | 時間   | 用途                   |
| ---------- | ---- | -------------------- |
| 製品デモ       | 30 分 | エージェントが興味あるリードのデモを予約 |
| ディスカバリーコール | 20 分 | 初回の資格確認通話            |
| オンボーディング   | 60 分 | 新規顧客のセットアップセッション     |

各イベントタイプには OneInbox に渡す数値 ID があります。

### 1 — Cal.com API キーを取得

1. [cal.com](https://cal.com) にログイン
2. **Settings** → **Developer** → **API Keys** へ
3. **Add** をクリック — 名前を付けてキーをコピー

### 2 — イベントタイプ ID を確認

**URL から:** Cal.com ダッシュボードで **Event Types** を開き、対象のイベントの Edit をクリック。URL に ID が含まれます：

```
https://app.cal.com/event-types/123456
                                ^^^^^^
                                これが event_type_id
```

**API から：**

```bash theme={null}
curl "https://api.cal.com/v2/event-types" \
  -H "Authorization: Bearer <your_calcom_api_key>"
```

レスポンスにすべてのイベントタイプとその `id` フィールドが一覧表示されます。エージェントに予約させたいものを選択します。

### 3 — 空き状況を設定

エージェントは Cal.com で空き状況がある枠のみ予約できます。本番稼働前に：

* イベントタイプに**稼働時間**を設定（例：月〜金、午前 9 時〜午後 5 時）
* 必要に応じて会議間の**バッファ時間**を設定
* イベントタイプが**アクティブ**（下書きでない）状態であることを確認

発信者が空き状況外の時間を要求した場合、予約は HTTP 400 で失敗し、エージェントはその枠が利用できないことを発信者に伝えます。

<Note>
  エージェントは会話中に発信者の**名前とメールアドレス**を取得する必要があります — Cal.com が予約を完了するためにどちらも必須です。スケジュールを試みる前にこれらを尋ねるようエージェントのシステムプロンプトを設定してください。
</Note>

### 4 — インテグレーションを作成

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cal.com Bookings",
    "provider": "calcom",
    "api_key": "<your_calcom_api_key>"
  }'
```

返却された `id` を保存します — `schedule_calendar_event` ツール作成時に `credential_id` として使用します。`event_type_id` はインテグレーションではなくツール自体に設定します。

<Tip>
  複数のイベントタイプ（デモ、ディスカバリー、オンボーディング）を運用する場合、**イベントタイプごとに別のインテグレーションを作成**してください — それぞれが異なる `event_type_id` を指します。次に、各インテグレーションに対して別々の `schedule_calendar_event` ツールを作成し、発信者の要求に基づいてエージェントが適切なものを発火できるよう明確な説明を付けてください。
</Tip>

***

## インテグレーションのつながり

```
インテグレーション（任意 BYOK）
        │
        ▼
一致する "provider" の LLM モデル
        │
        ▼
エージェント（llm_id）→ 通話
```

テレフォニーインテグレーションは、番号検索・登録の `credential_id` 経由で [電話番号](/jp/guides/phone-calls) を支えます。

***

## インテグレーションの管理

### 全インテグレーションを一覧表示

```bash theme={null}
curl https://api.oneinbox.ai/v1/integrations \
  -H "Authorization: Bearer <api_key>"
```

### インテグレーションを取得する

```bash theme={null}
curl https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>"
```

生の `api_key` は返されません — `masked_key` のみ表示されます。

### インテグレーションを更新する

既存のインテグレーションの名前、API キー、メタデータ、またはプロバイダーを更新します。

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Updated",
    "api_key": "<new_api_key>"
  }'
```

### インテグレーションを削除する

保存された認証情報を永続的に削除します。この `credential_id` を使用しているモデルやツールは、新しいインテグレーションを紐付けるまでプロバイダーへのアクセスを失います。

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/integrations/<credential_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## 次のステップ

* **[電話番号](/jp/guides/phone-calls)** — テレフォニーインテグレーション
* **[ボイス](/guides/voices)** — カスタムボイスのインポート
* **[インテグレーション作成](/api-reference/integrations/create-integration)** — API リファレンス