> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/api-reference/dui-hua-ping-tai.md).

# 対話プラットフォーム

会話が所属する単位であるインボックス（Inbox）は、Webhook の設定場所でもあります。各インボックスには複数の Webhook を設定でき、ユーザーメッセージの受信時（`incoming`）または Agent の返信時（`outgoing`）に、お客様のシステムに通知を送信します。Web Chat タイプのインボックスには、別途 [Web Chat エンドポイント](https://docs.maiagent.ai/api/ja/api-reference/dui-hua-widget.md)があります。設定方法と payload の形式については、技術マニュアルの [Webhook](https://docs.maiagent.ai/tech/api-integration/webhook)をご覧ください。

### チャットプラットフォームの一覧 <a href="#inboxes-list" id="inboxes-list"></a>

GET `/api/v1/inboxes/`

#### パラメータ

| パラメータ名         | 必須 | 型       | 説明                                                                                                      |
| -------------- | -- | ------- | ------------------------------------------------------------------------------------------------------- |
| `accessType`   | ❌  | string  | アクセスタイプで絞り込みます                                                                                          |
| `channelType`  | ❌  | string  | チャンネルタイプで絞り込みます                                                                                         |
| `chatbot`      | ❌  | string  | チャットボット ID で絞り込みます                                                                                      |
| `excludeTeam`  | ❌  | boolean | Leave out the chat platforms of teams' entry assistants, which the team's role grants decide.           |
| `excludeVoice` | ❌  | boolean | Leave out every voice agent inbox (inbox settings list).                                                |
| `includeVoice` | ❌  | boolean | With chatbot: also list the inboxes of the voice agents answered by it (role page, chat platform list). |
| `isActive`     | ❌  | boolean | 有効かどうかで絞り込みます                                                                                           |
| `ordering`     | ❌  | string  | Which field to use when ordering the results.                                                           |
| `page`         | ❌  | integer | A page number within the paginated result set.                                                          |
| `pageSize`     | ❌  | integer | Number of results to return per page.                                                                   |
| `pagination`   | ❌  | string  | ページネーションを行うかどうか (true/false) を指定します。false に設定すると、簡易版のデータ形式で返します                                         |
| `query`        | ❌  | string  |                                                                                                         |
| `source`       | ❌  | string  | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all;                                 |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/inboxes/?accessType=example&channelType=example&chatbot=example&excludeTeam=true&excludeVoice=true&includeVoice=true&isActive=true&ordering=example&page=1&pageSize=1&pagination=example&query=example&source=all" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/inboxes/?accessType=example&channelType=example&chatbot=example&excludeTeam=true&excludeVoice=true&includeVoice=true&isActive=true&ordering=example&page=1&pageSize=1&pagination=example&query=example&source=all", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/?accessType=example&channelType=example&chatbot=example&excludeTeam=true&excludeVoice=true&includeVoice=true&isActive=true&ordering=example&page=1&pageSize=1&pagination=example&query=example&source=all"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/inboxes/?accessType=example&channelType=example&chatbot=example&excludeTeam=true&excludeVoice=true&includeVoice=true&isActive=true&ordering=example&page=1&pageSize=1&pagination=example&query=example&source=all", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200 - チャットプラットフォームの一覧**

**レスポンススキーマの例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "name": string
      "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
      "unreadConversationsCount"?: integer // 任意
      "signAuth"?:  // 任意
      {
        "id": string (uuid)
        "signSource": string (uuid)
        "signParams": {
        {
          "keycloak": 
          {
            "clientId": string
            "url": string
            "realm": string
          }
          "line": 
          {
            "liffId": string
          }
          "ad": 
          {
            "saml": string
          }
          "google"?:  // 任意
          {
            "enabled": boolean
          }
        }
        }
        "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
        "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
        {
        }
        "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
        {
        }
        "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
        "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
          string
        ]
        "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
      }
      "enableAnalysis"?: boolean // 任意
      "voiceAgent": object // The voice agent this inbox is the entry of ({id, name, architecture, isDeleted}); null otherwise
    }
  ]
}
```

**レスポンスのサンプル値**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "961dcaac-bd2e-44d3-9050-82596dbb3334",
      "chatbot": {
        "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b",
        "name": "カスタマーサポートボット",
        "groups": [],
        "largeLanguageModel": {
          "id": "933aa8b3-cdf4-47a7-86d5-b5dc27fbb044",
          "name": "llm"
        },
        "embeddingModel": {
          "id": "aefcc4f9-917d-4a8a-bd36-d97e3b7cecfe",
          "name": "embedding",
          "icon": null,
          "isDefault": false
        },
        "rerankerModel": {
          "id": "86c2ddfd-0df9-47b9-8f3b-0c42e3347da3",
          "name": "rerank",
          "icon": null,
          "isDefault": true
        },
        "knowledgeBases": [],
        "tools": [],
        "agentMode": "normal",
        "replyMode": "normal",
        "updatedAt": "1739519493000",
        "enableEvaluation": false,
        "enableInlineCitations": false,
        "enableKnowledgeBaseRag": true,
        "enableAgenticTextToSql": true,
        "enableToolSearching": true,
        "numberOfRetrievedChunks": 12
      },
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "管理者グループ"
        }
      ],
      "channelType": "web",
      "channelTypeLabel": "Web",
      "name": "1345",
      "autoReplySchedules": [
        {
          "id": "2f4f6383-d8b5-4d88-b4a1-6d02d731f2a6",
          "weekday": 0,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Monday"
        },
        {
          "id": "2866f624-a5c3-4ffb-b980-0f8d6a9f0c93",
          "weekday": 1,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Tuesday"
        },
        {
          "id": "3cf1e488-fb13-426d-bd59-e62bd71aca85",
          "weekday": 2,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Wednesday"
        },
        {
          "id": "491776a9-fcf1-4e2e-892f-6d9ad5aebea4",
          "weekday": 3,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Thursday"
        },
        {
          "id": "dfecb0a9-5001-4aa0-b2cc-5459b6d64351",
          "weekday": 4,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Friday"
        },
        {
          "id": "68b6b4d1-7ac8-450f-8877-41b72b499919",
          "weekday": 5,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Saturday"
        },
        {
          "id": "15228ea1-4513-4504-81f4-4e486703d8b9",
          "weekday": 6,
          "isEnabled": true,
          "timeSlots": [
            [
              "00:00:00",
              "00:00:00"
            ]
          ],
          "weekdayName": "Sunday"
        }
      ],
      "unreadConversationsCount": 0,
      "totalConversationsCount": 42,
      "channel": {
        "id": "801a690a-1038-4fdd-8aba-bf003b12c3ef",
        "name": "1345",
        "avatar": "https://media-dev.maiagent.ai/static/images/default-chatbot-avatar.png",
        "logo": null,
        "description": "",
        "cover": null,
        "backUrl": "",
        "isActive": true,
        "enableSpeech": false,
        "displayGreeting": null,
        "displayConversationStarters": [],
        "theme": {
          "primaryColor": "#3854d8",
          "navbarTextColor": "#ffffff",
          "conversationBackgroundColor": "#ffffff",
          "chatbotMessageTextColor": "#374151",
          "userMessageTextColor": "#374151",
          "chatbotMessageBackgroundColor": "#DCE9F6",
          "userMessageBackgroundColor": "#DDEAF6",
          "chatbotMessageBackgroundShadowEnabled": true,
          "userMessageBackgroundShadowEnabled": true
        },
        "darkTheme": {
          "primaryColor": "#404040",
          "navbarTextColor": "#ffffff",
          "conversationBackgroundColor": "#18181B",
          "chatbotMessageTextColor": "#ffffff",
          "userMessageTextColor": "#ffffff",
          "chatbotMessageBackgroundColor": "#171717",
          "userMessageBackgroundColor": "#333842",
          "chatbotMessageBackgroundShadowEnabled": false,
          "userMessageBackgroundShadowEnabled": false
        },
        "enableFileUpload": true,
        "enableDisplayCitations": true,
        "enableShareConversation": false,
        "enableLocation": false,
        "enableShowPoweredBy": true,
        "enableDisplayChatbotAvatar": true,
        "enableDisplayChatbotName": true,
        "enableDisplayPreviousConversation": true,
        "enableDisplayConversationHistory": true,
        "enableConversationTimer": false,
        "conversationTimerDuration": null,
        "enableAutoNewConversationOnTimeout": false,
        "enableClearConversationOnTimeout": false,
        "accessType": "api",
        "greetings": [],
        "greetingsByLocale": {
          "en": [
            "Hello, how can I help you?"
          ],
          "zh-hant": [
            "你好，我可以幫你什麼嗎？"
          ],
          "ja": [
            "こんにちは、何かお手伝いできますか？"
          ],
          "ko": [
            "안녕하세요, 무엇을 도와드릴까요?"
          ]
        },
        "conversationStarters": [],
        "conversationStartersByLocale": {
          "en": [
            "What can I help you with today?"
          ],
          "zh-hant": [
            "你今天需要什麼幫助？"
          ],
          "ja": [
            "今日は何かお手伝いできますか？"
          ],
          "ko": [
            "오늘 뭘 도와줄수있어？"
          ]
        }
      },
      "webhooks": [],
      "createdAt": "1739519493000",
      "updatedAt": "1739519493000",
      "organization": "24b619d9-e981-4a8b-96da-63dc4f96bda6",
      "signAuth": null
    }
  ]
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### チャットプラットフォームの作成 <a href="#inboxes-create" id="inboxes-create"></a>

POST `/api/v1/inboxes/`

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

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

| フィールド                                         | 型                                                                                                                       | 必須  | 説明                                                                                                                                                                                                           |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name                                          | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| channelType                                   | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい  | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... |
| unreadConversationsCount                      | integer                                                                                                                 | いいえ |                                                                                                                                                                                                              |
| signAuth                                      | object (9 個のプロパティを含む: id, signSource, signParams...)                                                                    | いいえ |                                                                                                                                                                                                              |
| signAuth.signSource                           | string (uuid)                                                                                                           | はい  |                                                                                                                                                                                                              |
| signAuth.signParams                           | object                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak                  | object (3 個のプロパティを含む: clientId, url, realm)                                                                             | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.clientId         | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.url              | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.realm            | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.line                      | object (1 個のプロパティを含む: liffId)                                                                                           | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.line.liffId               | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.ad                        | object (1 個のプロパティを含む: saml)                                                                                             | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.ad.saml                   | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.google                    | object (1 個のプロパティを含む: enabled)                                                                                          | いいえ |                                                                                                                                                                                                              |
| signAuth.signParams.google.enabled            | boolean                                                                                                                 | はい  |                                                                                                                                                                                                              |
| signAuth.sourceIdAccessEnabled                | boolean                                                                                                                 | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.                 |
| signAuth.sourceIdVerifyMode                   | object                                                                                                                  | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...  |
| signAuth.sourceIdSignatureTtlMinutes          | object                                                                                                                  | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15;                     |
| signAuth.keycloakTokenPassthrough             | boolean                                                                                                                 | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...  |
| signAuth.keycloakTokenPassthroughAllowedHosts | array\[string]                                                                                                          | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to                                                                                                             |
| enableAnalysis                                | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                              |

**リクエストスキーマの例**

```typescript
{
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
  }
  "enableAnalysis"?: boolean // 任意
}
```

**リクエストのサンプル値**

```json
{
  "chatbot": {
    "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
  },
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "name": "更新後の名前"
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/inboxes/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  };

