# 代理店向けAPI

代理店として、クライアントが使用するものと同じREST APIを使用できますが、個々のリクエストを自分のアカウントではなく、管理下の**サブアカウント**に向けて送信します。これにより、クライアントのオンボーディングをエンドツーエンドで実行するツールを構築できます。キャンペーンの作成、ナレッジベースでのAIのトレーニング、連絡先のインポート、メッセージングチャネルの接続、電話番号の購入などを、各サブアカウントに手動でログインすることなくすべて実行可能です。

このページでは、代理店固有の動作、つまり `sub_account_id` パラメータを使用してサブアカウントの代理として操作する方法のみを説明します。基本事項（キーの生成、認証、ベースURL、エラー形式、レート制限）については、[APIアクセス](../integrations/api-access.md)ガイドから始めてください。そこに記載されているすべての内容はここにも適用されます。認証には**代理店アカウントの**APIキーを使用します。

::: note
**注:** このページは技術的な内容です。開発者ではない場合は、インテグレーションを担当している方に共有してください。
:::


***

## 「代理として操作する」仕組み

デフォルトでは、すべてのAPIリクエストはAPIキーを所有するアカウント、つまり代理店アカウントに対して実行されます。管理下のクライアントアカウントに対して操作を行うには、リクエストにオプションの `sub_account_id` パラメータを追加し、そのクライアントのアカウントIDを設定します。

- **`sub_account_id` を省略** → リクエストは自身の代理店アカウントに対して実行されます。
- **`sub_account_id` を含める** → リクエストはそのサブアカウントに対して実行されますが、プラットフォームがそのサブアカウントが実際にあなたのものであることを確認した後にのみ実行されます。

認証には常に**代理店アカウントの**APIキーを使用します。サブアカウント自身のキーは一切不要であり、サブアカウントの認証情報を扱う必要もありません。

### 指定方法

- **GET / DELETE エンドポイント** → クエリパラメータとして渡します: `?sub_account_id=THE_SUB_ACCOUNT_ID` (クエリで認証を行う場合は、`apiKey` と併せて指定します)。
- **POST / PUT / PATCH エンドポイント** → JSONリクエストボディに `"sub_account_id": "THE_SUB_ACCOUNT_ID"` として含めます。
- **AIアシスタント** → 設定は不要です。[MCPサーバー](../integrations/connect-ai-clients.md)は読み取りツールで同じ設定を保持しているため、エージェンシーキーによる1つの接続ですべてのクライアントのレポートを作成できます。リクエスト内でクライアント名を指定するだけです（例: 「Bella's Bistroには何人の連絡先がありますか？」）。書き込みアクションも利用可能です。`sub_account_id` を受け入れるすべてのエンドポイントがツールとして公開されているため、同じ接続からクライアントに代わって作成、変更、送信を行うことができます。

### サブアカウントIDの確認方法

`sub_account_id` は、クライアントアカウントの一意のIDです。サブアカウントとそのIDのリストは、**SubAccounts** APIエンドポイント（[サブアカウント](sub-accounts.md)ガイドを参照）またはサイドバーの **Sub Accounts** ページから取得できます。

***

## 所有権は常に検証されます

`sub_account_id` を渡すと、プラットフォームはそのアカウントが実際のサブアカウントであること、**かつ**あなたの代理店に属していることを確認します。その確認が取れた場合にのみ、リクエストが処理されます。

IDが不明な場合、サブアカウントではない場合、または別の代理店に属している場合、リクエストは **`404`** レスポンスで失敗します：

```json
{
  "success": false,
  "error_code": 404,
  "error": "Sub-account not found."
}
```

> **なぜ403ではなく404なのか？** 「forbidden（禁止）」というレスポンスは、外部の人間に対して、そのIDが存在するものの自分のものではないという情報を与えてしまいます。存在しない場合と自分のものではない場合の両方に同じ `404` を返すことで、そのエンドポイントを使ってどのIDが他の代理店に属しているかを特定されることを防げます。ここでは `404` を「あなたが管理していないサブアカウントです」という意味として扱ってください。

***

## `sub_account_id` がサポートされている場所

`sub_account_id` は、基本的にすべての**リソース**エンドポイント（アカウント固有のデータの作成、読み取り、更新、削除を行うすべての呼び出し）で受け入れられます。実際には、代理店キーを使用してサブアカウントのセットアップ全体をプロビジョニングし、実行することができます:

- **AI設定** — キャンペーン、エージェント、FAQ、ナレッジベースソース（ウェブサイトクロール **および** ドキュメントアップロード）、ナレッジベースグループ、ブロードキャスト、カスタム関数、MCPサーバー
- **連絡先 & CRM** — 連絡先（インポートを含む）、リスト、タグ、タスク、案件、アポイントメント、イベント
- **チャネル & 番号** — WhatsApp / WhatsApp Web / Telegram / Instagram & Messenger / LINEの接続、電話番号の検索 / 購入 / 管理、WhatsAppテンプレート、チャネルルーティング
- **メッセージング & コンテンツ** — メッセージ送信、チャットセッション、チャットエクスポート、日次サマリー
- **設定 & 統合** — Webhook、チャットウィジェット設定、ホワイトラベル設定、BYOK SMSおよびその他のアカウント設定、分析

これらの各パラメーターは**オプション**です。省略した場合、呼び出しはあなた自身の代理店アカウントに対して行われるため、1つの統合で両方に対応できます。クレジットと使用量は常にターゲットとするアカウントから差し引かれます。サブアカウントのキャンペーン、メッセージ、タグ、番号に対する料金は、**そのサブアカウントの**残高に請求されます。

### 適用されない場合

一部のエンドポイントは代理店レベルまたは自己宛てであり、`sub_account_id`を無視します：

