# API設計書

## 概要

本ドキュメントは、Chatwootのバックエンド API の設計仕様を記述したものです。Chatwootは、カスタマーサポート向けのオープンソースチャットプラットフォームであり、REST APIを通じてアカウント管理、会話管理、コンタクト管理、チーム管理などの機能を提供します。

## 共通仕様

### ベースURL

```
/api/v1
/api/v2
/platform/api/v1
/public/api/v1
```

### 認証方式

Chatwoot APIは以下の認証方式をサポートしています:

1. **Devise Token Auth（セッションベース）**: ブラウザベースのセッション認証
2. **API Access Token**: `api_access_token` ヘッダーを使用したトークン認証
3. **Platform API Token**: Platform Appに発行されたアクセストークン

### 共通ヘッダー

| ヘッダー名 | 必須 | 説明 |
| --- | --- | --- |
| api_access_token | 条件付き | APIアクセストークン（トークン認証時） |
| Content-Type | ○ | application/json |
| Accept | - | application/json |

### 共通エラーレスポンス

| ステータスコード | 説明 |
| --- | --- |
| 400 | Bad Request - リクエストパラメータ不正 |
| 401 | Unauthorized - 認証エラー |
| 403 | Forbidden - 権限エラー |
| 404 | Not Found - リソース未検出 |
| 422 | Unprocessable Entity - バリデーションエラー |
| 500 | Internal Server Error - サーバーエラー |

---

## API一覧

### Application API (v1)

