Maison — Hotel configuration, branding and content

Configure how a hotel's concierge behaves and looks: the hotel configuration document (set/unset fields), the chatbot tone, the chat widget's runtime switches and full style map, guest-facing translations with machine translation, theme colour and visuals, media assets, the sales agent configuration and lead recipients, internal client notes, the email log, settings catalogues (regions, departments, tags) and report subscribers. Use for any 'change what the concierge says/looks like' request or to read a hotel's current setup.

Part of the Maison public API. Read the maison-public-api skill first for authentication, discovery and transport details (https://docs.maison-labs.com/skills/maison-public-api/SKILL.md).

When to use

• Update address, hours, policies or any hotel fact the concierge should know — update_hotel_config.
• Change the agent's voice — set_chatbot_tone; get_chatbot_tone returns defaultTone and set_chatbot_tone with reset: true restores it.
• Localise — get_translations, translate_text, update_translations.
• Brand the widget — set_theme_color, upload_theme_visual; the full style map with get_chat_styles / set_chat_styles.
• To make a chat icon in the brand colour call generate_theme_icon; it replaces the current icon.
• Switch the custom theme or document answers on or off — get_chat_runtime / update_chat_runtime (branding, documents).

Before you start

1. Send x-api-key: <key> on every call; the key only reaches /api/v1.
2. GET /api/v1/tools (or MCP tools/list) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
3. Client-scoped tools take clientId (a hotel id). whoami lists the ids you can act on.

Tools

Full input fields for every tool: references/tools.md.

Recommended workflows

Change a hotel fact safely

1. get_hotel_config to read the current document and exact field names.
2. update_hotel_config with set: { field: value } (and unset: [field] to remove); only the fields sent change.
3. Confirm with send_message (conversations skill) in a new session.

Add a language

1. get_translations for the current map and keys.
2. translate_text in batches to draft the new locale, review, then update_translations with the merged map.

Tips

• Notes support optimistic concurrency: send the updatedDate you read, and retry on 409.
• Theme visuals and media images up to 64 KiB go inline as bytesBase64; larger ones (≤ 5 MB): create_theme_visual_upload / create_media_upload, PUT the file to uploadUrl with exactly headers, then upload_theme_visual / upload_media_asset with the uploadId. get_theme returns visual URLs.

Pitfalls

• update_translations replaces the whole map — always merge into the result of get_translations. It is validated exactly like the console (≤ 60 languages, identifier phrase keys, the default must be active).
• set_chat_styles replaces the whole style map — send every token you want kept (read it with get_chat_styles first).
• Agents tools require the hotel's plan to include agents, for Maison staff too; without it they answer 403 not_entitled.

Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send x-api-key.

# REST
curl -X POST "https://maison-labs.com/api/v1/client/<clientId>/note" -H "x-api-key: $MAISON_API_KEY" -H "content-type: application/json" -d '{ "bodyMarkdown": … }'

// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_client_note", "arguments": { "bodyMarkdown": … } } }

// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "add_client_note", "input": { "bodyMarkdown": … } } }] } } }

Errors are the same everywhere: 401 no/invalid key; 403 forbidden with details.missing (the grants you lack — fall back to the composite's parts or stop); 403 not_entitled (the hotel's plan lacks the feature); 404, 409, 413 too_large, 503. Inputs that fail validation return 400 invalid_input with the Zod issues — fix and retry once.