- **サブアカウント自体の管理** — SubAccountsエンドポイント（サブアカウントの作成 / 一覧取得 / 更新）およびBYOK利用限度額エンドポイントでは、すでにURLパス内でサブアカウントを指定しています。[価格設定およびポリシーエンドポイント](#set-per-client-ai-pricing-and-policy)と[チャット監視エンドポイント](#read-a-sub-accounts-conversations)も同様のパターンに従います。
- **アカウント間でのエージェントのコピー** — `POST /v1/subaccounts/agents/copy`は両方のアカウントを自身で指定し、宛先を`targetUserId`として受け取ります。以下の[実例](#worked-example-ship-a-template-agent-into-every-new-client)を参照してください。（古い`POST /v1/subaccounts/campaigns/copy`も同様に動作しますが、[Campaigns API](../api/campaigns.md)の他の部分とともに非推奨となっています。）
- **クレジットの調整および2つのエージェンシー全体のロールアップ** — [`POST /v1/subaccounts/credits`](#grant-or-deduct-credits-directly)は代わりに`email`でサブアカウントを識別します。また、[`GET /v1/subaccounts/credit-usage`](#read-credit-usage-and-campaign-health-across-your-book)と`GET /v1/subaccounts/campaign-status`はすべてのサブアカウントを一度にレポートするため、ターゲットとなる単一のアカウントはありません。
- **エージェンシー自身のアカウント** — APIキー管理、エージェンシーの利用状況レポート、チーム管理、および[価格ティア](#manage-your-pricing-tiers-over-the-api)は、常にエージェンシーアカウントに対して実行されます。
- **インバウンドメッセージのWebhook** — 外部システムが*送信先*とするエンドポイントは、それらを構成した資格情報を持つアカウントに紐付けられているため、リダイレクトする必要はありません。

> 各エンドポイントが受け入れるパラメータの最新かつ機械可読なリストは、ダッシュボードのAPIリファレンス（**Settings → Integrations → API Key**）および `GET /v1/docs/openapi.yaml` のOpenAPI仕様で確認できます。APIの変更は頻繁に行われるため、これらを信頼できる情報源として扱ってください。

::: master-only
<figure><img src="../.gitbook/assets/v2-api-access-key-section.png" alt="APIキー設定ページ。マスクされたキーと再生成コントロールが表示されています"><figcaption><p>設定 → 統合 → APIキー — 貴社のエージェンシーキーはここにあり、完全なAPIリファレンスへのリンクも併記されています。</p></figcaption></figure>
:::

***

## 実践例：サブアカウントのInstagramとMessengerを接続する

InstagramとMessengerの接続は、ブラウザベースのフローです。APIで開始し、返された同意URLをクライアントに渡す（またはクライアントのために開く）と、クライアントがブラウザで承認を行い、接続するページを選択します。これらすべてを `sub_account_id` でサブアカウントをターゲットにして行います。

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

クライアントの `sub_account_id` をボディに含めて接続エンドポイントを呼び出します。ここでは認証情報は送信されません。プラットフォームは、クライアントがブラウザで開く必要のある同意URLと、1回限りの相関トークンを返します。

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_account_id": "abc123def456"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/channels/meta/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
// data.oauth_url -> open this in the client's browser
```

**Python**

```python
import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/connect",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
# data["oauth_url"] -> open this in the client's browser
```

**レスポンス:**

```json
{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "8sFq2yV0kQ7m4n1pZr3tWb6cXe9hJl2aD5gK7uN0oI",
  "expires_at": "2026-06-10T12:30:00.000Z"
}
```

クライアントをブラウザで `oauth_url` に誘導して承認させます。`state_token` はこの試行を関連付けるための短期間有効なシークレットです。ログには記録しないでください。この試行は `expires_at` で期限切れになります。期限が切れた場合は最初からやり直してください。

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

クライアントが承認した後、接続可能なページが表示されるまで、ステータスエンドポイントをポーリングします（同じ `sub_account_id` を今度はクエリパラメータとして使用します）。

**cURL**

```bash
curl "https://api.dmchamp.com/v1/channels/meta/status?apiKey=YOUR_API_KEY&sub_account_id=abc123def456"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.dmchamp.com/v1/channels/meta/status?sub_account_id=abc123def456",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

const data = await res.json();
// Wait until data.status === "pages_loaded", then read data.pages
```

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"sub_account_id": "abc123def456"},
)

data = res.json()
# Wait until data["status"] == "pages_loaded", then read data["pages"]
```

**レスポンス:**

```json
{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1098765432101234",
      "name": "Acme Studio",
      "category": "Hair Salon",
      "instagram_business_account": {
        "id": "17841400000000000",
        "username": "acme.studio"
      }
    }
  ],
  "selected_page": null
}
```

`status`フィールドは、`pending` → `token_received` → `pages_loaded` → `connected`の順に遷移します。ページを選択する前に`pages_loaded`になるまで待機してください。進行せずに、2つの最終エラー状態（`failed`または`expired`：クライアントが同意を拒否した、または状態トークンの約30分の有効期限が切れた）が表示される場合があります。いずれかが発生した場合は`reason`フィールドが含まれます。これらが発生した場合はポーリングを停止し、ステップ1からやり直してください。`pending`で永久に待機しないでください。ページアクセストークンが返されることはありません。

### ステップ 3 — 接続するページを選択する

ステップ 2 で取得したページ ID のいずれかを選択します。ページを選択すると、そのページの Instagram と Messenger の両方が接続されます。リクエストボディに再度 `sub_account_id` を含めてください。

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/channels/meta/select-page?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_id": "1098765432101234",
    "sub_account_id": "abc123def456"
  }'
```

**JavaScript**

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

const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.dmchamp.com/v1/channels/meta/select-page",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "page_id": "1098765432101234",
        "sub_account_id": "abc123def456",
    },
)

data = res.json()
```

**レスポンス:**

```json
{
  "success": true,
  "page_id": "1098765432101234",
  "instagram_business_account_id": "17841400000000000"
}
```

これで完了です。クライアントのサブアカウントで Instagram と Messenger が接続されました。`page_id` を提供するだけで、基盤となる認証情報はサーバー側で解決され、統合機能を経由することはありません。

***

## 実行例：サブアカウント用の番号を購入する

番号の購入も同様の手順で行います。クエリに `sub_account_id` を含めて検索し、リクエストボディに同じ値を含めて購入します。クレジットは**サブアカウントの**残高から差し引かれ、番号はサブアカウントにプロビジョニングされます。

**検索 (cURL):**

```bash
curl "https://api.dmchamp.com/v1/phone-numbers/available?apiKey=YOUR_API_KEY&country_code=US&sub_account_id=abc123def456"
```

**購入 (JavaScript):**

```javascript
const res = await fetch("https://api.dmchamp.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",
    sub_account_id: "abc123def456",
  }),
});

const data = await res.json();
```

**購入 (Python):**

```python
import requests

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

data = res.json()
```

**レスポンス:**

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

番号は`PURCHASED`状態でプロビジョニングされ、WhatsApp送信者の登録はバックグラウンドで継続されます。送信前にステータスが`ONLINE`に達するまで`GET /v1/phone-numbers/{phoneNumber}/status?sub_account_id=abc123def456`をポーリングしてください。

***

## 実例：テンプレートエージェントをすべての新規クライアントに展開する

一般的なエージェンシーのパターンは、エージェンシーアカウントにマスターエージェントを1つ保持し、すべてのクライアントの開始時に適した設定に調整しておき、プロビジョニング時に各新規サブアカウントにそのコピーを作成することです。これは3回の呼び出しで完了し、その後繰り返す必要はありません。コピーは変更されるまでその設定を保持します。

### ステップ 1 — エージェントをコピーする

`POST /v1/subaccounts/agents/copy`

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/agents/copy?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_TEMPLATE_AGENT_ID",
    "targetUserId": "abc123def456",
    "newName": "Inbound Instagram Leads",
    "copyFaqs": true
  }'
```

レスポンスには、新しいエージェントのIDが`data.agent_id`に含まれます。FAQ、ナレッジベース、メディアライブラリは引き継がれますが、ソースアカウントのWhatsAppテンプレート、接続されたソーシャル投稿、連絡先は意図的に引き継がれません。フィールドの全リストは[AI Agents API](../api/agents.md#copy-an-agent-into-a-sub-account-agencies)を参照してください。

このエンドポイントは`sub_account_id`ではなく`targetUserId`を受け取ることに注意してください。これは両方のアカウントを自身で指定します。以下の2つの呼び出しでは、通常の`sub_account_id`パラメータを使用します。

### ステップ 2 — 有効化する

コピーされたエージェントは常に一時停止状態で届くため、指示があるまでメッセージを送信することはありません。このタイミングで、クライアントに適用したいAIティアを固定することも可能です。一度設定すればその状態が維持されるため、スケジュールに従って再適用する必要はありません。

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID/active?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

curl -X PUT "https://api.dmchamp.com/v1/agents/NEW_AGENT_ID?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "anthropic_model": "max" }'
```

クライアントが後からティアを変更できないようにするには、値を再送信する代わりに、サブアカウントで[許可されたティアをロック](#set-per-client-ai-pricing-and-policy)してください。

### ステップ3 — クライアントのチャネルをキャンペーンに割り当てる

コピーにはルーティングも設定されていないため、クライアントが接続したチャネルの応答者として設定するまで、何も届きません。チャネルごとに1回呼び出します：

```bash
curl -X PUT "https://api.dmchamp.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY&sub_account_id=abc123def456" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "NEW_AGENT_ID" }'
```

ここから、そのチャネル上の未知の連絡先からの最初のメッセージは、コピーされたエージェントによって自動的に拾われます。他のチャネルや番号ごとのルーティングについては、[チャネルをエージェントに向ける](../api/entry-points.md#point-a-channel-at-an-agent)を参照してください。

> **サブアカウント作成時にクライアントのタイムゾーンを設定してください。** `POST /v1/subaccounts`で`time_zone_id`を渡します。キャンペーンの有効時間はサブアカウント自身のタイムゾーンで評価されるため、タイムゾーンを指定せずに作成されたクライアントのスケジュールはUTCで読み取られます。その結果、アシスタントが返信を許可される時間が意図せずずれてしまう可能性があります。

***

## 自分で設定するクライアントのセットアップウィザードをスキップする

`POST /v1/subaccounts`

デフォルトでは、新しいサブアカウントの所有者が初めてサインインした際に、ガイド付きのセットアップウィザードが表示されます。キャンペーンの構築やチャネルの接続をクライアントのログイン前に行う「お任せ」クライアントの場合は、アカウント作成時に `guided_onboarding: false` を渡してください。クライアントはダッシュボードに直接移動し、サイドバーから **セットアップウィザード** の項目が非表示になります。

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "guided_onboarding": false,
    "usage_limits": { "monthly_credits": 500 }
  }'
```

このフィールドを省略（または`true`を送信）すると、ウィザードはこれまで通り動作するため、既存の統合を変更する必要はありません。後でクライアントにウィザードを再度表示させるには、`PUT /v1/subaccounts/{subAccountUid}/menu-visibility`（下記）を使用して`guided_onboarding`項目を再表示してください。メニューの表示設定はウィザードにアクセスできるかどうかを制御し、`guided_onboarding`は初回サインイン時のリダイレクトのみを制御します。

***

## クライアントのタスク、日次サマリー、またはメディアライブラリをオフにする

`POST /v1/subaccounts`

これら3つの機能は、特に指定しない限りすべての新規クライアントに対して有効になります。これらは本ガイドの他のすべての機能とは動作が異なり、オプトインではなく**オプトアウト**方式です。`features`からこれらを除外するだけでは不十分です。古いインテグレーションの`features`リストにはこれらの記載がない場合があるため、「エージェンシーがオフにした」のか「このリストがオプション導入前に作成されたものか」を判別できないためです。

そのため、`feature_settings`を使用して明示的に指定してください：

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "first_name": "Alex",
    "last_name": "Client",
    "business_name": "Client Co",
    "feature_settings": {
      "tasks": false,
      "daily_summaries": false,
      "ai_media_library": true
    }
  }'
```

すべてのキーはオプションであり、省略したものは有効なままとなります。`tasks: false`を指定すると、AIはそのクライアントのタスク作成を停止し、「新しいタスクが作成されました」というメールも送信されなくなります。`daily_summaries: false`を指定すると、夜間のサマリーは生成も送信もされなくなります。

`feature_settings`は、作成時にこれら3つをオフにする唯一の方法です。`features`からこれらを除外しても、リストの他の部分がどうであれ、それ自体では何も起こりません。これは、古いインテグレーションでこれら3つが意図せず無効化されるのを防ぐための意図的な仕様です。

後からこれらを変更するには、完全な`features`リストを`PUT /v1/subaccounts/{subAccountUid}/features`に送信してください。リストに存在すれば機能がオンになり、存在しなければオフになります。

***

## クライアントをサブアカウントへ自動ログインさせる（SSO）

`POST /v1/subaccounts/{subAccountUid}/sso-link`

エージェンシーAPIキーを使用して1回呼び出すだけで、クライアントを自身のサブアカウントに直接ログインさせるためのURLが取得できます。ログイン画面やパスワード入力の手順は不要で、追加で構築する必要もありません。このURLを新しいタブで開いたり、リダイレクトさせたり、あるいは自社プロダクト内のiframeで表示したりできます。

| フィールド | 必須 | 説明 |
|---|---|---|
| `redirect` | いいえ | クライアントに表示させたいアプリ内ページ（例: `"/chats"` や `"/agents"`）。レスポンスでは `deep_link_url` として返されます。 |
| `app_base_url` | いいえ | リンクのダッシュボードホスト。デフォルトはホワイトラベルアプリのドメイン（設定がない場合はプラットフォームドメイン）です。`https` である必要があります。 |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/sso-link" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect": "/chats" }'
```

**レスポンス**

```json
{
  "success": true,
  "url": "https://app.yourdomain.com/auth?redirect=%2Fchats#token=eyJhbGciOi…",
  "deep_link_url": "https://app.yourdomain.com/chats",
  "expires_at": "2026-07-22T15:04:05.000Z",
  "sub_account_uid": "SUB_ACCOUNT_UID"
}
```

効果的な利用方法:

- **ワンホップ。** `url`を開くとクライアントがサインインし、ダッシュボードの`redirect`ページに直接移動します。ログイン画面や中間ページは表示されません。`deep_link_url`は同じ宛先を指定するもので、ログイン後にフレームを明示的にナビゲートすることを好むインテグレーター向けです。セッションが存在すれば、そのブラウザコンテキスト内でどのダッシュボードパスも機能します。
- **オンデマンドで発行し、即座に開く。** リンクにはログイン資格情報が含まれており、約1時間で期限切れになります。クライアントがクリックした瞬間にサーバー側でリクエストし、保存やメール送信は行わないでください。
- ログイントークンはURLフラグメント（`#…`）で送信されます。これはブラウザがサーバーに送信することのない部分であり、消費された瞬間にアドレスバーから削除されます。
- **自社のサブアカウントのみ。** エンドポイントは、貴社のエージェンシーが所有していないアカウントへのアクセスを拒否します。
- 期限切れのリンクは、再試行パスを含む明確なエラーを表示します。その際は新しいリンクを発行してください。

***

## サブアカウントのナビゲーション項目を非表示にする

`PUT /v1/subaccounts/{subAccountUid}/menu-visibility`

サブアカウントに表示されるサイドバーや設定項目を制御します。ダッシュボードを埋め込む際に、自社プロダクトでカバーしていない機能のみを表示させたい場合に便利です。リストに含まれていない項目はすべて表示されたままになります。`null` を `menuVisibility` の値全体として送信すると、すべて表示状態にリセットされます。項目を非表示にするとメニューエントリも隠れます。厳密なアクセス制限を行うには、サブアカウントに付与する機能と組み合わせて使用してください。

**cURL**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/menu-visibility" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }'
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "menuVisibility": {
      "side_nav": { "Dashboard": false, "Campaigns": false, "Automations": false },
      "settings_nav": { "team": false }
    }
  }
}
```

`side_nav` は、サイドバーの項目名と一致する以下の13個のキーを受け入れます：`Dashboard`、`DailySummaries`、`Chats`、`Contacts`、`Deals`、`Tasks`、`Automations`、`Campaigns`、`Appointments`、`Settings`、`Help`、`CreditsCounter`（サイドバーに表示されるクレジット残高）、および `guided_onboarding`（セットアップウィザード）。さらに3つのキー（`AiInsights`、`Sub Accounts`、`Agency Reselling`）も受け入れられますが、これらは何も機能しません。これらは廃止された旧ダッシュボードにのみ適用されていたものであり、設定してもサブアカウントには影響しません。キーが欠落している場合は表示されることを意味します。サブアカウントに自身でサインインした際には、非表示の項目が一時的に表示されるため、いつでも設定を元に戻すことができます。

メニューからページを非表示にしても、アクセス権が付与されるわけではありません。`Automations`には、サブアカウントで`automations`機能が許可されている必要があります。この機能なしでキーを`true`に設定しても、ページは表示されません。`Tasks`と`DailySummaries`は逆の動作をします。これらは、オフにしない限りすべてのクライアントで有効になります（[クライアントのタスク、日次サマリー、またはメディアライブラリをオフにする](#turn-tasks-daily-summaries-or-the-media-library-off-for-a-client)を参照してください）。

***

## クライアントが接続できるチャネルタイプを選択する

`PUT /v1/subaccounts/{subAccountUid}/features`

プラン階層に表示される**チャネルタイプ**のスイッチは通常の機能IDであるため、ダッシュボードからではなくAPIを使用してクライアントごとに設定できます。これはURL自体にサブアカウント名が含まれるエンドポイントの1つであるため、`sub_account_id`は必要ありません。

| 機能ID | チャネル |
|---|---|
| `channel_chat_widget` | ウェブサイトチャットウィジェット |
| `channel_whatsapp_api` | WhatsApp Business API |
| `channel_whatsapp_web` | WhatsApp Web (QRコード連携番号) |
| `channel_instagram` | Instagram |
| `channel_messenger` | Facebook Messenger |
| `channel_telegram` | Telegram |
| `channel_line` | LINE |
| `channel_viber` | Viber |
| `channel_email` | メールボックス |
| `channel_sms` | SMS |
| `channel_imessage` | iMessage |

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/features" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      "channels_3",
      "channel_chat_widget",
      "channel_whatsapp_web",
      "channel_instagram",
      "image_understanding",
      "contact_tagging",
      "incoming_campaigns",
      "webhooks"
    ]
  }'
```