| カテゴリ | エンドポイント | メソッド | 説明 |
| --- | --- | --- | --- |
| Accounts | /api/v1/accounts | POST | アカウント作成 |
| Accounts | /api/v1/accounts/:id | GET | アカウント詳細取得 |
| Accounts | /api/v1/accounts/:id | PATCH | アカウント更新 |
| Accounts | /api/v1/accounts/:id/update_active_at | POST | アクティブ時刻更新 |
| Accounts | /api/v1/accounts/:id/cache_keys | GET | キャッシュキー取得 |
| Agents | /api/v1/accounts/:account_id/agents | GET | エージェント一覧 |
| Agents | /api/v1/accounts/:account_id/agents | POST | エージェント作成 |
| Agents | /api/v1/accounts/:account_id/agents/:id | PATCH | エージェント更新 |
| Agents | /api/v1/accounts/:account_id/agents/:id | DELETE | エージェント削除 |
| Agents | /api/v1/accounts/:account_id/agents/bulk_create | POST | エージェント一括作成 |
| Conversations | /api/v1/accounts/:account_id/conversations | GET | 会話一覧 |
| Conversations | /api/v1/accounts/:account_id/conversations | POST | 会話作成 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id | GET | 会話詳細取得 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id | PATCH | 会話更新 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id | DELETE | 会話削除 |
| Conversations | /api/v1/accounts/:account_id/conversations/meta | GET | 会話メタ情報取得 |
| Conversations | /api/v1/accounts/:account_id/conversations/search | GET | 会話検索 |
| Conversations | /api/v1/accounts/:account_id/conversations/filter | POST | 会話フィルタ |
| Conversations | /api/v1/accounts/:account_id/conversations/:id/mute | POST | 会話ミュート |
| Conversations | /api/v1/accounts/:account_id/conversations/:id/unmute | POST | 会話ミュート解除 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id/transcript | POST | トランスクリプト送信 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id/toggle_status | POST | ステータス切替 |
| Conversations | /api/v1/accounts/:account_id/conversations/:id/toggle_priority | POST | 優先度切替 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages | GET | メッセージ一覧 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages | POST | メッセージ作成 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages/:id | PATCH | メッセージ更新 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages/:id | DELETE | メッセージ削除 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages/:id/translate | POST | メッセージ翻訳 |
| Messages | /api/v1/accounts/:account_id/conversations/:conversation_id/messages/:id/retry | POST | メッセージ再送 |
| Contacts | /api/v1/accounts/:account_id/contacts | GET | コンタクト一覧 |
| Contacts | /api/v1/accounts/:account_id/contacts | POST | コンタクト作成 |
| Contacts | /api/v1/accounts/:account_id/contacts/:id | GET | コンタクト詳細取得 |
| Contacts | /api/v1/accounts/:account_id/contacts/:id | PATCH | コンタクト更新 |
| Contacts | /api/v1/accounts/:account_id/contacts/:id | DELETE | コンタクト削除 |
| Contacts | /api/v1/accounts/:account_id/contacts/active | GET | アクティブコンタクト |
| Contacts | /api/v1/accounts/:account_id/contacts/search | GET | コンタクト検索 |
| Contacts | /api/v1/accounts/:account_id/contacts/filter | POST | コンタクトフィルタ |
| Contacts | /api/v1/accounts/:account_id/contacts/import | POST | コンタクトインポート |
| Contacts | /api/v1/accounts/:account_id/contacts/export | POST | コンタクトエクスポート |
| Inboxes | /api/v1/accounts/:account_id/inboxes | GET | インボックス一覧 |
| Inboxes | /api/v1/accounts/:account_id/inboxes | POST | インボックス作成 |
| Inboxes | /api/v1/accounts/:account_id/inboxes/:id | GET | インボックス詳細取得 |
| Inboxes | /api/v1/accounts/:account_id/inboxes/:id | PATCH | インボックス更新 |
| Inboxes | /api/v1/accounts/:account_id/inboxes/:id | DELETE | インボックス削除 |
| Labels | /api/v1/accounts/:account_id/labels | GET | ラベル一覧 |
| Labels | /api/v1/accounts/:account_id/labels | POST | ラベル作成 |
| Labels | /api/v1/accounts/:account_id/labels/:id | GET | ラベル詳細取得 |
| Labels | /api/v1/accounts/:account_id/labels/:id | PATCH | ラベル更新 |
| Labels | /api/v1/accounts/:account_id/labels/:id | DELETE | ラベル削除 |
| Teams | /api/v1/accounts/:account_id/teams | GET | チーム一覧 |
| Teams | /api/v1/accounts/:account_id/teams | POST | チーム作成 |
| Teams | /api/v1/accounts/:account_id/teams/:id | GET | チーム詳細取得 |
| Teams | /api/v1/accounts/:account_id/teams/:id | PATCH | チーム更新 |
| Teams | /api/v1/accounts/:account_id/teams/:id | DELETE | チーム削除 |
| Webhooks | /api/v1/accounts/:account_id/webhooks | GET | Webhook一覧 |
| Webhooks | /api/v1/accounts/:account_id/webhooks | POST | Webhook作成 |
| Webhooks | /api/v1/accounts/:account_id/webhooks/:id | PATCH | Webhook更新 |
| Webhooks | /api/v1/accounts/:account_id/webhooks/:id | DELETE | Webhook削除 |
| Notifications | /api/v1/accounts/:account_id/notifications | GET | 通知一覧 |
| Notifications | /api/v1/accounts/:account_id/notifications/:id | PATCH | 通知更新 |
| Notifications | /api/v1/accounts/:account_id/notifications/:id | DELETE | 通知削除 |
| Notifications | /api/v1/accounts/:account_id/notifications/read_all | POST | 全て既読 |
| Notifications | /api/v1/accounts/:account_id/notifications/unread_count | GET | 未読数取得 |
| Canned Responses | /api/v1/accounts/:account_id/canned_responses | GET | 定型文一覧 |
| Canned Responses | /api/v1/accounts/:account_id/canned_responses | POST | 定型文作成 |
| Canned Responses | /api/v1/accounts/:account_id/canned_responses/:id | PATCH | 定型文更新 |
| Canned Responses | /api/v1/accounts/:account_id/canned_responses/:id | DELETE | 定型文削除 |
| Automation Rules | /api/v1/accounts/:account_id/automation_rules | GET | 自動化ルール一覧 |
| Automation Rules | /api/v1/accounts/:account_id/automation_rules | POST | 自動化ルール作成 |
| Automation Rules | /api/v1/accounts/:account_id/automation_rules/:id | GET | 自動化ルール詳細 |
| Automation Rules | /api/v1/accounts/:account_id/automation_rules/:id | PATCH | 自動化ルール更新 |
| Automation Rules | /api/v1/accounts/:account_id/automation_rules/:id | DELETE | 自動化ルール削除 |
| Macros | /api/v1/accounts/:account_id/macros | GET | マクロ一覧 |
| Macros | /api/v1/accounts/:account_id/macros | POST | マクロ作成 |
| Macros | /api/v1/accounts/:account_id/macros/:id | GET | マクロ詳細 |
| Macros | /api/v1/accounts/:account_id/macros/:id | PATCH | マクロ更新 |
| Macros | /api/v1/accounts/:account_id/macros/:id | DELETE | マクロ削除 |
| Macros | /api/v1/accounts/:account_id/macros/:id/execute | POST | マクロ実行 |
| Profile | /api/v1/profile | GET | プロフィール取得 |
| Profile | /api/v1/profile | PATCH | プロフィール更新 |
| Profile | /api/v1/profile/avatar | DELETE | アバター削除 |
| Profile | /api/v1/profile/availability | POST | 可用性更新 |
| Profile | /api/v1/profile/auto_offline | POST | 自動オフライン更新 |