axios.post("https://api.maiagent.ai/api/v1/inboxes/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "chatbot": {
        "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "name": "更新後の名前"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/inboxes/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbot' => [
                'id' => '80f3170d-eed7-4651-a8da-6b7e6bdbef8b'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'name' => '更新後の名前'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 201**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "id": string (uuid)
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
    "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
  }
  "enableAnalysis"?: boolean // 任意
  "voiceAgent": object // The voice agent this inbox is the entry of ({id, name, architecture, isDeleted}); null otherwise
}
```

**レスポンスの値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "channelType": "line",
  "unreadConversationsCount": 456,
  "signAuth": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "signSource": "550e8400-e29b-41d4-a716-446655440000",
    "signParams": {
      "keycloak": {
        "clientId": "レスポンス文字列",
        "url": "レスポンス文字列",
        "realm": "レスポンス文字列"
      },
      "line": {
        "liffId": "レスポンス文字列"
      },
      "ad": {
        "saml": "レスポンス文字列"
      },
      "google": {
        "enabled": false
      }
    },
    "sourceIdAccessEnabled": false,
    "sourceIdVerifyMode": {},
    "sourceIdSignatureTtlMinutes": {},
    "keycloakTokenPassthrough": false,
    "keycloakTokenPassthroughAllowedHosts": [
      "レスポンス文字列"
    ],
    "organizationLogin": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "サンプルレスポンス名",
      "description": "サンプルレスポンスの説明"
    }
  },
  "enableAnalysis": false,
  "voiceAgent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "サンプルレスポンス名",
    "description": "サンプルレスポンスの説明"
  }
}
```

**ステータスコード: 4XX - エラーレスポンス。エラーコードは X-Error-Code ヘッダーで返されます（「エラーコード」を参照）。**

***

### 特定のインボックスの取得 <a href="#inboxes-retrieve" id="inboxes-retrieve"></a>

GET `/api/v1/inboxes/{id}/`

#### パラメーター