正しく設定するための3つのポイント：

- **この呼び出しは機能リスト全体を置き換えます。** 変更するものだけでなく、クライアントが保持すべきすべての機能を送信してください。同じIDは、アカウント作成時の`POST /v1/subaccounts`における`features`としても機能します。
- **チャネルタイプとチャネル数は別々の制限であり、両方が適用されます。** `channels_1` / `channels_3` / `channels_unlimited` は*接続数*を制御し、`channel_*`のIDは*どのタイプか*を制御します。上記の例は「最大3接続まで、かつチャットウィジェット、WhatsApp Web、またはInstagramのみ」を意味します。
- **`channel_*` IDを一切送信しない場合、チャネル制限は適用されません。** これが元の動作であるため、この機能がリリースされた際も既存のクライアントには影響がありませんでした。1つ以上のIDを送信すると、それ以外のすべてはクライアントの「チャネル」ページで「接続」ボタンの代わりにアップグレードの案内が表示され、ロックされた状態になります。クライアントがすでに接続済みのチャネルは引き続き機能します。

> **プラン階層**でチャネルリストを設定し、そのプランを購入したすべてのクライアントに継承させる操作は、ダッシュボードの代理店プラン設定から行います。このエンドポイントは、特定のサブアカウントに対して設定を行うものです。

***

## クライアントのチームメンバー数に正確な上限を設定する

`PUT /v1/subaccounts/{subAccountUid}/limits`

