# Messaging channels — tool reference

Generated from the OpenAPI document (`https://maison-labs.com/api/v1/openapi.json`). Field types are JSON Schema types; GET/DELETE inputs travel as path or query, other methods as a JSON body.

## `add_channel_instruction` — Add a channel instruction

Appends one titled operator instruction to a channel's ordered list. The AI follows these notes whenever it responds on that channel. Returns the new instruction object with its assigned id. Use `update_channel_instruction` to edit an existing note.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/channel/{channelType}/instruction`
- MCP tool / A2A skill: `add_channel_instruction`
- Needs: update-client WRITE (client); client plan must include `update-client`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channelType` | path | enum: WEB \| GMAIL \| OUTLOOK \| INSTAGRAM \| MESSENGER \| WHATSAPP \| SMS \| CHATGPT | yes | Channel type: WEB \| GMAIL \| OUTLOOK \| INSTAGRAM \| MESSENGER \| WHATSAPP \| SMS \| CHATGPT |
| `title` | body | string | yes | Short label shown in the console (max 100 chars) |
| `text` | body | string | yes | Instruction text the AI reads when responding on this channel (max 1000 chars) |

## `connect_chatgpt_channel` — Connect the ChatGPT guest app

Opts the hotel into the ChatGPT guest-app integration — records the connection in client_channels. 503 when the ChatGPT guest app does not exist in this environment (checked first, so it reveals nothing about the plan); 403 `not_entitled` when the `guestapp` feature is not in the plan. Use `list_channels` first: both `guestMcpAvailable` and `guestappEntitled` must be true. Returns the connection result; `alreadyConnected: true` when the opt-in already existed.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/channel/chatgpt/connect`
- MCP tool / A2A skill: `connect_chatgpt_channel`
- Needs: update-client WRITE (client)

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `delete_channel_instruction` — Delete a channel instruction

Removes one instruction from a channel's list by its id. Removing an id that is already absent is a no-op. `update_channel_instruction` edits an existing instruction.

- REST: `DELETE https://maison-labs.com/api/v1/client/{clientId}/channel/{channelType}/instruction/{instructionId}`
- MCP tool / A2A skill: `delete_channel_instruction`
- Needs: update-client WRITE (client); client plan must include `update-client`
- Destructive — confirm with the user first.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channelType` | path | enum: WEB \| GMAIL \| OUTLOOK \| INSTAGRAM \| MESSENGER \| WHATSAPP \| SMS \| CHATGPT | yes | Channel type |
| `instructionId` | path | string | yes | Instruction id to remove; format uuid |

## `disconnect_channel` — Disconnect a channel

Permanently disconnects and deletes a channel connection. The widget will no longer respond on that channel. Reconnect via the admin console or `get_channel_connect_link`. 404 when the connection id is not found.

- REST: `DELETE https://maison-labs.com/api/v1/client/{clientId}/channel/{channelId}`
- MCP tool / A2A skill: `disconnect_channel`
- Needs: update-client WRITE (client); client plan must include `update-client`
- Destructive — confirm with the user first.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channelId` | path | string | yes | Channel connection id (from list_channels); format uuid |

## `get_channel_connect_link` — Get channel connect link

Returns the URL the operator must open in a signed-in browser to start an OAuth channel connection (Instagram, Messenger, Gmail, Outlook) — the connection is the third party's consent screen, so it cannot complete over the API. Optional `returnTo` (a Maison console, QA editor or admin client URL) is where the browser lands after consent; any other URL is refused with 400. WhatsApp uses Facebook Embedded Signup — the returned URL is the admin-console Channels tab where the operator completes that flow interactively. `requiresBrowserSession` is always true.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/channel/{channel}/connectlink`
- MCP tool / A2A skill: `get_channel_connect_link`
- Needs: update-client WRITE (client); client plan must include `update-client`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channel` | path | enum: instagram \| messenger \| gmail \| outlook \| whatsapp | yes | Channel to connect: instagram \| messenger \| gmail \| outlook \| whatsapp |
| `returnTo` | query | string | no | Where the browser returns after consent: a URL under {SITE_HOST}/console/, {SITE_HOST}/qa/ or the admin host's /clients/ (OAuth channels only); format uri |

## `list_channel_instructions` — List channel instructions

Returns all operator-authored style instructions for every channel type (WEB, GMAIL, OUTLOOK, INSTAGRAM, MESSENGER, WHATSAPP, SMS, CHATGPT). Each key holds an ordered list of titled notes the AI follows when responding on that channel. Use `add_channel_instruction` to add a note.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/channels/instructions`
- MCP tool / A2A skill: `list_channel_instructions`
- Needs: update-client READ (client); client plan must include `update-client`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `list_channels` — List connected channels

Returns every messaging channel connected to a hotel (Instagram, Messenger, Gmail, Outlook, WhatsApp, ChatGPT guest app, …), with the reply-mode settings of each. Also returns `entitled` (channels feature in the plan), `guestappEntitled` (ChatGPT guest-app entitlement) and `guestMcpAvailable` (the ChatGPT guest app exists in this environment) — `connect_chatgpt_channel` works only when both of the last two are true. Use before connecting a channel to see what is already active.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/channels`
- MCP tool / A2A skill: `list_channels`
- Needs: update-client READ (client); client plan must include `update-client`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |

## `update_channel_instruction` — Update a channel instruction

Replaces the title and text of one instruction by its id. Returns the updated instruction. 404 when the id is not found on that channel type.

- REST: `PUT https://maison-labs.com/api/v1/client/{clientId}/channel/{channelType}/instruction/{instructionId}`
- MCP tool / A2A skill: `update_channel_instruction`
- Needs: update-client WRITE (client); client plan must include `update-client`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channelType` | path | enum: WEB \| GMAIL \| OUTLOOK \| INSTAGRAM \| MESSENGER \| WHATSAPP \| SMS \| CHATGPT | yes | Channel type |
| `instructionId` | path | string | yes | Instruction id returned by add_channel_instruction; format uuid |
| `title` | body | string | yes | Replacement title |
| `text` | body | string | yes | Replacement text |

## `update_channel_settings` — Update channel settings

Changes the reply mode of a connected channel: `autoReplyEnabled` turns automatic responses on/off; `draftOnly` puts replies in draft mode instead of sending. At least one field must be supplied. 404 when the channel connection is not found.

- REST: `PATCH https://maison-labs.com/api/v1/client/{clientId}/channel/{channelId}`
- MCP tool / A2A skill: `update_channel_settings`
- Needs: update-client WRITE (client); client plan must include `update-client`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `channelId` | path | string | yes | Channel connection id (from list_channels); format uuid |
| `autoReplyEnabled` | body | boolean | no | Enable or disable automatic replies on this connection |
| `draftOnly` | body | boolean | no | When true, replies are placed in draft mode instead of sent |