| パラメーター名 | 必須 | 型      | 説明                                    |
| ------- | -- | ------ | ------------------------------------- |
| `id`    | ✅  | string | A UUID string identifying this Inbox. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "id": string (uuid)
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
    "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
  }
  "enableAnalysis"?: boolean // 任意
  "voiceAgent": object // The voice agent this inbox is the entry of ({id, name, architecture, isDeleted}); null otherwise
}
```

**レスポンスの値の例**

```json
{
  "id": "961dcaac-bd2e-44d3-9050-82596dbb3334",
  "chatbot": {
    "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b",
    "name": "カスタマーサポートボット",
    "groups": [],
    "largeLanguageModel": {
      "id": "933aa8b3-cdf4-47a7-86d5-b5dc27fbb044",
      "name": "llm"
    },
    "embeddingModel": {
      "id": "aefcc4f9-917d-4a8a-bd36-d97e3b7cecfe",
      "name": "embedding",
      "icon": null,
      "isDefault": false
    },
    "rerankerModel": {
      "id": "86c2ddfd-0df9-47b9-8f3b-0c42e3347da3",
      "name": "rerank",
      "icon": null,
      "isDefault": true
    },
    "knowledgeBases": [],
    "tools": [],
    "agentMode": "normal",
    "replyMode": "normal",
    "updatedAt": "1739519493000",
    "enableEvaluation": false,
    "enableInlineCitations": false,
    "enableKnowledgeBaseRag": true,
    "enableAgenticTextToSql": true,
    "enableToolSearching": true,
    "numberOfRetrievedChunks": 12
  },
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "管理者グループ"
    }
  ],
  "channelType": "web",
  "channelTypeLabel": "Web",
  "name": "1345",
  "autoReplySchedules": [
    {
      "id": "2f4f6383-d8b5-4d88-b4a1-6d02d731f2a6",
      "weekday": 0,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Monday"
    },
    {
      "id": "2866f624-a5c3-4ffb-b980-0f8d6a9f0c93",
      "weekday": 1,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Tuesday"
    },
    {
      "id": "3cf1e488-fb13-426d-bd59-e62bd71aca85",
      "weekday": 2,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Wednesday"
    },
    {
      "id": "491776a9-fcf1-4e2e-892f-6d9ad5aebea4",
      "weekday": 3,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Thursday"
    },
    {
      "id": "dfecb0a9-5001-4aa0-b2cc-5459b6d64351",
      "weekday": 4,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Friday"
    },
    {
      "id": "68b6b4d1-7ac8-450f-8877-41b72b499919",
      "weekday": 5,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Saturday"
    },
    {
      "id": "15228ea1-4513-4504-81f4-4e486703d8b9",
      "weekday": 6,
      "isEnabled": true,
      "timeSlots": [
        [
          "00:00:00",
          "00:00:00"
        ]
      ],
      "weekdayName": "Sunday"
    }
  ],
  "unreadConversationsCount": 0,
  "totalConversationsCount": 42,
  "channel": {
    "id": "801a690a-1038-4fdd-8aba-bf003b12c3ef",
    "name": "1345",
    "avatar": "https://media-dev.maiagent.ai/static/images/default-chatbot-avatar.png",
    "logo": null,
    "description": "",
    "cover": null,
    "backUrl": "",
    "isActive": true,
    "enableSpeech": false,
    "displayGreeting": null,
    "displayConversationStarters": [],
    "theme": {
      "primaryColor": "#3854d8",
      "navbarTextColor": "#ffffff",
      "conversationBackgroundColor": "#ffffff",
      "chatbotMessageTextColor": "#374151",
      "userMessageTextColor": "#374151",
      "chatbotMessageBackgroundColor": "#DCE9F6",
      "userMessageBackgroundColor": "#DDEAF6",
      "chatbotMessageBackgroundShadowEnabled": true,
      "userMessageBackgroundShadowEnabled": true
    },
    "darkTheme": {
      "primaryColor": "#404040",
      "navbarTextColor": "#ffffff",
      "conversationBackgroundColor": "#18181B",
      "chatbotMessageTextColor": "#ffffff",
      "userMessageTextColor": "#ffffff",
      "chatbotMessageBackgroundColor": "#171717",
      "userMessageBackgroundColor": "#333842",
      "chatbotMessageBackgroundShadowEnabled": false,
      "userMessageBackgroundShadowEnabled": false
    },
    "enableFileUpload": true,
    "enableDisplayCitations": true,
    "enableShareConversation": false,
    "enableLocation": false,
    "enableShowPoweredBy": true,
    "enableDisplayChatbotAvatar": true,
    "enableDisplayChatbotName": true,
    "enableDisplayPreviousConversation": true,
    "enableDisplayConversationHistory": true,
    "enableConversationTimer": false,
    "conversationTimerDuration": null,
    "enableAutoNewConversationOnTimeout": false,
    "enableClearConversationOnTimeout": false,
    "accessType": "api",
    "greetings": [],
    "greetingsByLocale": {
      "en": [
        "Hello, how can I help you?"
      ],
      "zh-hant": [
        "你好，我可以幫你什麼嗎？"
      ],
      "ja": [
        "こんにちは、何かお手伝いできますか？"
      ],
      "ko": [
        "안녕하세요, 무엇을 도와드릴까요?"
      ]
    },
    "conversationStarters": [],
    "conversationStartersByLocale": {
      "en": [
        "What can I help you with today?"
      ],
      "zh-hant": [
        "你今天需要什麼幫助？"
      ],
      "ja": [
        "今日は何かお手伝いできますか？"
      ],
      "ko": [
        "오늘 뭘 도와줄수있어？"
      ]
    }
  },
  "webhooks": [],
  "createdAt": "1739519493000",
  "updatedAt": "1739519493000",
  "organization": "24b619d9-e981-4a8b-96da-63dc4f96bda6",
  "signAuth": null
}
```

**ステータスコード: 4XX - エラーレスポンス。エラーコードは X-Error-Code ヘッダーで返されます（「エラーコード」を参照）。**

***

### インボックスの更新 <a href="#inboxes-update" id="inboxes-update"></a>

PUT `/api/v1/inboxes/{id}/`

#### パラメーター

| パラメーター名 | 必須 | 型      | 説明                                    |
| ------- | -- | ------ | ------------------------------------- |
| `id`    | ✅  | string | A UUID string identifying this Inbox. |

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

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

| フィールド                                         | 型                                                                                                                       | 必須  | 説明                                                                                                                                                                                                           |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name                                          | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| channelType                                   | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | はい  | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin... |
| unreadConversationsCount                      | integer                                                                                                                 | いいえ |                                                                                                                                                                                                              |
| signAuth                                      | object (9 個のプロパティを含みます: id, signSource, signParams...)                                                                  | いいえ |                                                                                                                                                                                                              |
| signAuth.signSource                           | string (uuid)                                                                                                           | はい  |                                                                                                                                                                                                              |
| signAuth.signParams                           | object                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak                  | object (3 個のプロパティを含みます: clientId, url, realm)                                                                           | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.clientId         | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.url              | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.keycloak.realm            | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.line                      | object (1 個のプロパティを含みます: liffId)                                                                                         | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.line.liffId               | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.ad                        | object (1 個のプロパティを含みます: saml)                                                                                           | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.ad.saml                   | string                                                                                                                  | はい  |                                                                                                                                                                                                              |
| signAuth.signParams.google                    | object (1 個のプロパティを含みます: enabled)                                                                                        | いいえ |                                                                                                                                                                                                              |
| signAuth.signParams.google.enabled            | boolean                                                                                                                 | はい  |                                                                                                                                                                                                              |
| signAuth.sourceIdAccessEnabled                | boolean                                                                                                                 | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.                 |
| signAuth.sourceIdVerifyMode                   | object                                                                                                                  | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...  |
| signAuth.sourceIdSignatureTtlMinutes          | object                                                                                                                  | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15;                     |
| signAuth.keycloakTokenPassthrough             | boolean                                                                                                                 | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...  |
| signAuth.keycloakTokenPassthroughAllowedHosts | array\[string]                                                                                                          | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to                                                                                                             |
| enableAnalysis                                | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                              |

**リクエストスキーマの例**

```typescript
{
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
  }
  "enableAnalysis"?: boolean // 任意
}
```

**リクエストの値の例**

```json
{
  "chatbot": {
    "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
  },
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "name": "更新後の名前"
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストペイロード
const data = {
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  };

axios.put("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストペイロード
data = {
    "chatbot": {
        "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "name": "更新後の名前"
}

response = requests.put(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbot' => [
                'id' => '80f3170d-eed7-4651-a8da-6b7e6bdbef8b'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'name' => '更新後の名前'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "id": string (uuid)
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
    "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
  }
  "enableAnalysis"?: boolean // 任意
  "voiceAgent": object // The voice agent this inbox is the entry of ({id, name, architecture, isDeleted}); null otherwise
}
```

**レスポンスの例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "channelType": "line",
  "unreadConversationsCount": 456,
  "signAuth": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "signSource": "550e8400-e29b-41d4-a716-446655440000",
    "signParams": {
      "keycloak": {
        "clientId": "レスポンス文字列",
        "url": "レスポンス文字列",
        "realm": "レスポンス文字列"
      },
      "line": {
        "liffId": "レスポンス文字列"
      },
      "ad": {
        "saml": "レスポンス文字列"
      },
      "google": {
        "enabled": false
      }
    },
    "sourceIdAccessEnabled": false,
    "sourceIdVerifyMode": {},
    "sourceIdSignatureTtlMinutes": {},
    "keycloakTokenPassthrough": false,
    "keycloakTokenPassthroughAllowedHosts": [
      "レスポンス文字列"
    ],
    "organizationLogin": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンスのサンプル名",
      "description": "レスポンスのサンプル説明"
    }
  },
  "enableAnalysis": false,
  "voiceAgent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンスのサンプル名",
    "description": "レスポンスのサンプル説明"
  }
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 会話プラットフォームの部分更新 <a href="#inboxes-partial-update" id="inboxes-partial-update"></a>

PATCH `/api/v1/inboxes/{id}/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Inbox. |

#### リクエスト内容

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

| フィールド                                         | 型                                                                                                                       | 必須  | 説明                                                                                                                                                                                                               |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| groups                                        | array\[IdName]                                                                                                          | いいえ | この受信トレイにアクセスできるグループの一覧                                                                                                                                                                                           |
| channelType                                   | string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team\_plus, line\_works, viber) | いいえ | `line`: LINE ; `telegram`: Telegram ; `teams`: Teams ; `web`: Web ; `messenger`: Messenger ; `instagram`: Instagram ; `email`: Email ; `whatsapp`: WhatsApp ; `slack`: Slack ; `team_plus`: Team+ ; \`lin...     |
| name                                          | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| autoReplySchedules                            | array\[AutoReplySchedule]                                                                                               | いいえ |                                                                                                                                                                                                                  |
| channel                                       | object                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| organization                                  | string (uuid)                                                                                                           | いいえ |                                                                                                                                                                                                                  |
| signAuth                                      | object (10 個のプロパティ: id, signSource, signParams...)                                                                      | いいえ |                                                                                                                                                                                                                  |
| signAuth.signSource                           | string (uuid)                                                                                                           | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams                           | object                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.keycloak                  | object (3 個のプロパティ: clientId, url, realm)                                                                                | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.keycloak.clientId         | string                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.keycloak.url              | string                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.keycloak.realm            | string                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.line                      | object (1 個のプロパティ: liffId)                                                                                              | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.line.liffId               | string                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.ad                        | object (1 個のプロパティ: saml)                                                                                                | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.ad.saml                   | string                                                                                                                  | はい  |                                                                                                                                                                                                                  |
| signAuth.signParams.google                    | object (1 個のプロパティ: enabled)                                                                                             | いいえ |                                                                                                                                                                                                                  |
| signAuth.signParams.google.enabled            | boolean                                                                                                                 | はい  |                                                                                                                                                                                                                  |
| signAuth.sourceIdAccessEnabled                | boolean                                                                                                                 | いいえ | When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged.                     |
| signAuth.sourceIdVerifyMode                   | object                                                                                                                  | いいえ | "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testin...      |
| signAuth.sourceIdSignatureTtlMinutes          | object                                                                                                                  | いいえ | How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism. `1`: 1 ; `5`: 5 ; `15`: 15;                         |
| signAuth.keycloakTokenPassthrough             | boolean                                                                                                                 | いいえ | When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-to...      |
| signAuth.keycloakTokenPassthroughAllowedHosts | array\[string]                                                                                                          | いいえ | Hostnames (or "\*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to                                                                                                                 |
| enableTimeAwareResponse                       | boolean                                                                                                                 | いいえ | Enable time aware responses for this inbox                                                                                                                                                                       |
| defaultTimezone                               | string                                                                                                                  | いいえ | Default timezone for this inbox (e.g., Asia/Taipei, America/New\_York)                                                                                                                                           |
| enableSenderNameAwareResponse                 | boolean                                                                                                                 | いいえ | Enable sender name aware responses for this inbox                                                                                                                                                                |
| enableGpsAwareResponse                        | boolean                                                                                                                 | いいえ | Enable GPS aware responses for this inbox                                                                                                                                                                        |
| gpsRequestTiming                              | object                                                                                                                  | いいえ | Web chat only. "on\_open" asks the browser for the location as soon as the chat opens (current behavior); "on\_demand" asks only when the AI requests it through an ask\_user\_question question carrying ex...  |
| enableAiLineSticker                           | boolean                                                                                                                 | いいえ | LINE inboxes only. When on, the AI may attach one LINE official sticker to a reply (from the global LINE AI sticker list).                                                                                       |
| enableOcr                                     | boolean                                                                                                                 | いいえ | Retired: attachments pick their parser by content detection (image-heavy files go to the Vision Parser, billed by token; scanned and text files to the MaiAgent Parser, scanned pages billed as OCR) and...      |
| enableAgentAttachmentDecision                 | boolean                                                                                                                 | いいえ | Kill switch for AGENT-mode attachment handling. When False (default), AGENT-mode chatbots skip auto-embedding on upload and let the agent handle attachments at runtime via ParseAttachmentContentTool /...      |
| enableStreamMessage                           | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| enableHumanHandoff                            | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| fullHumanMode                                 | boolean                                                                                                                 | いいえ | When on, every incoming message goes straight to the human queue without the AI: no handoff judgement, no AI reply, no handoff/analysis LLM cost. Requires human handoff. Also works on a platform with ...      |
| silentSkipPhrases                             | array\[any]                                                                                                             | いいえ |                                                                                                                                                                                                                  |
| handoffSkipPhrases                            | array\[any]                                                                                                             | いいえ |                                                                                                                                                                                                                  |
| handoffPrompt                                 | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| handoffLlm                                    | string (uuid)                                                                                                           | いいえ |                                                                                                                                                                                                                  |
| handoffContextMessageLimit                    | integer                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| handoffMessage                                | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| queuingMessage                                | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| assignedMessage                               | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| enablePendingReplyMessage                     | boolean                                                                                                                 | いいえ | Send a placeholder message to the user while the AI is processing.                                                                                                                                               |
| pendingReplyMessage                           | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| pendingReplyInitialDelaySeconds               | integer                                                                                                                 | いいえ | Delay before sending the first pending reply, so a fast AI response can pre-empt it.                                                                                                                             |
| pendingReplyIntervalSeconds                   | integer                                                                                                                 | いいえ | Interval to repeat the pending reply while the AI is still processing.                                                                                                                                           |
| enablePendingReplyCleanup                     | boolean                                                                                                                 | いいえ | Delete pending reply messages after the AI reply is sent. Only effective on platforms that support message deletion (Teams, Telegram, Slack).                                                                    |
| enableAnalysis                                | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| analysisLlm                                   | string (uuid)                                                                                                           | いいえ |                                                                                                                                                                                                                  |
| analysisPrompt                                | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| analysisContextMessageLimit                   | integer                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| analysisGenerateSummary                       | boolean                                                                                                                 | いいえ | When on, conversation analysis writes the conversation summary (editable, with revisions); inbox auto split brings it to the next conversation                                                                   |
| analysisApplyTags                             | boolean                                                                                                                 | いいえ | When on, conversation analysis picks the conversation tags from the inbox tags                                                                                                                                   |
| enableServiceHours                            | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| serviceHoursTimezone                          | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| offlineBehavior                               | string (enum: show\_message, leave\_message)                                                                            | いいえ | `show_message`: Show Message ; `leave_message`: Leave Message;                                                                                                                                                   |
| offlineMessage                                | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| serviceHoursSchedules                         | array\[ServiceHoursSchedule]                                                                                            | いいえ |                                                                                                                                                                                                                  |
| dispatchMode                                  | object                                                                                                                  | いいえ | Auto dispatch assigns transferred conversations to an agent automatically. Claim (handover) leaves them unassigned for online agents to pick up themselves; timeout reassignment does not apply and the ...      |
| assignmentRoutingModel                        | string (enum: round\_robin, least\_active)                                                                              | いいえ | `round_robin`: Round Robin ; `least_active`: Least Active;                                                                                                                                                       |
| assignmentMaxConcurrent                       | integer                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| assignmentQueueTimeout                        | integer                                                                                                                 | いいえ | Queue timeout in seconds                                                                                                                                                                                         |
| queueTimeoutMessage                           | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| maxQueueSize                                  | integer                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| queueFullMessage                              | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| assignmentTargetMembers                       | array\[string]                                                                                                          | いいえ |                                                                                                                                                                                                                  |
| enableTagRouting                              | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| enableReassignOnTimeout                       | boolean                                                                                                                 | いいえ | When on, a queued or assigned-but-unanswered conversation that times out is reassigned to the next available agent (skipping already-tried agents) instead of returning straight to the AI; it only retu...      |
| enableQueueReminder                           | boolean                                                                                                                 | いいえ | Reply with a throttled waiting reminder when the contact sends messages while queued.                                                                                                                            |
| queueReminderMessage                          | string                                                                                                                  | いいえ |                                                                                                                                                                                                                  |
| queueReminderCooldown                         | integer                                                                                                                 | いいえ | Minimum seconds between queue reminders in one conversation                                                                                                                                                      |
| enableQueueCancel                             | boolean                                                                                                                 | いいえ | Allow the contact to cancel a queued handoff and return to the AI by themselves.                                                                                                                                 |
| queueCancelButtonText                         | string                                                                                                                  | いいえ | Label of the cancel quick-reply button. Its text also counts as a cancel keyword, so tapping the button always cancels even when the keyword list changes.                                                       |
| queueCancelKeywords                           | object                                                                                                                  | いいえ | Messages matching one of these exactly (after stripping surrounding whitespace) cancel the queued handoff. Empty means no keyword matching (the cancel button text still matches); the serializer requir...      |
| queueCancelMessage                            | string                                                                                                                  | いいえ | Sent to the contact right after they cancel the queued handoff.                                                                                                                                                  |
| enableIdleAutoResolve                         | boolean                                                                                                                 | いいえ | Resolve a conversation served by a human agent once the agent replied last and the contact has not answered for the idle minutes. Frees the agent slot; queued conversations and ones where the contact ...      |
| idleAutoResolveMinutes                        | integer                                                                                                                 | いいえ | Minutes the contact may stay silent after the last agent reply before auto resolve                                                                                                                               |
| idleAutoResolveMessage                        | string                                                                                                                  | いいえ | Sent to the contact when the conversation is auto resolved; blank sends nothing. LINE delivers it as a push message (counts toward the LINE message quota); Messenger / Instagram / WhatsApp skip it onc...      |
| enableAgentReplyTimeout                       | boolean                                                                                                                 | いいえ | When on, a conversation served by a human agent returns to the AI once a contact message has gone unanswered by any agent for the configured seconds; the AI then answers the last unanswered message. A...      |
| agentReplyTimeout                             | integer                                                                                                                 | いいえ | Seconds (60-86400) a contact message may go unanswered by a human agent before the AI takes over                                                                                                                 |
| agentReplyTimeoutMessage                      | string                                                                                                                  | いいえ | Sent to the contact when the conversation returns to the AI; leave empty to send none.                                                                                                                           |
| enableSatisfactionSurvey                      | boolean                                                                                                                 | いいえ | Send a 1-5 satisfaction survey when a conversation served by a human agent is resolved. Only applies to LINE, Messenger and Instagram inboxes; each LINE survey uses push message quota.                         |
| satisfactionSurveyPrompt                      | string                                                                                                                  | いいえ | Question sent with the 1-5 buttons. Empty uses the default prompt.                                                                                                                                               |
| satisfactionSurveyThanksMessage               | string                                                                                                                  | いいえ | Sent after the contact finishes the survey. Empty uses the default message.                                                                                                                                      |
| satisfactionSurveyFollowUpPrompt              | string                                                                                                                  | いいえ | Asked after a score below 3; the next text is saved as the comment. Empty uses the default.                                                                                                                      |
| enableReturnToPreviousAssignee                | boolean                                                                                                                 | いいえ | When on, a resolved conversation the contact writes to again within the configured hours reopens assigned to the agent who held it instead of to the AI. It still reopens to the AI when that agent is o...      |
| returnToPreviousAssigneeHours                 | integer                                                                                                                 | いいえ | Hours (1-720), counted from when the conversation was resolved, during which a returning contact goes back to the agent who held it                                                                              |
| enableAutoSplit                               | boolean                                                                                                                 | いいえ | When on, a one-to-one contact writing again after the conversation was resolved or went idle for the configured time starts a new conversation instead of continuing the old one. Web inboxes and group ...      |
| autoSplitOnResolve                            | boolean                                                                                                                 | いいえ | Split when the latest conversation was resolved more than the configured minutes ago                                                                                                                             |
| autoSplitResolveMinutes                       | integer                                                                                                                 | いいえ | Minutes (0-10080) after the latest resolve; 0 splits on the next contact message                                                                                                                                 |
| autoSplitOnIdle                               | boolean                                                                                                                 | いいえ | Split when the last message of the latest conversation is older than the configured hours, unless a human agent is serving it or it is queued                                                                    |
| autoSplitIdleHours                            | integer                                                                                                                 | いいえ | Hours (1-720) since the last message of the latest conversation                                                                                                                                                  |
| enableContinuationSummary                     | boolean                                                                                                                 | いいえ | When on, a conversation started by auto split gives its AI the previous conversations' analysis summaries; a previous conversation without a current summary gets one from conversation analysis (one bi...      |
| continuationSummaryCount                      | integer                                                                                                                 | いいえ | How many previous conversations (1-3) a new conversation looks back at for summaries                                                                                                                             |
| copilotEnabled                                | boolean                                                                                                                 | いいえ |                                                                                                                                                                                                                  |
| copilotTriggerMode                            | string (enum: manual, every\_incoming)                                                                                  | いいえ | `manual`: Manual ; `every_incoming`: Every Incoming;                                                                                                                                                             |
| quotaExceededMessage                          | string                                                                                                                  | いいえ | Custom message sent to the visitor when the inbox credit quota is exhausted. Used as the fallback when `quota_exceeded_message_by_locale` has no match for the conversation locale. Empty means the syst...      |
| quotaExceededMessageByLocale                  | object                                                                                                                  | いいえ | Locale-keyed quota-exceeded messages. A dict mapping normalized locale codes from CHAT\_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to \`q...    |
| creditSuspendedMessage                        | string                                                                                                                  | いいえ | Custom message sent to the visitor when the AI auto-reply is suspended because the organization has run out of credits or has no active plan. Used as the fallback when \`credit\_suspended\_message\_by\_loc... |
| creditSuspendedMessageByLocale                | object                                                                                                                  | いいえ | Locale-keyed credit-suspended messages. A dict mapping normalized locale codes from CHAT\_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to ...     |
| voiceEntry                                    | object (8 個のプロパティ: isActive, voiceUrl, usesGreeting...)                                                                 | いいえ | A voice inbox's entry switch, voice link and greetings (decision 50); null for other inboxes. Rendered by retrieve and update only.                                                                              |
| voiceEntry.isActive                           | boolean                                                                                                                 | いいえ | The voice entry switch (the VOICE web chat); off refuses new calls only.                                                                                                                                         |
| voiceEntry.greetings                          | array\[string]                                                                                                          | いいえ | The voice agent's greetings, one picked at random per call.                                                                                                                                                      |
| voiceEntry.greetingsByLocale                  | object                                                                                                                  | いいえ | The voice agent's greetings by locale.                                                                                                                                                                           |

**リクエスト構造の例**

```typescript
{
  "groups"?: [ // この受信トレイにアクセスできるグループの一覧 (任意)
    {
      "id": string (uuid)
    }
  ]
  "channelType"?: string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber (任意)
  "name"?: string // 任意
  "autoReplySchedules"?: [ // 任意
    {
      "isEnabled"?: boolean // 任意
      "timeSlots"?: [ // 任意
        array[string]
      ]
    }
  ]
  "channel"?: // 異なる型の場合があります (任意)
  {
    "avatar"?: string (uri) // 任意
    "logo"?: string (uri) // 任意
    "description"?: string // 任意
    "cover"?: string (uri) // 任意
    "backUrl"?: string // 任意
    "isActive"?: boolean // 任意
    "speechPhrases"?: [ // Proper nouns the speech input boosts as an Azure phrase list. Entries are trimmed; blank and duplicate entries are dropped; at most 500 entries of 100 characters. Empty means no phrase is boosted. (任意)
      string
    ]
    "theme": {
    {
      "primaryColor"?: string // 任意
      "navbarTextColor"?: string // 任意
      "conversationBackgroundColor"?: string // 任意
      "chatbotMessageTextColor"?: string // 任意
      "userMessageTextColor"?: string // 任意
      "chatbotMessageBackgroundColor"?: string // 任意
      "userMessageBackgroundColor"?: string // 任意
      "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意
      "userMessageBackgroundShadowEnabled"?: boolean // 任意
      "chatbotMessageGradientEnabled"?: boolean // 任意
      "userMessageGradientEnabled"?: boolean // 任意
    }
    }
    "darkTheme": {
    {
      "primaryColor"?: string // 任意
      "navbarTextColor"?: string // 任意
      "conversationBackgroundColor"?: string // 任意
      "chatbotMessageTextColor"?: string // 任意
      "userMessageTextColor"?: string // 任意
      "chatbotMessageBackgroundColor"?: string // 任意
      "userMessageBackgroundColor"?: string // 任意
      "chatbotMessageBackgroundShadowEnabled"?: boolean // 任意
      "userMessageBackgroundShadowEnabled"?: boolean // 任意
      "chatbotMessageGradientEnabled"?: boolean // 任意
      "userMessageGradientEnabled"?: boolean // 任意
    }
    }
    "enableFileUpload"?: boolean // 任意
    "enableDisplayCitations"?: boolean // 任意
    "toolDisplayMode"?: string (enum: full, compact, hidden) // * `full` - Full
* `compact` - Compact
* `hidden` - Hidden (任意)
    "enableAskOptionButtons"?: boolean // When on, ask_user_question options float as a button row above the input box (the input stays usable); when off, the current overlay panel stays. A gradual-rollout switch that can be turned off any time to roll back. (任意)
    "enableConversationHandoff"?: boolean // When on, the web chat of this platform shows the handoff UI (hint bar, summary card, continue button) and registers the handoff tools; still gated by the global handoff switch in system settings (global off means always off). MaiGPT always shows it without this switch. The context usage bar at the bottom is controlled separately by "Show context usage". Off by default, so customer-facing web chats show no handoff UI; a gradual-rollout switch: turning it off rolls back without a redeploy. (任意)
    "enableDisplayContextUsage"?: boolean // When on, the web chat of this platform shows a context usage percentage bar below the input box. Independent of conversation handoff: not affected by the handoff switches (including the global one), and does not affect the handoff hint bar. MaiGPT always shows it without this switch. Off by default; turning it off rolls back without a redeploy. (任意)
    "enableDisplayThinking"?: boolean // 任意
    "enableUserThinkingControl"?: boolean // 任意
    "enableDisplayQueryMetadata"?: boolean // 任意
    "enableDisplayHookMarkers"?: boolean // 任意
    "hookMarkerTextInputModify"?: string // 任意
    "hookMarkerTextOutputModify"?: string // 任意
    "hookMarkerTextInputBlock"?: string // 任意
    "hookMarkerTextOutputBlock"?: string // 任意
    "enableShareConversation"?: boolean // 任意
    "enableShowConnectedServices"?: boolean // 任意
    "enableLocation"?: boolean // 任意
    "enableShowPoweredBy"?: boolean // 任意
    "poweredByLogo"?: string (uri) // 任意
    "enableAnonymous"?: boolean // 任意
    "enableDisplayPreviousConversation"?: boolean // 任意
    "enableDisplayConversationHistory"?: boolean // 任意
    "enableConversationTimer"?: boolean // 任意
    "conversationTimerDuration"?: integer // タイマーのタイムアウト時間。範囲は 3〜60 分 (任意)
    "enableAutoNewConversationOnTimeout"?: boolean // 任意
    "enableClearConversationOnTimeout"?: boolean // Only takes effect when "Start a new conversation on timeout" is on (the web chat shows the timeout prompt instead of resetting directly): on timeout the chat is masked and the conversation is cleared, and the user must confirm to start a new one; refreshing the page does not show the previous conversation either (任意)
    "enableSatisfactionSurvey"?: boolean // 任意
    "satisfactionSurveyDelayMinutes"?: integer // Minutes after the last AI reply before the survey pops up, 1-60 minutes (任意)
    "satisfactionSurveyPrompt"?: string // Custom survey title text; leave empty to use the localized default text of the front end (任意)
    "enableThemeModeToggle"?: boolean // 任意
    "enableDisplayFontSizeSwitch"?: boolean // 任意
    "defaultThemeMode"?:  // 任意
    {
    }
    "enableDownloadCitations"?: boolean // 任意
    "customDomain"?:  // 任意
    {
      "domain": string
    }
    "enableDisplayChatbotAvatar"?: boolean // 任意
    "enableDisplayChatbotName"?: boolean // 任意
    "buttonIcon"?: string (uri) // 任意
    "conversationStartersDisplayCount"?: integer // 任意
    "includeGreetingInContext"?: boolean // When enabled, the conversation greeting and the numbered conversation starters (in configured order, unshuffled and untruncated) are injected into the LLM context so the agent can resolve short replies like "1" to the matching starter option. (任意)
    "preChatFormEnabled"?: boolean // 任意
    "preChatFormFields"?: object // 任意
    "preChatFormTitle"?: object // 任意
    "preChatFormSubtitle"?: object // 任意
    "loadingDisplayMode"?:  // Waiting-experience style. `narrative` shows per-stage copy; `brand_animation` plays the uploaded asset and hides every system narration line. Defaults to `narrative`, which with no copy configured behaves exactly as before this field existed.

* `narrative` - Narrative copy
* `brand_animation` - Brand animation (任意)
    {
    }
    "loadingStageCopyByLocale"?: object // Locale-keyed per-stage waiting copy, shaped {locale: {stage: text}} where stage is one of LoadingStage. An absent locale or stage falls back to the built-in copy, so a partially filled dict is valid and never blocks a reply. (任意)
    "loadingLongWaitCopyByLocale"?: object // Locale-keyed line shown once the wait exceeds `loading_long_wait_threshold_seconds`, shaped {locale: text}. Written in the brand character voice for the animation mode, but applies to both modes. Empty means no long-wait line is shown. (任意)
    "loadingLongWaitThresholdSeconds"?: integer // How long a single reply must be pending before the long-wait copy appears. (任意)
    "loadingAnimationUseSharedAsset"?: boolean // True (default) means every stage plays `loading_animation_shared_asset_url`, so the admin only uploads once. False expands per-stage assets, each falling back to the shared asset when its own slot is empty. (任意)
    "loadingAnimationSharedAssetUrl"?: string (uri) // 任意
    "loadingAnimationAssetUrlsByStage"?: object // Shaped {stage: url} keyed by LoadingStage. Only consulted when `loading_animation_use_shared_asset` is False; a missing stage falls back to the shared asset. (任意)
    "loadingTypingShowCopy"?: boolean // Only affects the first "typing" stage. True (default, the pre-existing behavior) shows the typing-stage copy next to the pre-first-char animation/dot; False plays only the animation with no text line. Thinking / analyzing / long-wait stages are unaffected. (任意)
    "toolCardRunningIconUrl"?: string (uri) // 任意
    "toolCardCompletedIconUrl"?: string (uri) // 任意
    "greetings"?: [ // Default greeting messages shown as the AI first message when a new conversation starts. One message is randomly selected per conversation. Used as the fallback when `greetings_by_locale` has no match for the request locale. (任意)
      string
    ]
    "greetingsByLocale"?: object // Locale-keyed greetings. A dict mapping locale codes to a list of greeting strings (e.g. keys like "en", "zh-TW", "ja"). Selected by the conversation request Accept-Language header; falls back to `greetings` when no locale matches. (任意)
    "voiceGreetings"?: [ // Greeting messages spoken aloud when a voice session starts. One message is randomly selected per session. The spoken greeting is ephemeral and NOT written back to conversation history. Used as the fallback when `voice_greetings_by_locale` has no match for the request locale. (任意)
      string
    ]
    "voiceGreetingsByLocale"?: object // Locale-keyed voice greetings. A dict mapping locale codes to a list of greeting strings. Selected by the Accept-Language header; falls back to `voice_greetings` when no locale matches. (任意)
    "conversationStarters"?: [ // Default suggested questions shown to the end-user as clickable prompts at the start of a conversation. Used as the fallback when `conversation_starters_by_locale` has no match for the request locale. (任意)
      string
    ]
    "conversationStartersByLocale"?: object // Locale-keyed conversation starters. A dict mapping locale codes to a list of starter strings (e.g. keys like "en", "zh-TW", "ja"). Selected by the Accept-Language header; falls back to `conversation_starters` when no locale matches. (任意)
    "allowedEmbedOrigins"?: [ // Origins allowed to embed this web chat and call the SDK contact-setup endpoint. Each entry is either an exact origin (scheme://host[:port], e.g. https://example.com) or a wildcard (*.example.com) that matches example.com and all of its subdomains on any scheme/port. An empty list means no restriction. Validated against the embedding page origin forwarded by the web chat frontend; bounds unauthorized-domain embedding. Browser-level enforcement (CSP frame-ancestors on the entry page) additionally requires an AWS/CloudFront deployment; on GCP storage the allowlist is enforced by the API alone. WARNING: leave empty until the web chat frontend forwards the embedding origin, otherwise setup calls fall back to the web chat host origin and every request is rejected. (任意)
      string
    ]
  }
  "organization"?: string (uuid) // 任意
  "signAuth"?:  // 任意
  {
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
  }
  "enableTimeAwareResponse"?: boolean // Enable time aware responses for this inbox (任意)
  "defaultTimezone"?: string // Default timezone for this inbox (e.g., Asia/Taipei, America/New_York) (任意)
  "enableSenderNameAwareResponse"?: boolean // Enable sender name aware responses for this inbox (任意)
  "enableGpsAwareResponse"?: boolean // Enable GPS aware responses for this inbox (任意)
  "gpsRequestTiming"?:  // Web chat only. "on_open" asks the browser for the location as soon as the chat opens (current behavior); "on_demand" asks only when the AI requests it through an ask_user_question question carrying extra_params.requestLocation. LINE always offers a share-location quick reply regardless of this value.

* `on_open` - Ask when the chat opens
* `on_demand` - Ask only when the AI needs it (任意)
  {
  }
  "enableAiLineSticker"?: boolean // LINE inboxes only. When on, the AI may attach one LINE official sticker to a reply (from the global LINE AI sticker list). (任意)
  "enableOcr"?: boolean // Retired: attachments pick their parser by content detection (image-heavy files go to the Vision Parser, billed by token; scanned and text files to the MaiAgent Parser, scanned pages billed as OCR) and this switch has no effect. (任意)
  "enableAgentAttachmentDecision"?: boolean // Kill switch for AGENT-mode attachment handling. When False (default), AGENT-mode chatbots skip auto-embedding on upload and let the agent handle attachments at runtime via ParseAttachmentContentTool / IngestAttachmentTool. When True, AGENT-mode chatbots fall back to auto-embedding chat attachments into the knowledge base on upload, same as non-AGENT modes. Has no effect on non-AGENT chatbot modes (they always auto-embed). (任意)
  "enableStreamMessage"?: boolean // 任意
  "enableHumanHandoff"?: boolean // 任意
  "fullHumanMode"?: boolean // When on, every incoming message goes straight to the human queue without the AI: no handoff judgement, no AI reply, no handoff/analysis LLM cost. Requires human handoff. Also works on a platform with no assistant attached. (任意)
  "silentSkipPhrases"?: [ // 任意
    object
  ]
  "handoffSkipPhrases"?: [ // 任意
    object
  ]
  "handoffPrompt"?: string // 任意
  "handoffLlm"?: string (uuid) // 任意
  "handoffContextMessageLimit"?: integer // 任意
  "handoffMessage"?: string // 任意
  "queuingMessage"?: string // 任意
  "assignedMessage"?: string // 任意
  "enablePendingReplyMessage"?: boolean // Send a placeholder message to the user while the AI is processing. (任意)
  "pendingReplyMessage"?: string // 任意
  "pendingReplyInitialDelaySeconds"?: integer // Delay before sending the first pending reply, so a fast AI response can pre-empt it. (任意)
  "pendingReplyIntervalSeconds"?: integer // Interval to repeat the pending reply while the AI is still processing. (任意)
  "enablePendingReplyCleanup"?: boolean // Delete pending reply messages after the AI reply is sent. Only effective on platforms that support message deletion (Teams, Telegram, Slack). (任意)
  "enableAnalysis"?: boolean // 任意
  "analysisLlm"?: string (uuid) // 任意
  "analysisPrompt"?: string // 任意
  "analysisContextMessageLimit"?: integer // 任意
  "analysisGenerateSummary"?: boolean // When on, conversation analysis writes the conversation summary (editable, with revisions); inbox auto split brings it to the next conversation (任意)
  "analysisApplyTags"?: boolean // When on, conversation analysis picks the conversation tags from the inbox tags (任意)
  "enableServiceHours"?: boolean // 任意
  "serviceHoursTimezone"?: string // 任意
  "offlineBehavior"?: string (enum: show_message, leave_message) // * `show_message` - Show Message
* `leave_message` - Leave Message (任意)
  "offlineMessage"?: string // 任意
  "serviceHoursSchedules"?: [ // 任意
    {
      "weekday": integer
      "startTime": string (time)
      "endTime": string (time)
      "isEnabled"?: boolean // 任意
    }
  ]
  "dispatchMode"?:  // Auto dispatch assigns transferred conversations to an agent automatically. Claim (handover) leaves them unassigned for online agents to pick up themselves; timeout reassignment does not apply and the queue timeout may be set to "no timeout".

* `auto` - Auto Dispatch
* `handover` - Claim (Handover) (任意)
  {
  }
  "assignmentRoutingModel"?: string (enum: round_robin, least_active) // * `round_robin` - Round Robin
* `least_active` - Least Active (任意)
  "assignmentMaxConcurrent"?: integer // 任意
  "assignmentQueueTimeout"?: integer // Queue timeout in seconds (任意)
  "queueTimeoutMessage"?: string // 任意
  "maxQueueSize"?: integer // 任意
  "queueFullMessage"?: string // 任意
  "assignmentTargetMembers"?: [ // 任意
    string (uuid)
  ]
  "enableTagRouting"?: boolean // 任意
  "enableReassignOnTimeout"?: boolean // When on, a queued or assigned-but-unanswered conversation that times out is reassigned to the next available agent (skipping already-tried agents) instead of returning straight to the AI; it only returns to the AI once no agent is left to try. (任意)
  "enableQueueReminder"?: boolean // Reply with a throttled waiting reminder when the contact sends messages while queued. (任意)
  "queueReminderMessage"?: string // 任意
  "queueReminderCooldown"?: integer // Minimum seconds between queue reminders in one conversation (任意)
  "enableQueueCancel"?: boolean // Allow the contact to cancel a queued handoff and return to the AI by themselves. (任意)
  "queueCancelButtonText"?: string // Label of the cancel quick-reply button. Its text also counts as a cancel keyword, so tapping the button always cancels even when the keyword list changes. (任意)
  "queueCancelKeywords"?: object // Messages matching one of these exactly (after stripping surrounding whitespace) cancel the queued handoff. Empty means no keyword matching (the cancel button text still matches); the serializer requires at least one keyword while queue cancel is enabled. (任意)
  "queueCancelMessage"?: string // Sent to the contact right after they cancel the queued handoff. (任意)
  "enableIdleAutoResolve"?: boolean // Resolve a conversation served by a human agent once the agent replied last and the contact has not answered for the idle minutes. Frees the agent slot; queued conversations and ones where the contact spoke last are never resolved. (任意)
  "idleAutoResolveMinutes"?: integer // Minutes the contact may stay silent after the last agent reply before auto resolve (任意)
  "idleAutoResolveMessage"?: string // Sent to the contact when the conversation is auto resolved; blank sends nothing. LINE delivers it as a push message (counts toward the LINE message quota); Messenger / Instagram / WhatsApp skip it once the contact last wrote more than 24 hours ago. (任意)
  "enableAgentReplyTimeout"?: boolean // When on, a conversation served by a human agent returns to the AI once a contact message has gone unanswered by any agent for the configured seconds; the AI then answers the last unanswered message. Auto-dispatched conversations the agent has not answered yet are left to timeout reassignment while that is enabled. (任意)
  "agentReplyTimeout"?: integer // Seconds (60-86400) a contact message may go unanswered by a human agent before the AI takes over (任意)
  "agentReplyTimeoutMessage"?: string // Sent to the contact when the conversation returns to the AI; leave empty to send none. (任意)
  "enableSatisfactionSurvey"?: boolean // Send a 1-5 satisfaction survey when a conversation served by a human agent is resolved. Only applies to LINE, Messenger and Instagram inboxes; each LINE survey uses push message quota. (任意)
  "satisfactionSurveyPrompt"?: string // Question sent with the 1-5 buttons. Empty uses the default prompt. (任意)
  "satisfactionSurveyThanksMessage"?: string // Sent after the contact finishes the survey. Empty uses the default message. (任意)
  "satisfactionSurveyFollowUpPrompt"?: string // Asked after a score below 3; the next text is saved as the comment. Empty uses the default. (任意)
  "enableReturnToPreviousAssignee"?: boolean // When on, a resolved conversation the contact writes to again within the configured hours reopens assigned to the agent who held it instead of to the AI. It still reopens to the AI when that agent is offline, paused, off duty, no longer an active member with access to this inbox, or the inbox is outside its service hours. (任意)
  "returnToPreviousAssigneeHours"?: integer // Hours (1-720), counted from when the conversation was resolved, during which a returning contact goes back to the agent who held it (任意)
  "enableAutoSplit"?: boolean // When on, a one-to-one contact writing again after the conversation was resolved or went idle for the configured time starts a new conversation instead of continuing the old one. Web inboxes and group conversations are never split; a returning contact handed back to the previous assignee stays. (任意)
  "autoSplitOnResolve"?: boolean // Split when the latest conversation was resolved more than the configured minutes ago (任意)
  "autoSplitResolveMinutes"?: integer // Minutes (0-10080) after the latest resolve; 0 splits on the next contact message (任意)
  "autoSplitOnIdle"?: boolean // Split when the last message of the latest conversation is older than the configured hours, unless a human agent is serving it or it is queued (任意)
  "autoSplitIdleHours"?: integer // Hours (1-720) since the last message of the latest conversation (任意)
  "enableContinuationSummary"?: boolean // When on, a conversation started by auto split gives its AI the previous conversations' analysis summaries; a previous conversation without a current summary gets one from conversation analysis (one billed model call on that conversation). Needs conversation analysis with its summary on. (任意)
  "continuationSummaryCount"?: integer // How many previous conversations (1-3) a new conversation looks back at for summaries (任意)
  "copilotEnabled"?: boolean // 任意
  "copilotTriggerMode"?: string (enum: manual, every_incoming) // * `manual` - Manual
* `every_incoming` - Every Incoming (任意)
  "quotaExceededMessage"?: string // Custom message sent to the visitor when the inbox credit quota is exhausted. Used as the fallback when `quota_exceeded_message_by_locale` has no match for the conversation locale. Empty means the system default message is used. (任意)
  "quotaExceededMessageByLocale"?: object // Locale-keyed quota-exceeded messages. A dict mapping normalized locale codes from CHAT_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to `quota_exceeded_message`. (任意)
  "creditSuspendedMessage"?: string // Custom message sent to the visitor when the AI auto-reply is suspended because the organization has run out of credits or has no active plan. Used as the fallback when `credit_suspended_message_by_locale` has no match for the conversation locale. The same text is used whether or not the conversation is handed to a human, so on an inbox without human handoff it should not promise a human reply. Empty means the system default message is used (which promises a human reply only when the conversation was handed to the human queue). (任意)
  "creditSuspendedMessageByLocale"?: object // Locale-keyed credit-suspended messages. A dict mapping normalized locale codes from CHAT_LANGUAGES (e.g. "en", "zh-hant", "ja") to a message string. Selected by the conversation locale; falls back to `credit_suspended_message`. (任意)
  "voiceEntry"?:  // A voice inbox's entry switch, voice link and greetings (decision 50); null for other inboxes. Rendered by retrieve and update only. (任意)
  {
    "isActive"?: boolean // The voice entry switch (the VOICE web chat); off refuses new calls only. (任意)
    "greetings"?: [ // The voice agent's greetings, one picked at random per call. (任意)
      string
    ]
    "greetingsByLocale"?: object // The voice agent's greetings by locale. (任意)
  }
}
```

**リクエストのサンプル値**

```json
{
  "chatbot": {
    "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
  },
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "name": "更新後の名前"
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストのペイロード
const data = {
    "chatbot": {
      "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "name": "更新後の名前"
  };

axios.patch("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストのペイロード
data = {
    "chatbot": {
        "id": "80f3170d-eed7-4651-a8da-6b7e6bdbef8b"
    },
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "name": "更新後の名前"
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'chatbot' => [
                'id' => '80f3170d-eed7-4651-a8da-6b7e6bdbef8b'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'name' => '更新後の名前'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
  "unreadConversationsCount"?: integer // 任意
  "signAuth"?:  // 任意
  {
    "id": string (uuid)
    "signSource": string (uuid)
    "signParams": {
    {
      "keycloak": 
      {
        "clientId": string
        "url": string
        "realm": string
      }
      "line": 
      {
        "liffId": string
      }
      "ad": 
      {
        "saml": string
      }
      "google"?:  // 任意
      {
        "enabled": boolean
      }
    }
    }
    "sourceIdAccessEnabled"?: boolean // When enabled, embedded visitors presenting a Source ID (verified per the verify mode below) may chat without going through the login flow. Disabled keeps every existing behavior unchanged. (任意)
    "sourceIdVerifyMode"?:  // "Require signature verification": the embedding site must send an HMAC signature computed on its backend. "Source ID only": anyone knowing a Source ID can act as that contact; suitable only for testing or closed networks.

* `signature` - Require signature verification
* `raw` - Source ID only (任意)
    {
    }
    "sourceIdSignatureTtlMinutes"?:  // How long a signature can be used to obtain the contact identity. Not a session lifetime: once exchanged, the session follows the existing WebChat mechanism.

* `1` - 1
* `5` - 5
* `15` - 15 (任意)
    {
    }
    "keycloakTokenPassthrough"?: boolean // When enabled, the Keycloak access token a visitor logged in with is forwarded as the Authorization header when the AI calls MCP and API tools on their behalf, so tools do not require a separate per-tool login. Only for the Keycloak sign source. Never overrides an Authorization header a tool already resolves from its own credentials. The visitor identity is the organization member bound to the conversation at login, never the contact Source ID. (任意)
    "keycloakTokenPassthroughAllowedHosts"?: [ // Hostnames (or "*.example.com" wildcards) of the tools the visitor Keycloak token may be sent to (任意)
      string
    ]
    "organizationLogin": object // How visitors sign in when the sign source is "organization" (mirrors the back-office login); null for other sign sources
  }
  "enableAnalysis"?: boolean // 任意
  "voiceAgent": object // The voice agent this inbox is the entry of ({id, name, architecture, isDeleted}); null otherwise
}
```

**レスポンスのサンプル値**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "channelType": "line",
  "unreadConversationsCount": 456,
  "signAuth": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "signSource": "550e8400-e29b-41d4-a716-446655440000",
    "signParams": {
      "keycloak": {
        "clientId": "レスポンス文字列",
        "url": "レスポンス文字列",
        "realm": "レスポンス文字列"
      },
      "line": {
        "liffId": "レスポンス文字列"
      },
      "ad": {
        "saml": "レスポンス文字列"
      },
      "google": {
        "enabled": false
      }
    },
    "sourceIdAccessEnabled": false,
    "sourceIdVerifyMode": {},
    "sourceIdSignatureTtlMinutes": {},
    "keycloakTokenPassthrough": false,
    "keycloakTokenPassthroughAllowedHosts": [
      "レスポンス文字列"
    ],
    "organizationLogin": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンスのサンプル名",
      "description": "レスポンスのサンプル説明"
    }
  },
  "enableAnalysis": false,
  "voiceAgent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンスのサンプル名",
    "description": "レスポンスのサンプル説明"
  }
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### 受信トレイの削除 <a href="#inboxes-destroy" id="inboxes-destroy"></a>

DELETE `/api/v1/inboxes/{id}/`

#### パラメーター

| パラメーター名 | 必須 | 型      | 説明                                    |
| ------- | -- | ------ | ------------------------------------- |
| `id`    | ✅  | string | A UUID string identifying this Inbox. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// リクエストボディ (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

| ステータスコード | 説明                                                                 |
| -------- | ------------------------------------------------------------------ |
| 204      | No response body                                                   |
| 4XX      | Error response; X-Error-Code carries its code (see "Error codes"). |

***

### 受信トレイの Webhook 一覧取得 <a href="#inboxes-webhooks-list" id="inboxes-webhooks-list"></a>

GET `/api/v1/inboxes/{inboxPk}/webhooks/`

#### パラメーター

| パラメーター名    | 必須 | 型       | 説明                                             |
| ---------- | -- | ------- | ---------------------------------------------- |
| `inboxPk`  | ✅  | string  |                                                |
| `page`     | ❌  | integer | A page number within the paginated result set. |
| `pageSize` | ❌  | integer | Number of results to return per page.          |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/?page=1&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/?page=1&pageSize=1", config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/?page=1&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "inbox": string (uuid)
      "name": string // Webhook configuration name for identification
      "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
      {
      }
      "directionLabel": string
      "isEnabled"?: boolean // 任意
      "url": string (uri)
      "method"?:  // 任意
      {
      }
      "headersMasked": object
      "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
      "templatePresetLabel": string
      "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
      "payloadPreset"?: // 異なる型の場合があります (任意)
      string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
      "payloadPresetLabel": string
      "receiveUrl": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
}
```

**レスポンスの値の例**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inbox": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "direction": {},
      "directionLabel": "レスポンス文字列",
      "isEnabled": false,
      "url": "https://example.com/file.jpg",
      "method": {},
      "headersMasked": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "サンプルレスポンス名",
        "description": "サンプルレスポンスの説明"
      },
      "templatePreset": "maiagent_standard",
      "templatePresetLabel": "レスポンス文字列",
      "customTemplate": "レスポンス文字列",
      "payloadPreset": "genesys_cloud",
      "payloadPresetLabel": "レスポンス文字列",
      "receiveUrl": "レスポンス文字列",
      "createdAt": "レスポンス文字列",
      "updatedAt": "レスポンス文字列"
    }
  ]
}
```

**ステータスコード: 4XX - エラーレスポンス。エラーコードは X-Error-Code ヘッダーで返されます（「エラーコード」を参照）。**

***

### Webhook の作成 <a href="#inboxes-webhooks-create" id="inboxes-webhooks-create"></a>

POST `/api/v1/inboxes/{inboxPk}/webhooks/`

{% hint style="info" %}
`direction` には `incoming`（ユーザーメッセージの受信時に発火）または `outgoing`（Agent の返信時に発火）を指定します。`template_preset` に `maiagent_standard` を選択すると、MaiAgent 標準の payload を使用します。
{% endhint %}

#### パラメーター

| パラメーター名   | 必須 | 型      | 説明 |
| --------- | -- | ------ | -- |
| `inboxPk` | ✅  | string |    |

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

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

| フィールド          | 型                                                         | 必須  | 説明                                                                                                                                    |
| -------------- | --------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name           | string                                                    | はい  | Webhook configuration name for identification                                                                                         |
| direction      | object                                                    | はい  | When to trigger: incoming (user messages) or outgoing (bot replies) `incoming`: Incoming ; `outgoing`: Outgoing ; `receive`: Receive; |
| isEnabled      | boolean                                                   | いいえ |                                                                                                                                       |
| url            | string (uri)                                              | いいえ |                                                                                                                                       |
| method         | object                                                    | いいえ |                                                                                                                                       |
| headers        | object                                                    | いいえ | Custom HTTP headers as JSON object                                                                                                    |
| templatePreset | string (enum: maiagent\_standard, genesys\_cloud, custom) | いいえ | `maiagent_standard`: MaiAgent Standard ; `genesys_cloud`: Genesys Cloud ; `custom`: Custom;                                           |
| customTemplate | string                                                    | いいえ | Jinja2 template for custom payload format. Required when template\_preset is "custom".                                                |
| secretToken    | string                                                    | いいえ | Secret token for webhook signature verification                                                                                       |
| payloadPreset  | object                                                    | いいえ | Preset for parsing incoming webhook payloads (used with direction=receive) `genesys_cloud`: Genesys Cloud;                            |

**リクエストスキーマの例**

```typescript
{
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "isEnabled"?: boolean // 任意
  "url"?: string (uri) // 任意
  "method"?:  // 任意
  {
  }
  "headers"?: object // Custom HTTP headers as JSON object (任意)
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "secretToken"?: string // Secret token for webhook signature verification (任意)
  "payloadPreset"?: // 異なる型の場合があります (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
}
```

**リクエストの値の例**

```json
{
  "name": "サンプル名",
  "direction": {},
  "isEnabled": true,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headers": null,
  "templatePreset": "maiagent_standard",
  "customTemplate": "サンプル文字列",
  "secretToken": "サンプル文字列",
  "payloadPreset": null
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サンプル名",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "サンプル文字列",
    "secretToken": "サンプル文字列",
    "payloadPreset": null
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "サンプル名",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "サンプル文字列",
    "secretToken": "サンプル文字列",
    "payloadPreset": null
  };

axios.post("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/", data, config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "サンプル名",
    "direction": {},
    "isEnabled": True,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": None,
    "templatePreset": "maiagent_standard",
    "customTemplate": "サンプル文字列",
    "secretToken": "サンプル文字列",
    "payloadPreset": None
}

response = requests.post(url, json=data, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => 'サンプル名',
            'direction' => new \stdClass(),
            'isEnabled' => true,
            'url' => 'https://example.com/file.jpg',
            'method' => new \stdClass(),
            'headers' => null,
            'templatePreset' => 'maiagent_standard',
            'customTemplate' => 'サンプル文字列',
            'secretToken' => 'サンプル文字列',
            'payloadPreset' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 201**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "inbox": string (uuid)
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "directionLabel": string
  "isEnabled"?: boolean // 任意
  "url": string (uri)
  "method"?:  // 任意
  {
  }
  "headersMasked": object
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "templatePresetLabel": string
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "payloadPreset"?: // 異なる型の場合があります (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
  "payloadPresetLabel": string
  "receiveUrl": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**レスポンスの値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "direction": {},
  "directionLabel": "レスポンス文字列",
  "isEnabled": false,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "サンプルレスポンス名",
    "description": "サンプルレスポンスの説明"
  },
  "templatePreset": "maiagent_standard",
  "templatePresetLabel": "レスポンス文字列",
  "customTemplate": "レスポンス文字列",
  "payloadPreset": "genesys_cloud",
  "payloadPresetLabel": "レスポンス文字列",
  "receiveUrl": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列"
}
```

**ステータスコード: 4XX - エラーレスポンス。エラーコードは X-Error-Code ヘッダーで返されます（「エラーコード」を参照）。**

***

### 特定の Webhook の取得 <a href="#inboxes-webhooks-retrieve" id="inboxes-webhooks-retrieve"></a>

GET `/api/v1/inboxes/{inboxPk}/webhooks/{id}/`

#### パラメーター

| パラメーター名   | 必須 | 型      | 説明                                            |
| --------- | -- | ------ | --------------------------------------------- |
| `id`      | ✅  | string | A UUID string identifying this Inbox Webhook. |
| `inboxPk` | ✅  | string |                                               |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストエラー:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストエラー:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストエラー: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "inbox": string (uuid)
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "directionLabel": string
  "isEnabled"?: boolean // 任意
  "url": string (uri)
  "method"?:  // 任意
  {
  }
  "headersMasked": object
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "templatePresetLabel": string
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "payloadPreset"?: // 異なる型の場合があります (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
  "payloadPresetLabel": string
  "receiveUrl": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**レスポンスの値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "direction": {},
  "directionLabel": "レスポンス文字列",
  "isEnabled": false,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "サンプルレスポンス名",
    "description": "サンプルレスポンスの説明"
  },
  "templatePreset": "maiagent_standard",
  "templatePresetLabel": "レスポンス文字列",
  "customTemplate": "レスポンス文字列",
  "payloadPreset": "genesys_cloud",
  "payloadPresetLabel": "レスポンス文字列",
  "receiveUrl": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列"
}
```