`team_seats_*` 機能では、プリセットされた段階（3 / 5 / 10 / 無制限）のみが提供されます。クライアントに「2」「7」「15」など、**正確な**チームシート数を割り当てるには、代わりに `usage_limits.team_seats_limit` を設定してください。これはプリセットよりも優先され、プラットフォームは招待、直接追加、招待承諾のすべてにおいてこの制限を強制します。上限に達すると、それ以降の招待はサーバー側で拒否されます。

- 正の整数は正確な上限数となります。
- `0` はチームメンバーが**含まれない**ことを意味し、クライアントは誰も招待できません。
- `-1` は無制限を意味します。
- `null` はカスタム制限を解除し、機能リストにある `team_seats_*` のプリセット設定に戻します。

制限を引き下げても既存のチームメンバーが削除されることはありません。新しいメンバーの追加のみが停止されます。

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/limits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usageLimits": { "team_seats_limit": 7 }
  }'
```

作成時にも設定できます。`POST /v1/subaccounts` は `usage_limits.team_seats_limit` と同じセマンティクスを受け入れます。`GET /v1/subaccounts?email=...` でサブアカウントを取得し、`usage_limits.team_seats_limit` を確認することで現在の値を読み取れます（存在しない場合や `null` の場合は、プリセットの設定が適用されます）。同じエンドポイントで `credits`、`monthly_credits`、`roll_over_to_next_month`、`rollover_cap_months`、`rollover_expiry_days`、`byok_monthly_limit_usd` も更新できます。変更したいキーのみを送信してください。

**SaaSプランのシート制限との相互作用について。** SaaSプランには独自のシート許容量を設定できます（プランエディターで設定します。詳細は[プランのチームシート](agency-accounts.md#step-3--set-up-pricing-tiers)を参照してください）。これはクライアントがサブスクライブした際に自動的に適用されます。このエンドポイントを通じて設定した制限は、**手動**付与としてカウントされます。プランを購入すると、そのプラン独自のシート許容量に置き換わります（その購入は明示的なプランの選択であるため）。しかし、無人で行われる月次の**更新によって手動制限が上書きされることはありません**。そのため、クライアントに付与した一度限りの例外設定は、請求サイクルをまたいでも維持されます。`null`を使用して手動制限を解除すると、次回の更新時にプランの設定が再び適用されるようになります。

**クライアントが更新の間に持ち越せる量を制限します。** `roll_over_to_next_month` の隣にさらに2つの `usage_limits` キーがあります。どちらも作成時に `POST /v1/subaccounts` で受け入れられ、`null` を指定するといずれもクリアされます。

| キー | 機能 |
|---|---|
| `rollover_cap_months` | クライアントが保持できる許容量（月数）。0から120の数値で、小数も指定可能です（`0.5` は0.5ヶ月分）。更新のたびに、未使用の残高は、新しいクレジットが追加される前に、その更新で付与される許容量の最大この倍数まで切り詰められます。`0` は持ち越しを許可しません。 |
| `rollover_expiry_days` | 1から3650までの整数（日数）。この期間未使用のままのクレジットは、その期間を超えた後の最初の更新時に削除されます。消費は常に最も古いクレジットから行われるため、毎月許容量を使い切るクライアントがクレジットを失うことはありません。 |

設定しない場合、いずれもクライアントのプラン設定が適用されます。ここで値を送信すると、プランの設定よりも優先されます。これらは定期クレジット（月間許容量およびプランクレジット）のみに適用されます。トップアップ、自動リチャージ、および単発の追加分には、上限や有効期限は適用されません。各切り詰め処理は、クライアントのクレジット履歴に **Rollover Cap Credit Adjustment**（繰越上限によるクレジット調整）または **Expired Credits Credit Adjustment**（期限切れクレジットによるクレジット調整）として記録され、使用量としてはカウントされません。プランレベルでの同等の設定は、価格ティア上の `rollover_cap_months` および `rollover_expiry_days` です。詳細は [ティアのフィールド](#the-fields-on-a-tier) および [繰越上限の設定](sub-accounts.md#capping-what-rolls-over) を参照してください。

***

## クライアントごとのAI価格設定とポリシーを設定する

`PUT /v1/subaccounts/{subAccountUid}/max-tier` · `/ai-tiers` · `/max-rate` · `/action-pricing` · `/insider-rate` · `/locked-bot-fields` · `/notifications` · `/zero-credit-reply`

上記の `/limits`、`/features`、`/menu-visibility` に加え、クライアントごとに設定可能なスイッチがさらに8つあります。それぞれURL内でサブアカウントのuidを使用し（`sub_account_id` ボディ/クエリパラメータは不要。ターゲットはパス内で指定済み）、同じスコープ（あなたのエージェンシーキー、およびサブアカウントがあなたのエージェンシーに属していること）で適用されます。

**クライアントが使用できるAIモデル**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-tier" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

`{ "enabled": boolean }` は、クライアントをMax AIティア（プラットフォームのリスト価格でのインフラストラクチャ）にオプトイン（またはオプトアウト）させます。BYOKクライアントに対してこれを有効にすると、AIコストが「自身のキーで無料」から「クレジットプールから引き落とし」に変更されるため、エージェンシー全体のデフォルトではなく、クライアントごとに慎重に決定する必要があります。

クライアントのキャンペーンやエージェントが選択できるティアを（単にMaxを制限するだけでなく）制限するには、`ai-tiers` を使用します。

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/ai-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_ai_tiers": ["standard", "economy"] }'
```

`allowed_ai_tiers` は `standard`、`economy`、`max`、`mini` から抽出された配列であり、クライアントの許可リストを置き換えます。`null`（または `[]`）を送信すると制限が解除され、任意のティアを選択できるようになります。サブアカウントが独自のAIティアを選択すると **あなた** のクレジットプールから消費されるため、これはリセラークライアントがあなたの請求額をどれだけ増やすかを決定するための重要な手段となります。

**クライアントのクレジットが不足している間の保留返信**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/zero-credit-reply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "message": "Thanks for your message, we will get back to you shortly." }'
```

クライアントの残高（またはあなたのプール）が空になると、AIは応答できず、連絡先には何も届きません。`enabled: true` を設定すると、停止中に連絡してきたすべての連絡先に `message` が1回だけ送信されます（最大500文字、すべてのチャネルでそのまま送信）。クレジットが回復すると、AIはその会話に対して実際に応答します。`enabled: false` は保存されたテキストを保持します。`enabled: false` に `message` を指定せずに送信すると、設定が削除されます。これはサブアカウントの編集モーダルにある **Holding reply when out of credits**（クレジット不足時の保留返信）と同じスイッチです。[クライアントのクレジットが不足している間の保留返信](sub-accounts.md#a-holding-reply-while-a-client-is-out-of-credits) を参照してください。

**クライアントがAIアクションごとに支払う料金とWhatsApp手数料のマークアップ**

クライアント向けの料金を設定するには、最もシンプルな方法から最も詳細な方法まで、2つの方法があります。

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/max-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rate": 0.35 }'
```

`rate` は、MaxモデルのAIアクションごとにサブアカウント自身の残高から消費されるクレジット価格であり、プールが実際に支払う金額に上乗せするクライアント向けのマークアップです。`null` はオーバーライドを解除し、プラットフォームのリスト価格に戻します。料金は、Maxアクションが自身のプールにかかるコスト以上（クライアントにコストを下回る価格を設定することはできません）で、かつ10クレジット以下である必要があります。この範囲外のリクエストは、エラーメッセージ内に計算された下限値とともに拒否されます。

一律のMax料金ではなく、アクションタイプごとの価格設定を行うには、`action-pricing` を使用します。

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/action-pricing" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actionPricing": {
      "AI_MESSAGE": 0.6,
      "CHAT_SUMMARY": 0.15,
      "wa_carrier_multiplier": null
    }
  }'