### Reports API (v2)

| カテゴリ | エンドポイント | メソッド | 説明 |
| --- | --- | --- | --- |
| Reports | /api/v2/accounts/:account_id/reports | GET | レポートデータ取得 |
| Reports | /api/v2/accounts/:account_id/reports/summary | GET | サマリー取得 |
| Reports | /api/v2/accounts/:account_id/reports/agents | GET | エージェントレポート |
| Reports | /api/v2/accounts/:account_id/reports/inboxes | GET | インボックスレポート |
| Reports | /api/v2/accounts/:account_id/reports/labels | GET | ラベルレポート |
| Reports | /api/v2/accounts/:account_id/reports/teams | GET | チームレポート |
| Reports | /api/v2/accounts/:account_id/reports/conversations | GET | 会話レポート |

### Platform API (v1)

| カテゴリ | エンドポイント | メソッド | 説明 |
| --- | --- | --- | --- |
| Accounts | /platform/api/v1/accounts | GET | アカウント一覧 |
| Accounts | /platform/api/v1/accounts | POST | アカウント作成 |
| Accounts | /platform/api/v1/accounts/:id | GET | アカウント詳細 |
| Accounts | /platform/api/v1/accounts/:id | PATCH | アカウント更新 |
| Accounts | /platform/api/v1/accounts/:id | DELETE | アカウント削除 |
| Users | /platform/api/v1/users | POST | ユーザー作成 |
| Users | /platform/api/v1/users/:id | GET | ユーザー詳細 |
| Users | /platform/api/v1/users/:id | PATCH | ユーザー更新 |
| Users | /platform/api/v1/users/:id | DELETE | ユーザー削除 |
| Users | /platform/api/v1/users/:id/login | GET | SSO ログインURL |
| Users | /platform/api/v1/users/:id/token | GET | トークン取得 |

### Public API (v1)

| カテゴリ | エンドポイント | メソッド | 説明 |
| --- | --- | --- | --- |
| Contacts | /public/api/v1/inboxes/:inbox_id/contacts | POST | コンタクト作成 |
| Contacts | /public/api/v1/inboxes/:inbox_id/contacts/:id | GET | コンタクト詳細 |
| Contacts | /public/api/v1/inboxes/:inbox_id/contacts/:id | PATCH | コンタクト更新 |
| Conversations | /public/api/v1/inboxes/:inbox_id/contacts/:contact_id/conversations | GET | 会話一覧 |
| Conversations | /public/api/v1/inboxes/:inbox_id/contacts/:contact_id/conversations | POST | 会話作成 |
| Messages | /public/api/v1/inboxes/:inbox_id/contacts/:contact_id/conversations/:conversation_id/messages | GET | メッセージ一覧 |
| Messages | /public/api/v1/inboxes/:inbox_id/contacts/:contact_id/conversations/:conversation_id/messages | POST | メッセージ作成 |

---

## 各APIエンドポイント定義

### Accounts

#### 1. アカウント作成