**ステータスコード: 4XX - エラーレスポンス。エラーコードは X-Error-Code ヘッダーで返されます（「エラーコード」を参照）。**

***

### Webhook の更新 <a href="#inboxes-webhooks-update" id="inboxes-webhooks-update"></a>

PUT `/api/v1/inboxes/{inboxPk}/webhooks/{id}/`

#### パラメーター

| パラメーター名   | 必須 | 型      | 説明                                            |
| --------- | -- | ------ | --------------------------------------------- |
| `id`      | ✅  | string | A UUID string identifying this Inbox Webhook. |
| `inboxPk` | ✅  | string |                                               |

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

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

| フィールド          | 型                                                         | 必須  | 説明                                                                                                                                    |
| -------------- | --------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name           | string                                                    | はい  | Webhook configuration name for identification                                                                                         |
| direction      | object                                                    | はい  | When to trigger: incoming (user messages) or outgoing (bot replies) `incoming`: Incoming ; `outgoing`: Outgoing ; `receive`: Receive; |
| isEnabled      | boolean                                                   | いいえ |                                                                                                                                       |
| url            | string (uri)                                              | いいえ |                                                                                                                                       |
| method         | object                                                    | いいえ |                                                                                                                                       |
| headers        | object                                                    | いいえ | Custom HTTP headers as JSON object                                                                                                    |
| templatePreset | string (enum: maiagent\_standard, genesys\_cloud, custom) | いいえ | `maiagent_standard`: MaiAgent Standard ; `genesys_cloud`: Genesys Cloud ; `custom`: Custom;                                           |
| customTemplate | string                                                    | いいえ | Jinja2 template for custom payload format. Required when template\_preset is "custom".                                                |
| secretToken    | string                                                    | いいえ | Secret token for webhook signature verification                                                                                       |
| payloadPreset  | object                                                    | いいえ | Preset for parsing incoming webhook payloads (used with direction=receive) `genesys_cloud`: Genesys Cloud;                            |