```

`actionPricing` はクライアントの既存のマップに対するマージ（結合）です。指定しなかったキーはそのまま残り、`null` はそのキーをデフォルトに戻します。認識されるキーは以下の通りです。

| キー | 価格 |
|---|---|
| `AI_MESSAGE` | AIの返信 |
| `AI_TOOL_USE` | AIツール呼び出し |
| `EVALUATION_CALL` | チャット評価パス |
| `INTERRUPTION_HANDLING` | 返信途中の中断処理 |
| `CONTACT_TAG` | AIが割り当てた連絡先タグ |
| `CHAT_SUMMARY` | チャットの要約 |
| `wa_carrier_multiplier` | クライアントが支払うAI以外のWhatsApp手数料（月額番号レンタル料、管理レーン配信手数料、Meta/Twilioテンプレートのパススルーコスト）すべてに適用されるマークアップ乗数 |

アクションごとのレートは0より大きく10以下の数値である必要があります。`wa_carrier_multiplier`は少なくとも`1`（原価を下回る割引は不可）であり、最大10までとなります。認識されないキーや範囲外の値を送信するとリクエスト全体が拒否され、問題のあるすべてのキーが指摘されるため、タイプミスによって実際には適用されない価格が保存されてしまうことはありません。

[Champions Circle](https://skool.com/dm-champions)メンバーの場合、`insider-rate`は20%オフのMax/Lead Finderレートをエージェンシー全体に適用するのではなく、1つのクライアントにのみ適用します：

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/insider-rate" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

これを有効にするには、ご自身のエージェンシーアカウントが実際にCircleメンバーシップを保持している必要があります。無効にする場合はその必要がないため、メンバーシップが失効した状態でも、いつでもクライアントの設定を元に戻すことができます。

**クライアントのプレイブックのセクションをロックする**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/locked-bot-fields" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locked_bot_fields": ["instructions", "rules"] }'
```

`locked_bot_fields`は`instructions`、`goal`、`rules`、`personality`、`conclude_unless`から構成される配列であり、クライアントのロックリストを置き換えます。サブアカウント自身が（直接、またはAPIキーを使用して）ロックされたセクションを変更しようとすると、サーバー側で拒否されます。一方、あなた（`sub_account_id`経由）およびクライアント自身のダッシュボード管理者ビューからは、引き続きすべてを編集できます。すべてをロック解除するには`null`（または`[]`）を送信してください。プレイブックを所有し、その結果に対して評価を受ける「Done-for-you（代行型）」のクライアントに役立ちます。

**クライアントに代わって通知設定を行う**

```bash
curl -X PUT "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/notifications" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "settings": {
        "credit_alerts": { "enabled": true, "channels": ["email", "in_app"] },
        "new_contacts": { "enabled": false }
      }
    }
  }'
```

`notifications`はクライアントの通知設定全体を置き換えます（キーごとのマージではありません。サブアカウント自身の「設定」ページでの保存方法に合わせて、保持したいすべてのカテゴリを送信してください）。`settings`配下の各カテゴリは、`enabled`（ブール値）と、`email`、`in_app`、`webhook`から最大3つの`channels`を受け付けます。プラットフォームのデフォルトにリセットするには`null`を送信してください。

7つのエンドポイントはすべて `{ "success": true, "data": { "subAccountUid": "...", ...the field(s) you set... } }` を返し、変更前後の値が監査ログに記録されます。一般的なエラー: アカウントが Agency/Dev ではない、またはサブアカウントが管理対象外の場合は `403`、エージェンシーのサブアカウントではない、または値が範囲外の場合は `400` が発生します。

***

## サブスクリプションを一時停止したクライアントを一時停止する

`POST /v1/subaccounts/{subAccountUid}/pause` · `POST /v1/subaccounts/{subAccountUid}/unpause`

クライアントがサブスクリプションを一時停止した場合、アカウントを削除するのではなく、一時停止してください。送信されるすべてのメッセージ（アウトバウンドメッセージ、ブロードキャスト、すべてのチャネルでのAI返信など）が直ちに停止されます。また、クライアントがサインインすると、アプリの代わりに全画面の**アカウントが一時停止されました**というロック画面（オプションのメッセージを表示可能）が表示されます。エージェント、キャンペーン、接続済みチャネル、連絡先、チャット履歴などはすべてそのまま保持されるため、一時停止を解除すれば、設定をやり直すことなく、中断したところから正確に再開できます。

| フィールド | 必須 | 説明 |
|---|---|---|
| `message` | いいえ | クライアントのロック画面に表示されます。省略するとデフォルトの文言が表示されます。 |
| `reason` | いいえ | 一時停止とともに保存され、監査ログにも記録される代理店内部用のメモです。クライアントには表示されません。 |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/pause" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your account is on hold — contact us to reactivate it.", "reason": "Subscription suspended per client email" }'
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "subAccountUid": "SUB_ACCOUNT_UID",
    "paused": true,
    "level": "hard_blocked"
  }
}
```

クライアントが戻ってきたら、`POST /v1/subaccounts/SUB_ACCOUNT_UID/unpause`（本文なし）を実行してロックを解除します。送信とAI返信が直ちに再開されます。

知っておくべきこと:

- **ダッシュボードの「ハードブロック」トグルと同じ状態です** ([サブアカウントのブロック/一時停止](sub-accounts.md#blocking-pausing-a-sub-account))。API経由で一時停止されたクライアントはダッシュボード上でブロック中として表示され、その逆も同様です。また、どちら側から行われたブロックであっても、一時停止を解除すればブロックは解除されます。現在の状態は、`GET /v1/subaccounts`（`"none"`、`"soft_blocked"`、または`"hard_blocked"`の`level`）の`agency_block`フィールドから読み取ることができます。
- **どちらの呼び出しもべき等です。** すでに一時停止されているクライアントを一時停止しても、メッセージ、理由、タイムスタンプが更新されるだけです。アクティブなクライアントの停止を解除しても何も変更されません。
- **クライアントに自動的にメールは送信されません。** 多くの代理店がホワイトラベルを利用しているため、クライアントへの通知は代理店側で行う必要があります。
- **お客様自身のDM Champの請求には影響しません。** クライアントの一時停止は、お客様とクライアント間の関係にのみ影響します。
- **AIアシスタントもこれを行うことができます。** [MCPサーバー](../integrations/connect-ai-clients.md)は、これらのエンドポイントを`pause_subaccount`および`unpause_subaccount`ツールとして公開しています。

***

## クレジットの直接付与または控除

`POST /v1/subaccounts/credits`

サブアカウントの残高に対して正確な量のクレジットを追加または削除します。これはダッシュボードの手動クレジット調整のAPI版です。[`PUT /v1/subaccounts/{subAccountUid}/limits`](#set-an-exact-team-member-limit-for-a-client) にある定期的な `monthly_credits`、`roll_over_to_next_month`、`rollover_cap_months`、`rollover_expiry_days` の設定とは異なる、単発の残高変更です。

このページで、サブアカウントを `sub_account_id` ではなく **メールアドレス** で識別する唯一のエンドポイントです。

| フィールド | 必須 | 説明 |
|---|---|---|
| `email` | はい | エージェンシー配下に存在するサブアカウントのメールアドレス。 |
| `amount` | はい | 0以外のクレジット数。正の数は追加、負の数は控除となります。 |
| `description` | いいえ | クライアントのクレジット履歴で調整内容として表示されます。デフォルトは「Adjusted by agency via API（エージェンシーがAPI経由で調整）」という汎用的な行です。 |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/credits" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "client@example.com", "amount": 500, "description": "Q3 bonus credits" }'
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "email": "client@example.com",
    "previous_balance": 1200,
    "adjustment": 500,
    "new_balance": 1700
  }
}
```

残高がゼロを下回るような負の `amount` は `400` で拒否され、利用可能な残高と差し引こうとした額が通知されます。クライアントが独自のStripe請求（リセラーモード）を利用している場合、追加された金額はクライアントが購入したクレジットとしてカウントされるため、実際のトップアップと同様に次回の月次リセット後も保持されます。標準の割り当てクライアントの場合は、定期的な許容量の一部として扱われます。いずれの場合も単発の追加分であるため、アカウント（またはそのプラン）に設定された繰越上限や有効期限によって切り詰められることはありません。それらの制限は定期的な許容量とプランクレジットのみに適用されます。

***

## サブアカウントの会話を読み取る

`GET /v1/subaccounts/{subAccountUid}/chats` · `GET /v1/subaccounts/{subAccountUid}/chats/{contactId}/messages`

クライアントのアカウントにサインインすることなく、会話の監視やサポート用のビューを構築できます。まず、最新メッセージのプレビュー付きで連絡先を一覧表示し、次に特定の連絡先のメッセージ履歴全体を読み取ります。