アカウントと初期ユーザーを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts` |
| 認証 | 不要 |
| 権限 | なし（サインアップが有効な場合のみ） |

**リクエストボディ**

```json
{
  "account_name": "My Company",
  "user_full_name": "John Doe",
  "email": "john@example.com",
  "password": "securepassword123",
  "locale": "en"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| account_name | string | ○ | presence | アカウント名 |
| user_full_name | string | ○ | presence | ユーザーのフルネーム |
| email | string | ○ | email format | メールアドレス |
| password | string | ○ | - | パスワード |
| locale | string | - | - | ロケール設定 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "data": {
    "id": 1,
    "name": "My Company",
    "locale": "en"
  }
}
```

---

#### 2. アカウント詳細取得

特定のアカウントの詳細情報を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:id` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "id": 1,
  "name": "My Company",
  "locale": "en",
  "domain": "example.com",
  "support_email": "support@example.com"
}
```

---

#### 3. アカウント更新

アカウント情報を更新します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `PATCH /api/v1/accounts/:id` |
| 認証 | 必要 |
| 権限 | アカウント管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "name": "Updated Company Name",
  "locale": "ja",
  "domain": "newdomain.com",
  "support_email": "newsupport@example.com"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | アカウント名 |
| locale | string | - | - | ロケール |
| domain | string | - | - | ドメイン |
| support_email | string | - | email format | サポートメール |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Agents

#### 4. エージェント一覧

アカウントに所属するエージェント（ユーザー）一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/agents` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role": "administrator",
    "availability": "online",
    "auto_offline": true
  }
]
```

---

#### 5. エージェント作成

新しいエージェントを招待・作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/agents` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "agent": {
    "email": "newagent@example.com",
    "name": "New Agent",
    "role": "agent",
    "availability": "online",
    "auto_offline": true
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| email | string | ○ | email format | メールアドレス |
| name | string | - | - | エージェント名 |
| role | string | - | agent/administrator | ロール |
| availability | string | - | online/offline/busy | 可用性 |
| auto_offline | boolean | - | - | 自動オフライン |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Conversations

#### 6. 会話一覧

アカウント内の会話一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/conversations` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| assignee_type | string | - | - | アサイニータイプ |
| status | string | - | - | ステータスフィルター |
| inbox_id | integer | - | - | インボックスID |
| page | integer | - | 1 | ページ番号 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "data": {
    "payload": [
      {
        "id": 1,
        "display_id": 1,
        "status": "open",
        "priority": null,
        "inbox_id": 1,
        "contact": {},
        "messages": []
      }
    ],
    "meta": {
      "mine_count": 10,
      "unassigned_count": 5,
      "all_count": 20
    }
  }
}
```

---

#### 7. 会話作成

新しい会話を作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/conversations` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "inbox_id": 1,
  "contact_id": 1,
  "source_id": "unique_source_id",
  "message": {
    "content": "Hello, I need help!"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| inbox_id | integer | - | - | インボックスID |
| contact_id | integer | - | - | コンタクトID |
| source_id | string | - | unique | ソースID |
| message | object | - | - | 初期メッセージ |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

#### 8. 会話ステータス切替

会話のステータスを切り替えます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/conversations/:id/toggle_status` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |
| id | integer | ○ | 会話のdisplay_id |

**リクエストボディ**

```json
{
  "status": "resolved",
  "snoozed_until": "2024-01-01T00:00:00Z"
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| status | string | - | open/resolved/pending/snoozed | 新しいステータス |
| snoozed_until | datetime | - | - | スヌーズ終了時刻 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Messages

#### 9. メッセージ一覧

会話内のメッセージ一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/conversations/:conversation_id/messages` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |
| conversation_id | integer | ○ | 会話のdisplay_id |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "id": 1,
    "content": "Hello!",
    "message_type": "incoming",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

---

#### 10. メッセージ作成

会話に新しいメッセージを追加します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/conversations/:conversation_id/messages` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |
| conversation_id | integer | ○ | 会話のdisplay_id |

**リクエストボディ**

```json
{
  "content": "Thank you for contacting us!",
  "message_type": "outgoing",
  "private": false
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| content | string | - | - | メッセージ内容 |
| message_type | string | - | incoming/outgoing | メッセージタイプ |
| private | boolean | - | - | プライベートノート |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Contacts

#### 11. コンタクト一覧

アカウント内のコンタクト一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/contacts` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| page | integer | - | 1 | ページ番号 |
| sort | string | - | - | ソート項目 |
| labels | array | - | - | ラベルフィルター |
| include_contact_inboxes | boolean | - | true | コンタクトインボックス含む |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "payload": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone_number": "+1234567890"
    }
  ],
  "meta": {
    "count": 100
  }
}
```

---

#### 12. コンタクト作成

新しいコンタクトを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/contacts` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone_number": "+1234567890",
  "identifier": "unique_id",
  "custom_attributes": {
    "company": "Acme Corp"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | 名前 |
| email | string | - | email format | メールアドレス |
| phone_number | string | - | - | 電話番号 |
| identifier | string | - | unique | 識別子 |
| custom_attributes | object | - | - | カスタム属性 |
| avatar_url | string | - | url format | アバターURL |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

#### 13. コンタクト検索

コンタクトを検索します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/contacts/search` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| q | string | ○ | - | 検索クエリ |

**レスポンス（成功時）**

ステータスコード: `200 OK`

**レスポンス（エラー時）**

ステータスコード: `422 Unprocessable Entity`

```json
{
  "error": "Specify search string with parameter q"
}
```

---

### Inboxes

#### 14. インボックス一覧

アカウント内のインボックス一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/inboxes` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "payload": [
    {
      "id": 1,
      "name": "Website Chat",
      "channel_type": "Channel::WebWidget",
      "greeting_enabled": true
    }
  ]
}
```

---

#### 15. インボックス作成

新しいインボックスを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/inboxes` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "name": "Website Chat",
  "channel": {
    "type": "web_widget",
    "website_url": "https://example.com"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | インボックス名 |
| channel.type | string | ○ | web_widget/api/email/line/telegram/whatsapp/sms | チャネルタイプ |
| greeting_enabled | boolean | - | - | 挨拶有効化 |
| greeting_message | string | - | - | 挨拶メッセージ |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Labels

#### 16. ラベル一覧

アカウント内のラベル一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/labels` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "payload": [
    {
      "id": 1,
      "title": "VIP",
      "description": "VIP customers",
      "color": "#FF0000",
      "show_on_sidebar": true
    }
  ]
}
```

---

#### 17. ラベル作成

新しいラベルを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/labels` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "label": {
    "title": "Priority",
    "description": "High priority items",
    "color": "#FF5733",
    "show_on_sidebar": true
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| title | string | ○ | presence | ラベル名 |
| description | string | - | - | 説明 |
| color | string | - | hex color format | 色 |
| show_on_sidebar | boolean | - | - | サイドバー表示 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Teams

#### 18. チーム一覧

アカウント内のチーム一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/teams` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "id": 1,
    "name": "Support Team",
    "description": "Main support team",
    "allow_auto_assign": true
  }
]
```

---

#### 19. チーム作成

新しいチームを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/teams` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "team": {
    "name": "Sales Team",
    "description": "Sales support team",
    "allow_auto_assign": true
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | ○ | presence | チーム名 |
| description | string | - | - | 説明 |
| allow_auto_assign | boolean | - | - | 自動アサイン許可 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Webhooks

#### 20. Webhook一覧

アカウント内のWebhook一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/webhooks` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "payload": [
    {
      "id": 1,
      "name": "Order Webhook",
      "url": "https://example.com/webhook",
      "subscriptions": ["conversation_created", "message_created"]
    }
  ]
}
```

---

#### 21. Webhook作成

新しいWebhookを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/webhooks` |
| 認証 | 必要 |
| 権限 | 管理者 |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "webhook": {
    "name": "Order Updates",
    "url": "https://example.com/webhook",
    "inbox_id": 1,
    "subscriptions": ["conversation_created", "message_created"]
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | Webhook名 |
| url | string | ○ | url format | Webhook URL |
| inbox_id | integer | - | - | インボックスID |
| subscriptions | array | - | - | 購読イベント |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Canned Responses

#### 22. 定型文一覧

アカウント内の定型文一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/accounts/:account_id/canned_responses` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**クエリパラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| search | string | - | - | 検索クエリ |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "id": 1,
    "short_code": "greeting",
    "content": "Hello! How can I help you today?"
  }
]
```

---

#### 23. 定型文作成

新しい定型文を作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /api/v1/accounts/:account_id/canned_responses` |
| 認証 | 必要 |
| 権限 | アカウントメンバー |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| account_id | integer | ○ | アカウントID |

**リクエストボディ**

```json
{
  "canned_response": {
    "short_code": "thanks",
    "content": "Thank you for reaching out!"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| short_code | string | ○ | presence, unique | ショートコード |
| content | string | ○ | presence | 内容 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Profile

#### 24. プロフィール取得

現在のユーザーのプロフィールを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /api/v1/profile` |
| 認証 | 必要 |
| 権限 | 認証済みユーザー |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "display_name": "John",
  "message_signature": "Best regards"
}
```

---

#### 25. プロフィール更新

現在のユーザーのプロフィールを更新します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `PATCH /api/v1/profile` |
| 認証 | 必要 |
| 権限 | 認証済みユーザー |

**リクエストボディ**

```json
{
  "profile": {
    "name": "John Smith",
    "display_name": "Johnny",
    "email": "john.smith@example.com",
    "message_signature": "Kind regards",
    "current_password": "oldpassword",
    "password": "newpassword",
    "password_confirmation": "newpassword"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | 名前 |
| display_name | string | - | - | 表示名 |
| email | string | - | email format | メールアドレス |
| message_signature | string | - | - | メッセージ署名 |
| current_password | string | 条件付き | - | 現在のパスワード |
| password | string | - | - | 新しいパスワード |
| password_confirmation | string | - | match password | パスワード確認 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

**レスポンス（エラー時）**

ステータスコード: `422 Unprocessable Entity`

```json
{
  "message": "Invalid current password"
}
```

---

### Platform API - Accounts

#### 26. Platform アカウント一覧

Platform Appがアクセス可能なアカウント一覧を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /platform/api/v1/accounts` |
| 認証 | Platform API Token |
| 権限 | Platform App |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "id": 1,
    "name": "My Company",
    "locale": "en"
  }
]
```

---

#### 27. Platform アカウント作成

新しいアカウントを作成し、Platform Appに紐付けます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /platform/api/v1/accounts` |
| 認証 | Platform API Token |
| 権限 | Platform App |

**リクエストボディ**

```json
{
  "name": "New Company",
  "locale": "en",
  "domain": "newcompany.com",
  "support_email": "support@newcompany.com",
  "features": {
    "auto_resolve": true
  },
  "limits": {
    "agents": 10
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | ○ | presence | アカウント名 |
| locale | string | - | - | ロケール |
| domain | string | - | - | ドメイン |
| support_email | string | - | email format | サポートメール |
| features | object | - | - | 機能フラグ |
| limits | object | - | - | 制限設定 |
| custom_attributes | object | - | - | カスタム属性 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

### Platform API - Users

#### 28. Platform ユーザー作成

新しいユーザーを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /platform/api/v1/users` |
| 認証 | Platform API Token |
| 権限 | Platform App |

**リクエストボディ**

```json
{
  "name": "New User",
  "email": "newuser@example.com",
  "password": "securepassword",
  "custom_attributes": {
    "department": "Sales"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| name | string | - | - | 名前 |
| email | string | ○ | email format | メールアドレス |
| password | string | - | - | パスワード |
| display_name | string | - | - | 表示名 |
| custom_attributes | object | - | - | カスタム属性 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

#### 29. Platform SSO ログインURL取得

ユーザーのSSOログインURLを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET /platform/api/v1/users/:id/login` |
| 認証 | Platform API Token |
| 権限 | Platform App |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| id | integer | ○ | ユーザーID |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "url": "https://app.chatwoot.com/app/login?sso_auth_token=xxx"
}
```

---

### Public API - Contacts

#### 30. Public コンタクト作成

公開APIを通じてコンタクトを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `POST /public/api/v1/inboxes/:inbox_id/contacts` |
| 認証 | 不要（インボックスの公開設定による） |
| 権限 | なし |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| inbox_id | string | ○ | インボックスのチャネルID |

**リクエストボディ**

```json
{
  "identifier": "unique_visitor_id",
  "identifier_hash": "hmac_hash",
  "email": "visitor@example.com",
  "name": "Visitor Name",
  "phone_number": "+1234567890",
  "avatar_url": "https://example.com/avatar.png",
  "custom_attributes": {
    "plan": "premium"
  }
}
```

| フィールド名 | 型 | 必須 | バリデーション | 説明 |
| --- | --- | --- | --- | --- |
| identifier | string | - | - | 識別子 |
| identifier_hash | string | 条件付き | HMAC検証 | HMAC認証ハッシュ |
| email | string | - | email format | メールアドレス |
| name | string | - | - | 名前 |
| phone_number | string | - | - | 電話番号 |
| avatar_url | string | - | url format | アバターURL |
| custom_attributes | object | - | - | カスタム属性 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

---

## 備考

### Bot アクセス可能エンドポイント

Agent Bot（api_access_token認証）がアクセスできるエンドポイントは制限されています:

- `api/v1/accounts/conversations`: toggle_status, toggle_priority, create, update, custom_attributes
- `api/v1/accounts/conversations/messages`: create
- `api/v1/accounts/conversations/assignments`: create

### Enterprise限定機能

以下のエンドポイントはEnterprise版でのみ利用可能です:

- `/api/v1/accounts/:account_id/conversations/:id/reporting_events`
- `/api/v1/accounts/:account_id/reporting_events`
- `/api/v1/accounts/:account_id/contacts/:id/call`
- `/api/v1/accounts/:account_id/csat_survey_responses/:id` (PATCH)
- `/enterprise/api/v1/accounts/:id/checkout`
- `/enterprise/api/v1/accounts/:id/subscription`

### チャネルタイプ

インボックス作成時に指定可能なチャネルタイプ:

- `web_widget`: Webサイト用チャットウィジェット
- `api`: API連携チャネル
- `email`: メールチャネル
- `line`: LINE連携
- `telegram`: Telegram連携
- `whatsapp`: WhatsApp連携
- `sms`: SMS連携