**リクエストスキーマの例**

```typescript
{
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "isEnabled"?: boolean // 任意
  "url"?: string (uri) // 任意
  "method"?:  // 任意
  {
  }
  "headers"?: object // Custom HTTP headers as JSON object (任意)
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "secretToken"?: string // Secret token for webhook signature verification (任意)
  "payloadPreset"?: // 複数の型の可能性あり (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
}
```

**リクエスト値の例**

```json
{
  "name": "名前の例",
  "direction": {},
  "isEnabled": true,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headers": null,
  "templatePreset": "maiagent_standard",
  "customTemplate": "文字列の例",
  "secretToken": "文字列の例",
  "payloadPreset": null
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "名前の例",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": null
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "名前の例",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": null
  };

axios.put("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "名前の例",
    "direction": {},
    "isEnabled": True,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": None,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": None
}

response = requests.put(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '名前の例',
            'direction' => new \stdClass(),
            'isEnabled' => true,
            'url' => 'https://example.com/file.jpg',
            'method' => new \stdClass(),
            'headers' => null,
            'templatePreset' => 'maiagent_standard',
            'customTemplate' => '文字列の例',
            'secretToken' => '文字列の例',
            'payloadPreset' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "inbox": string (uuid)
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "directionLabel": string
  "isEnabled"?: boolean // 任意
  "url": string (uri)
  "method"?:  // 任意
  {
  }
  "headersMasked": object
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "templatePresetLabel": string
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "payloadPreset"?: // 複数の型の可能性あり (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
  "payloadPresetLabel": string
  "receiveUrl": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "direction": {},
  "directionLabel": "レスポンス文字列",
  "isEnabled": false,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンスの名前の例",
    "description": "レスポンスの説明の例"
  },
  "templatePreset": "maiagent_standard",
  "templatePresetLabel": "レスポンス文字列",
  "customTemplate": "レスポンス文字列",
  "payloadPreset": "genesys_cloud",
  "payloadPresetLabel": "レスポンス文字列",
  "receiveUrl": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列"
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### Webhook を部分更新します <a href="#inboxes-webhooks-partial-update" id="inboxes-webhooks-partial-update"></a>

PATCH `/api/v1/inboxes/{inboxPk}/webhooks/{id}/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明                                            |
| --------- | -- | ------ | --------------------------------------------- |
| `id`      | ✅  | string | A UUID string identifying this Inbox Webhook. |
| `inboxPk` | ✅  | string |                                               |

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

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