**連絡先を一覧表示**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats?apiKey=YOUR_AGENCY_API_KEY&pageSize=25"
```

| クエリパラメータ | 必須 | 説明 |
|---|---|---|
| `pageSize` | いいえ | 1ページあたりの連絡先数。デフォルトは25、最大は50です。 |
| `lastActivityAt` | いいえ | ページネーションカーソル — 前のページの `lastActivityAt` を渡して継続します。 |
| `searchQuery` | いいえ | 連絡先名または電話番号でフィルタリングします。 |

**レスポンス**

```json
{
  "success": true,
  "data": {
    "contacts": [
      {
        "contactId": "contact456",
        "firstName": "Jamie",
        "lastName": "Lee",
        "phoneNumber": "+14155551234",
        "email": "jamie@example.com",
        "channel": "whatsapp",
        "lastActivityAt": "2026-08-30T14:22:00.000Z",
        "lastMessage": { "body": "Thanks, that fixed it!", "direction": "inbound", "timestamp": "2026-08-30T14:22:00.000Z" },
        "isBotActive": true,
        "markChatClosed": false
      }
    ],
    "subAccountName": "Client Co",
    "subAccountEmail": "client@example.com",
    "hasMore": true,
    "lastActivityAt": "2026-08-30T14:22:00.000Z"
  }
}
```

連絡先は、アクティビティの新しい順に並べ替えられます。`hasMore` が `true` である間は、`lastActivityAt` を使用してページングを続けてください。

**特定の連絡先のメッセージを読み取る**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/SUB_ACCOUNT_UID/chats/contact456/messages?apiKey=YOUR_AGENCY_API_KEY&pageSize=30"
```

| クエリパラメータ | 必須 | 説明 |
|---|---|---|
| `pageSize` | いいえ | 1ページあたりのメッセージ数。デフォルトは30、最大100です。 |
| `beforeTimestamp` | いいえ | ページネーションカーソル — このISOタイムスタンプより古いメッセージを取得します。 |

**レスポンス**

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "messageId": "msg789",
        "body": "Thanks, that fixed it!",
        "direction": "inbound",
        "timestamp": "2026-08-30T14:22:00.000Z",
        "status": "received",
        "channel": "whatsapp",
        "botReply": false,
        "mediaUrl": null,
        "mediaContentType": null,
        "name": "Jamie Lee",
        "role": null
      }
    ],
    "contactInfo": { "firstName": "Jamie", "lastName": "Lee", "phoneNumber": "+14155551234", "channel": "whatsapp" },
    "hasMore": false,
    "oldestTimestamp": "2026-08-30T14:22:00.000Z"
  }
}
```

メッセージは新しい順に返されます。`beforeTimestamp` を使用して履歴を遡ってページングしてください。

***

## 管理下にあるすべてのクレジット使用状況とキャンペーンの健全性を読み取る

`GET /v1/subaccounts/credit-usage` · `GET /v1/subaccounts/campaign-status`

管理しているすべてのサブアカウントを対象とした2つのダッシュボード形式の集計機能です。クライアントごとに個別にクリックして確認するのではなく、独自の代理店用レポートを構築するために使用できます。

**クレジット使用状況**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/credit-usage?apiKey=YOUR_AGENCY_API_KEY&from=2026-08-01&to=2026-08-31"
```

| クエリパラメータ | 必須 | 説明 |
|---|---|---|
| `from` / `to` | はい | ISO日付範囲。 |
| `subAccountId` | いいえ | 省略すると代理店全体の概要がサブアカウントごとに1行で表示されます。指定すると詳細モードに切り替わり、そのサブアカウントの概要と、生のページネーションされた使用記録が表示されます。 |
| `limitCount` | いいえ | 詳細モードのみ。デフォルトは500、最大2000です。 |
| `startAfterTimestamp` | いいえ | 詳細モードのみ — ページネーションカーソル。 |

```json
{
  "success": true,
  "data": {
    "subAccounts": [
      {
        "subAccountId": "abc123def456",
        "subAccountName": "Client Co",
        "subAccountEmail": "client@example.com",
        "totalCreditsUsed": 842,
        "totalCostUsd": 3.15,
        "byReason": { "AI reply": 620, "Chat summary": 80 },
        "topCampaigns": [{ "campaignName": "Inbound Leads", "creditsUsed": 500 }]
      }
    ],
    "totals": { "totalCreditsUsed": 842, "totalCostUsd": 3.15, "totalRecords": 214 },
    "dateRange": { "from": "2026-08-01", "to": "2026-08-31" },
    "hasMore": false,
    "lastTimestamp": null
  }
}
```

`subAccountId` を渡すと、同じレスポンスに `records` も含まれます。これには `amount`、`reason`、`campaignName`、`contactName`、`timestamp` を含む個別の課金情報が含まれます。クライアントがあなたのクレジットではなく独自のBYOKキーで支払いを行っている場合、コスト/トークンの数値は非表示になります（`costsRedacted: true`）。これはプラットフォームのコストテレメトリであり、再販業者向けのビューに表示するものではありません。

**キャンペーンステータス**

```bash
curl "https://api.dmchamp.com/v1/subaccounts/campaign-status?apiKey=YOUR_AGENCY_API_KEY&pageSize=20"
```

| クエリパラメータ | 必須 | 説明 |
|---|---|---|
| `pageSize` | いいえ | 1ページあたりのサブアカウント数。デフォルトは10、最大50です。 |
| `lastDocumentId` | いいえ | ページネーションカーソル。 |
| `searchQuery` | いいえ | サブアカウント名またはメールアドレスによるフィルタリング。 |

```json
{
  "success": true,
  "data": {
    "totalSubAccounts": 34,
    "subAccountsWithIssues": 3,
    "totalLiveCampaigns": 51,
    "totalPausedCampaigns": 6,
    "subAccounts": [
      {
        "userId": "abc123def456",
        "email": "client@example.com",
        "displayName": "Jamie Lee",
        "businessName": "Client Co",
        "totalCampaigns": 2,
        "liveCampaigns": 1,
        "pausedCampaigns": 1,
        "hasIssues": true,
        "issueDetails": ["1 campaign paused"],
        "lastCampaignActivity": "2026-08-29T09:00:00.000Z"
      }
    ],
    "hasMore": true,
    "lastDocumentId": "abc123def456",
    "pageSize": 20
  }
}
```

`hasIssues` / `issueDetails` フラグは、一時停止中のキャンペーンや、ルーティングされたチャネルがないキャンペーンなど、確認が必要なサブアカウントを示します。これを使用して、各クライアントを個別に開いて停滞しているキャンペーンを確認するのではなく、全顧客にわたるヘルスチェックダッシュボードを構築してください。

> 全クライアントの時系列メッセージングおよびクレジットアクティビティ（時点のスナップショットではなく、チャート作成に適した時系列データ）については、Analytics APIガイドの `GET /analytics/agency-rollup` を参照してください。

***

## セットアップ済みのクライアントアカウントを配布する

`PUT /v1/snapshots/default` · `POST /v1/snapshots/{snapshotId}/apply`

[スナップショット](snapshots.md)は再利用可能なテンプレートです。これは、あなたのアカウントから取得した1つ以上のAIエージェントと、そのナレッジベース、ツール、メディアで構成されます。2つのエンドポイントを使用して、プロビジョニングフローに組み込むことができます。

**自動 — すべての新規クライアントに適用されます。** スナップショットを一度デフォルトとしてスター登録すると、それ以降に作成されるすべてのアカウントにインストールされた状態で提供されます。これには、`POST /v1/subaccounts`経由で作成されたアカウント、ダッシュボードで作成したアカウント、およびクライアントがチェックアウトリンクから支払った際に自動的に作成されるアカウントが含まれます。

まず、スナップショットのIDを確認します：