| フィールド          | 型                                                         | 必須  | 説明                                                                                                                                    |
| -------------- | --------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------- |
| name           | string                                                    | いいえ | Webhook configuration name for identification                                                                                         |
| direction      | object                                                    | いいえ | When to trigger: incoming (user messages) or outgoing (bot replies) `incoming`: Incoming ; `outgoing`: Outgoing ; `receive`: Receive; |
| isEnabled      | boolean                                                   | いいえ |                                                                                                                                       |
| url            | string (uri)                                              | いいえ |                                                                                                                                       |
| method         | object                                                    | いいえ |                                                                                                                                       |
| headers        | object                                                    | いいえ | Custom HTTP headers as JSON object                                                                                                    |
| templatePreset | string (enum: maiagent\_standard, genesys\_cloud, custom) | いいえ | `maiagent_standard`: MaiAgent Standard ; `genesys_cloud`: Genesys Cloud ; `custom`: Custom;                                           |
| customTemplate | string                                                    | いいえ | Jinja2 template for custom payload format. Required when template\_preset is "custom".                                                |
| secretToken    | string                                                    | いいえ | Secret token for webhook signature verification                                                                                       |
| payloadPreset  | object                                                    | いいえ | Preset for parsing incoming webhook payloads (used with direction=receive) `genesys_cloud`: Genesys Cloud;                            |