```bash
curl "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

次に、それをデフォルトとして設定します：

```bash
curl -X PUT "https://api.dmchamp.com/v1/snapshots/default" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "snapshot_id": "SNAPSHOT_ID" }'
```

統合はこれで完了です。オフにするには`{"snapshot_id": null}`を送信してください。ダッシュボードの**スナップショット**ページでスターをクリックすることでも同様の操作が可能です。

現在スターが付いているものを読み取るには（例えば、プロビジョニングスクリプトが設定を決定する前など）、`GET /v1/snapshots/default` は `{ "success": true, "data": { "default_snapshot_id": "SNAPSHOT_ID" } }` を返します。何もスターが付いていない場合は `null` を返します。`GET /v1/snapshots`（上記のIDを見つけるために使用）は、同じ `default_snapshot_id` を完全な `snapshots` 配列とともに返すため、ほとんどの統合ではこの1回の呼び出しで十分です。完全なスナップショットオブジェクトのフィールドについては、[スナップショット](snapshots.md)ガイドを参照してください。

**オンデマンド — 特定のアカウントにインストールします。** 既存のクライアントのオンボーディングや、後からクライアントに別のテンプレートを提供する場合に便利です。

```bash
curl -X POST "https://api.dmchamp.com/v1/snapshots/SNAPSHOT_ID/apply" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sub_account_id": "SUB_ACCOUNT_UID" }'
```

`sub_account_id`を省略すると、代わりにあなた自身の代理店アカウントにインストールされます。`/subaccounts`エンドポイントと同様に、これらは環境変数`sub_account_id`ではなく、パスまたはボディでターゲットアカウントを指定します。

構築前に知っておくべきこと：

- **インストールされたエージェントは一時停止状態で開始されます。** クライアントのチャネルを先に接続してから、エージェントを有効にしてください。これは自動パスとオンデマンドパスの両方に当てはまります。
- **プロビジョニングがスナップショットによって失敗することはありません。** インストールが完了できない場合でも、クライアントアカウントは作成され使用可能な状態になります。単に空の状態で作成されるため、後からスナップショットを適用できます。
- **チャネル、カレンダー、OAuth接続はコピーされません。** 各アカウントで個別に接続する必要があります。プレーンなAPIキーを使用するツールはすぐに機能し続けます。
- **2回適用すると2つ目のコピーが作成されます。** 何も上書きされません。

***

## API経由でテンプレート自体を構築する

`POST /v1/snapshots` · API経由のエージェント、カスタム関数、メディア

上記のセクションでは、ダッシュボードで作成されたスナップショットを配布する方法を説明しました。作成側の機能も公開されているため、「マスター設定を一度組み立て、キャプチャし、すべてのクライアントに配布する」という一連のループをコードから実行できます。

プロビジョニングスクリプトで使用する順序で、各要素を説明します。

1. **カスタム関数の作成。** `POST /v1/custom-functions` で作成し、`GET /v1/custom-functions` で既存の関数を一覧表示します。`GET`、`PUT`、`DELETE` を `/v1/custom-functions/{customFunctionId}` に対して使用することで、読み取り、更新、削除が可能です。`POST /v1/custom-functions/test` は保存前に定義のドライランを行います。
2. **エージェントの作成と構成。** `POST /v1/agents` で作成、`PUT /v1/agents/{agentId}` で更新します。`PATCH /v1/agents/{agentId}/active` に `{ "active": false }` を指定すると作業中に一時停止状態を維持でき（`true` を指定すると有効になります）、`GET /v1/agents` で一覧表示します。
3. **エージェントに機能を追加。** `POST /v1/agents/{agentId}/custom-functions` に `{ "custom_function_id": "..." }` を指定して関数をエージェントにアタッチし、対応する `DELETE /v1/agents/{agentId}/custom-functions/{customFunctionId}` でデタッチします。
4. **メディアライブラリの構築。** `POST /v1/agents/{agentId}/media-library` でアイテムをアップロードし（`base64Data`、`mimeType`、`title`、`description` を含むJSON）、`GET` でエージェントのアイテムを一覧表示します。`PATCH`/`DELETE` を `/{itemId}` に対して使用して更新や削除を行います。
5. **スナップショットとしてキャプチャ。**

```bash
curl -X POST "https://api.dmchamp.com/v1/snapshots" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Master setup v1",
    "agent_ids": ["AGENT_ID"],
    "include_knowledge": true,
    "include_tools": true,
    "include_media": true
  }'
```

その後は前述のセクションと同様です。デフォルトとしてスターを付けることで新規クライアント作成時に自動適用されるようにするか、必要に応じて適用します。管理機能も用意されており、`PATCH /v1/snapshots/{snapshotId}` に `{ "name": "..." }` を指定して名前を変更、`DELETE /v1/snapshots/{snapshotId}` で削除（デフォルトの場合はスターを解除）、`GET /v1/snapshots/apply-targets` でインストール可能なすべてのアカウントを一覧表示できます。

エージェント、カスタム関数、メディアの各エンドポイントはすべて `sub_account_id` を受け入れるため、同じ呼び出しを使用して特定のクライアントアカウント内のエージェントを直接管理することも可能です。スナップショットの呼び出しは常にエージェンシーアカウントに対して行われ、テンプレートは管理側に保持されます。これらすべての完全なリクエストおよびレスポンススキーマについては、[APIリファレンス](../api/reference.md)を参照してください。

***

## API経由での料金プランの管理

`GET /v1/agency/pricing-tiers` · `POST /v1/agency/pricing-tiers` · `PATCH /v1/agency/pricing-tiers/{tierIndex}` · `DELETE /v1/agency/pricing-tiers/{tierIndex}`

**SaaSモード → 料金プラン**で販売するプランは、コードから読み取りや変更が可能です。そのため、貴社の管理パネルやプロビジョニングスクリプトから、ダッシュボードを開くことなくプランの追加、価格の調整、チェックアウトリンクの発行を行うことができます。このページの他のすべての呼び出しと同様に、エージェンシーAPIキーで認証を行ってください。これらのエンドポイントはエージェンシーレベルであるため、`sub_account_id`は必要ありません。すべての書き込み操作は、ダッシュボードでの保存時と同じ検証およびStripeの製品・価格同期を実行するため、ここで作成されたプランは手動で設定したものと区別がつきません。

### プランの一覧取得

```bash
curl "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "tiers": [
      {
        "tierIndex": 0,
        "credits": 1000,
        "price_cents": 2900,
        "currency": "usd",
        "label": "Starter",
        "billing_interval": "month",
        "trial_days": 14,
        "trial_credits": 250,
        "trial_card_required": false,
        "trial_hard_expiry": true,
        "stripe_price_id": "price_1PxAbC…",
        "stripe_product_id": "prod_QxAbC…",
        "checkout_url": "https://app.yourdomain.com/v1/checkout?id=YOUR_AGENCY_UID&tierIndex=0"
      }
    ],
    "count": 1,
    "max_tiers": 20
  }
}
```

各プランには、プラン一覧内での位置を示す**`tierIndex`**（他の3つの呼び出しで指定する値）と、共有可能な**`checkout_url`**が含まれます。これは**支払い**タブで提供されるリンクと同じもので、そのプランが販売されている[ホワイトラベルドメイン](white-labeling.md)を指しています。

### プランの追加

リクエストボディは1つのプランオブジェクトであり、リストの末尾に追加されます。

```bash
curl -X POST "https://api.dmchamp.com/v1/agency/pricing-tiers" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Starter",
    "credits": 1000,
    "price_cents": 2900,
    "currency": "usd",
    "billing_interval": "month",
    "trial_days": 14,
    "trial_credits": 250,
    "trial_card_required": false,
    "trial_hard_expiry": true,
    "features": ["channels_3", "channel_whatsapp_web", "webhooks"]
  }'
```

レスポンスには、作成されたプランが含まれます。これには、プランが配置された`tierIndex`と、その`checkout_url`が含まれます。

### プランの編集

変更したいフィールドのみを送信してください。プランの他の設定はそのまま維持されます。

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agency/pricing-tiers/0" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_cents": 3900, "trial_hard_expiry": true }'
```

APIが認識しないフィールドは無視されるのではなく拒否され、エラーメッセージでそのフィールド名が通知されます。そのため、タイプミスによって設定が反映されたように見えて実際には機能していない、といった事態を防ぐことができます。価格、クレジット、通貨、または請求サイクルを変更すると、Stripe内に新しい価格が作成されます。すでに登録済みのクライアントは、登録時のプラン設定が継続されます。

### プランの削除

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agency/pricing-tiers/2" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

ダッシュボードと同じルールが適用されます。アクティブなサブスクライバーがいるプランは削除できません。リクエストは拒否され、現在何人のサブスクライバーがそのプランを利用しているかが通知されます。先にそれらのサブスクライバーを解約または移行してください。削除が成功すると、再番号付けされた残りのプラン一覧がレスポンスとして返されます。

### プランのフィールド

| フィールド | 内容 |
|---|---|
| `label` / `description` | プラン名、およびチェックアウトページに表示されるオプションの行。 |
| `credits` | 月間または年間プランでは **月ごと**、週間プランでは **請求期間ごと** にクライアントが付与されるクレジット。 |
| `price_cents` | 請求間隔ごとの価格（最小通貨単位。`2900` = $29.00）。年間プランでは1年分全体の価格。 |
| `currency` | 小文字のISOコード（`usd`、`eur`、`gbp` など）。 |
| `billing_interval` / `billing_interval_count` | `month`（デフォルト）、`year`、または「N週間ごと」の1〜52のカウントを指定する `week`。 |
| `trial_days` | 無料トライアル期間（0〜90日）。`0`（または省略）はトライアルなしを意味します。 |
| `trial_credits` | クライアントがトライアル開始時に持つクレジット。デフォルトはプランの `credits`。 |
| `trial_card_required` | `false` は、カード情報を入力せずにトライアルを開始できるようにします。デフォルトは `true`。 |
| `trial_hard_expiry` | `true` は、アップグレードなしでトライアルが終了した際に、未使用のトライアルクレジットをプールに戻し、クライアントのアカウントをロックします。デフォルトは `false`。[トライアル後のハード期限切れ](agency-accounts.md#step-3--set-up-pricing-tiers) を参照してください。 |
| `rollover_cap_months` | このプランのクライアントが更新の間に持ち越せる許容量（月数）。0から120の数値で、小数も指定可能。`0` は持ち越しなし。`null`（デフォルト）は上限なしを意味します。[繰越上限の設定](sub-accounts.md#capping-what-rolls-over) を参照してください。 |
| `rollover_expiry_days` | 次回の更新時に未使用クレジットが削除されるまでの日数（1〜3650の整数）。`null`（デフォルト）は有効期限なしを意味します。 |
| `features` / `feature_settings` | このプランのクライアントが利用できる機能。[クライアントが接続できるチャネルタイプを選択](#choose-which-channel-types-a-client-can-connect) と同じ機能ID。 |
| `team_seats_limit` | プランで付与されるチームシート数。正確な数値、なしの場合は `0`、無制限の場合は `-1`。 |
| `white_label_config` | このプランが販売される [ホワイトラベルドメイン](white-labeling.md#up-to-three-white-labels) のいずれか。 |

トライアル関連のフィールドは、トライアルが設定されているプランでのみ有効です。`trial_days: 0`でティアを保存すると、これらの設定は破棄されます。プランのStripeプロダクトIDおよび価格IDは自動的に管理されるため、手動で設定することはできません。

正しく設定するための3つのポイント：

- **ティアインデックスは位置を示すものであり、永続的なIDではありません。** プランを削除すると、それ以降のすべてのプランが1つずつ繰り上がります。そのため、変更を行った後は必ずリストを再取得してください。また、ダッシュボードでプランを削除した場合と同様に、公開済みのチェックアウトリンクも再コピーする必要があります。
- **SaaSモードを先に設定する必要があります。** これらのエンドポイントを使用するには、ホワイトラベル設定とStripeキーが保存されたエージェンシーアカウントが必要です。これらがない場合、プランのプロダクトや価格を紐付けるStripeアカウントが存在しません。
- **プラン数は最大20個までです。** これはダッシュボードと同じ制限です。リストレスポンス内の `max_tiers` フィールドで現在の制限を確認できます。

完全なリクエストおよびレスポンスのスキーマは、[APIリファレンス](../api/reference.md)の**Agency**セクションに記載されています。

***

## API経由でクレジット単価を設定する

`GET /v1/agency/credit-price` · `PATCH /v1/agency/credit-price`

アドホックなチャージ（**SaaSモード → クレジット単価設定**）でクライアントが支払う価格は、コードから読み取りや変更を行うことも可能です。これは価格を自動的に変動させる必要があるケース向けに構築されています。例えば、ある通貨でクレジットを販売し、別の通貨で請求を行う代理店の場合、毎週手動で価格を編集する代わりに、スケジュールされたジョブによって為替レートの変動に合わせて価格を修正させることができます。

### 現在の価格を読み取る

```bash
curl "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "note": "USD 0.25 per credit at our reference rate",
    "minimum_cents": 60
  }
}
```

`minimum_cents` は、その通貨でプラットフォームが許可する最低価格であるため、ジョブは新しい価格を送信する前に確認を行うことができます。価格が設定されるまで、これら3つの値はすべて `null` となります。

### 価格を変更する

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agency/credit-price" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price_per_credit_cents": 130, "currency": "brl" }'
```

変更したい項目のみを送信してください。`price_per_credit_cents` は最小通貨単位での価格です（`130` = R$1.30）。`currency` は小文字のISOコードです。`note` は、請求ページでクレジット単価の直下にクライアントに対して表示される最大200文字のオプションのテキストです。*「USD 0.25 per credit at our reference rate（基準レートで1クレジットあたり0.25米ドル）」*のように、他通貨での参考価格を表示するのに便利です。`"note": ""` を送信すると削除されます。レスポンスは上記の読み取りと同じ形式であるため、ジョブは比較を行い、変更がない場合は書き込みをスキップすることができます。

ダッシュボードと同じルールが適用されます。価格はその通貨のプラットフォーム最低価格を下回ることはできず、アカウントにはホワイトラベル設定が必要です。価格ティアのエンドポイントとは異なり、この値を読み取ったり変更したりするためにStripeキーは必要ありません。

### 他の操作ができないキーをジョブに付与する

スケジューラーにエージェンシーのフルキーを入力することは、価格更新に必要な権限以上のアクセス権を与えることになります。代わりに、**Agency Credit Price**（エージェンシーのクレジット価格）エリアに限定された**スコープ付きキー**を作成してください。このキーはクレジット単価の読み取りと変更のみが可能で、それ以外の操作（サブアカウント、プラン、クレジット、Stripe接続へのアクセスなど）は一切できません。

```bash
curl -X POST "https://api.dmchamp.com/v1/api-keys" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "FX price updater", "scopes": { "read_only": false, "tags": ["Agency Credit Price"] } }'
```

レスポンスには新しいキーが`api_key`として**一度だけ**含まれます。二度と表示されないため、すぐに保存してください。価格の読み取りのみが必要なキーには`"read_only": true`を設定し、自動的に無効化したい場合は`"expires_at"`（ISO日付）を追加してください。スコープ付きキーを作成できるのはアカウント所有者のキーのみです。キーの一覧表示や取り消しは、`GET /v1/api-keys`および`DELETE /v1/api-keys/{id}`で行えます。

***

## サブアカウントに価格設定を読み取らせる

`GET /v1/subaccounts/agency-pricing`

このページの他のすべてのエンドポイントは、**貴社のエージェンシーキー**を使用して呼び出され、オプションで `sub_account_id` を介してクライアントをターゲットにします。このエンドポイントはその逆で、**サブアカウント自身のAPIキー**を使用して呼び出され、`sub_account_id` は使用しません。そのため、クライアント自身のチャージページ（または貴社がクライアントのために構築する統合）で、貴社のアカウント情報を表示することなく、貴社がクライアントに請求する金額を表示できます。

```bash
curl "https://api.dmchamp.com/v1/subaccounts/agency-pricing" \
  -H "X-API-Key: THE_SUB_ACCOUNTS_OWN_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "tiers": [{ "credits": 1000, "price_cents": 2900, "currency": "usd" }],
    "price_per_credit_cents": 125,
    "price_per_credit_currency": "brl",
    "price_per_credit_note": "USD 0.25 per credit at our reference rate",
    "agency_display_name": "Client Co's Growth Partner"
  }
}
```

これは、エージェンシーとして貴社が受け取る [`GET /v1/agency/pricing-tiers`](#list-your-tiers) および [`GET /v1/agency/credit-price`](#read-the-current-price) の戻り値と完全に一致しますが、クライアントに見せる必要のない情報（Stripe ID、`max_tiers` など）は除外されます。これは、エージェンシーとリンクされたサブアカウントである場合にのみ機能します。貴社自身のエージェンシーアカウントから呼び出すと、権限エラーが返されます。

***

## 注意事項

- **エージェンシーキーを使用してください。** すべての呼び出しは、サブアカウントのAPIキーではなく、エージェンシーアカウントのAPIキーで認証してください。`sub_account_id` パラメータがアクションの転送先を指定します。
- **クレジットはサブアカウントから消費されます。** 購入や定期的な請求は、あなたのアカウントではなく、対象となるサブアカウントのクレジット残高に適用されます。
- **`404` は「対象外のサブアカウント」を意味します。** IDを再確認し、そのアカウントがあなたが管理しているものであることを確認してください。
- **このパラメータは、受け入れ可能なすべての場所でオプションです。** 省略した場合、同じエンドポイントがエージェンシーアカウントに対して機能するため、1つの統合を両方に再利用できます。

***

## 関連情報

- [APIアクセス](../integrations/api-access.md) — 認証、ベースURL、エラー、レート制限。
- [サブアカウント](sub-accounts.md) — ターゲットにできるアカウントのリストと管理。
- [サブアカウントの自動リチャージ](sub-account-auto-recharge.md) — Webhook + APIを介してサブアカウントにクレジットを付与。
- [キャンペーンAPI](../api/campaigns.md) — キャンペーンの作成、更新、コピー（完全なフィールドリファレンスを含む）。
- [チャネル接続API](../api/channels.md) — クライアントのチャネルを接続し、キャンペーンにルーティング。
- Analytics APIガイド（APIセクション内） — エージェンシーのサブアカウントのロールアップおよびその他のすべてのレポートエンドポイント。
- [スナップショット](snapshots.md) — スナップショットがキャプチャするものと、ダッシュボードでの構築方法。