**リクエストスキーマの例**

```typescript
{
  "name"?: string // Webhook configuration name for identification (任意)
  "direction"?:  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive (任意)
  {
  }
  "isEnabled"?: boolean // 任意
  "url"?: string (uri) // 任意
  "method"?:  // 任意
  {
  }
  "headers"?: object // Custom HTTP headers as JSON object (任意)
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "secretToken"?: string // Secret token for webhook signature verification (任意)
  "payloadPreset"?: // 複数の型の可能性あり (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
}
```

**リクエスト値の例**

```json
{
  "name": "名前の例",
  "direction": {},
  "isEnabled": true,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headers": null,
  "templatePreset": "maiagent_standard",
  "customTemplate": "文字列の例",
  "secretToken": "文字列の例",
  "payloadPreset": null
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "名前の例",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": null
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "名前の例",
    "direction": {},
    "isEnabled": true,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": null,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": null
  };

axios.patch("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "名前の例",
    "direction": {},
    "isEnabled": True,
    "url": "https://example.com/file.jpg",
    "method": {},
    "headers": None,
    "templatePreset": "maiagent_standard",
    "customTemplate": "文字列の例",
    "secretToken": "文字列の例",
    "payloadPreset": None
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '名前の例',
            'direction' => new \stdClass(),
            'isEnabled' => true,
            'url' => 'https://example.com/file.jpg',
            'method' => new \stdClass(),
            'headers' => null,
            'templatePreset' => 'maiagent_standard',
            'customTemplate' => '文字列の例',
            'secretToken' => '文字列の例',
            'payloadPreset' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "inbox": string (uuid)
  "name": string // Webhook configuration name for identification
  "direction":  // When to trigger: incoming (user messages) or outgoing (bot replies)

* `incoming` - Incoming
* `outgoing` - Outgoing
* `receive` - Receive
  {
  }
  "directionLabel": string
  "isEnabled"?: boolean // 任意
  "url": string (uri)
  "method"?:  // 任意
  {
  }
  "headersMasked": object
  "templatePreset"?: string (enum: maiagent_standard, genesys_cloud, custom) // * `maiagent_standard` - MaiAgent Standard
* `genesys_cloud` - Genesys Cloud
* `custom` - Custom (任意)
  "templatePresetLabel": string
  "customTemplate"?: string // Jinja2 template for custom payload format. Required when template_preset is "custom". (任意)
  "payloadPreset"?: // 複数の型の可能性あり (任意)
  string (enum: genesys_cloud) // Preset for parsing incoming webhook payloads (used with direction=receive)

* `genesys_cloud` - Genesys Cloud (任意)
  "payloadPresetLabel": string
  "receiveUrl": string
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inbox": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "direction": {},
  "directionLabel": "レスポンス文字列",
  "isEnabled": false,
  "url": "https://example.com/file.jpg",
  "method": {},
  "headersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "レスポンスの名前の例",
    "description": "レスポンスの説明の例"
  },
  "templatePreset": "maiagent_standard",
  "templatePresetLabel": "レスポンス文字列",
  "customTemplate": "レスポンス文字列",
  "payloadPreset": "genesys_cloud",
  "payloadPresetLabel": "レスポンス文字列",
  "receiveUrl": "レスポンス文字列",
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列"
}
```

**ステータスコード: 4XX - Error response; X-Error-Code carries its code (see "Error codes").**

***

### Webhook の削除 <a href="#inboxes-webhooks-destroy" id="inboxes-webhooks-destroy"></a>

DELETE `/api/v1/inboxes/{inboxPk}/webhooks/{id}/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明                                            |
| --------- | -- | ------ | --------------------------------------------- |
| `id`      | ✅  | string | A UUID string identifying this Inbox Webhook. |
| `inboxPk` | ✅  | string |                                               |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// リクエストボディ (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/inboxes/550e8400-e29b-41d4-a716-446655440000/webhooks/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

| ステータスコード | 説明                                                                 |
| -------- | ------------------------------------------------------------------ |
| 204      | No response body                                                   |
| 4XX      | Error response; X-Error-Code carries its code (see "Error codes"). |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/api-reference/dui-hua-ping-tai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
