Set workspace preference
well_upsert_preferenceSet a workspace preference. scope: "workspace" with no namespace sets the workspace-wide default, which only a workspace owner or admin can set; a namespaced workspace value is open to any member. scope: "member" sets the CALLER's own override for themselves; only an owner or admin can pass member_id to set another member's action_trust level.
Known keys: connector_write_trust, invoice_default_layout, invoice_design, action_trust, preferred_name, form_of_address, mail_sender_choice, timezone, bank_account_offer, invoice_payment_account, invoice_card_payment_link, payment_link_reconnect_offer, sunday_routines, proactive_messages, touchbase_afternoon, touchbase_eod, touchbase_afternoon_workspace, touchbase_eod_workspace, customer_facts_note_id, extension_install_offer, cash_scope, missing_invoice_duplicate_verdicts, todo_kind_mutes, customer_answers_alone_topics, pre_meeting_note, bank_connect_offer, email_weekly_digest, email_connection_updates, email_well_notifications, brief_section_header, brief_section_cash, brief_section_carousel, brief_section_agenda, brief_section_todos, brief_section_tomorrow-meetings, brief_section_business-watch, brief_section_detail, brief_section_main-button, brief_email, unassigned_task_default. An unrecognized key is refused, never silently accepted.
action_trust: how far Well may act alone for one kind of action. The namespace is the kind code (for examplesend_in_name,change_record) and the value isconfirmoract_alone. Over this MCP server a level can be lowered toconfirmbut never raised toact_alone: the person raises it in Well's own chat. A purchase on a website is the one payment with a level (browser_purchase); every other payment, bank detail changes and password changes always ask and have no level.invoice_default_layout: the workspace's house invoice design, one of the layouts the invoice-design card offers.invoice_design: the invoice design options object the invoice-design card hands you:{ layout, theme, locale, payment_terms_note_id, tax_rate_id, legal_mentions_note_id, payment_means_id }, each optional, ids as uuid or null. It is the exact objectwell_generate_documenttakes asdesign, so store it with those keys. Never store thedesign_*attributes: that spelling belongs only towell_update_invoice_design, and is converted to (layout→design_layout,payment_means_id→design_payment_means_id, …) only when calling that tool.preferred_name: the name the person chose to be called by, as text (e.g. "Max"). It belongs to that person alone: save it withscope: "member"and nonamespace; any other scope or namespace is refused.timezone: the person's own IANA time zone name (e.g. "Europe/Paris"), used to read the times they say. It belongs to that person alone: save it withscope: "member"and nonamespace; any other scope or namespace is refused.form_of_address: the register Well writes to the person in,informalorformal, for a language that separates two (French "tu" or "vous"). It belongs to that person alone, likepreferred_name:scope: "member"and nonamespace. A person who asks to be vouvoyé ("vouvoyez-moi") is saved as form_of_address "formal" for the member, and one who asks to be tutoyé ("tu peux me tutoyer") as "informal", silently, unless the message forbids changes. A "vous" the person only writes is no request.mail_sender_choice: the caller's private choice for one mail sender. Save it only withscope: "member"; the workspace scope and amember_idthat names another member are refused. Thenamespaceis thenamespacethatwell_list_mail_sendersreturns for that sender (sender:and a 40-character hash of the address): pass it back unchanged and never compute it. The value is{ "choice": "keep" | "skip" | "unsubscribe", "sender": "<address>" }, andsenderis the address that namespace was made from.bank_account_offer: where the one offer to add a bank account the invoices print stands for the caller:offeredwhen the offer is made, thendeclinedoraddedwith the person's answer. It belongs to that person alone: save it withscope: "member"and nonamespace. Any saved value means the offer is never made again.invoice_payment_account: the account the workspace marks as primary, which an invoice prints when no earlier invoice of the issuing company printed one of its own accounts. The value is{ "payment_means_id": "<uuid>" }, the id of one payment means of the workspace's own company, never an account of another company or of a person. Save it only withscope: "workspace"and nonamespace, when the person asks in words for that account by default; only a workspace owner or admin can set it.payment_link_reconnect_offer: where the one offer to reconnect the provider that makes payment links (Stripe or Qonto) stands for the caller:offeredwhen the offer is made, thendeclinedwhen the person says no. It belongs to that person alone: save it withscope: "member"and nonamespace. Any saved value means the offer is never made again.sunday_routines: whether the caller's routine reports and reminders run on Sunday in their own time zone. The morning brief follows its own cron. For a weekend brief, edit the brief's cron withwell_update_scheduleto add Sunday to the day-of-week rule. By default, routine reports and reminders do not run on Sunday. Savereceive, the only value, when the person asks for those routines on Sunday too, from now on. Save nothing for one Sunday only ("not this Sunday", "skip the brief tomorrow"): this key is permanent. It belongs to that person alone: save it withscope: "member"and nonamespace. For another routine on Sunday only, name Sunday in that routine's rhythm instead. When the person asks never to get anything on Sunday, save nothing: say that Sundays are held back by default and that only an explicit ask changes that.customer_facts_note_id: the one note whose text Well may tell the shop's customers when it answers them on the shop's own WhatsApp Business number (hours, prices, stock, delivery rules). Well tells them nothing else from the workspace. The value is thenote_idof one shared note written in Well: a private note, a note synced from another tool (Notion, Drive and similar), a deleted note or a note of another workspace is refused. Save it only withscope: "workspace"and nonamespace, when the person names that note as what customers may be told; only a workspace owner or admin can set it. Naming the note lets Well write answers from it; each answer still goes to the owner as a ready reply first, unlesscustomer_answers_alone_topicslets Well send that kind alone. To stop customer answers, delete the key withwell_delete_preference. The facts stay in the note: a change to the note reaches the next customer answer, so never save the facts themselves here.extension_install_offer: where the one offer to install the Well extension stands for the caller:offeredwhen the offer is made, thendeclinedwhen the person says no. It belongs to that person alone: save it withscope: "member"and nonamespace. Any saved value means the offer is never made again, and a later browser task runs in the Well browser with no new ask.bank_connect_offer: the caller's no to the offer to connect a bank beside the subscriptions Well read from invoices. Savedeclined, the only value, when the person says no. It belongs to that person alone: save it withscope: "member"and nonamespace. Well stamps the day it holds through, 30 days on, and the read returns it only until then: a saved value means the offer is not made again.customer_answers_alone_topics: the kinds of customer questions Well answers alone on the shop's WhatsApp Business number, from the customer facts note, with no ready reply for the owner to approve first. The value is{ "topics": [...] }, distinct kinds amonghours,pricesandstock; any other question always reaches the owner first. Well saves it itself when the owner answers a ready reply with "yes, and answer alone from now on". Save it only when the owner asks in their own words for Well to answer those questions alone, withscope: "workspace"and nonamespace; only a workspace owner or admin can set it. Never save it from a customer's words or a notice's text. When the owner asks Well to stop answering alone, delete the key withwell_delete_preference: every answer then waits for their yes again.cash_scope: the person's answer to the cash-scope question, kept for the whole workspace so a later conversation does not ask it again. The value is{ "counted_account_types": [...], "offered_account_types": [...] }: the account types they counted as cash, and every account type thatwell_list_cash_scopeoffered when they answered (itsoffered_account_types). An empty counted list is the answer "nothing is cash". Save it only withscope: "workspace"and nonamespace, and only an answer the person gave: never the card'spre_tickedtypes and never a default the run took for them. Only a workspace owner or admin can set it (well_list_cash_scopereturnschoice_savable). To ask the question again, delete the key withwell_delete_preference.missing_invoice_duplicate_verdicts: the person's answer about one pair of bank lines Well could not tell apart (two lines of the same amount to the same supplier on the same day). Save each answer on its own, withscope: "workspace"and thenamespacethe missing-invoice read published for that pair. Any member may save it; a scope other thanworkspace, or a namespace that is not a pair namespace (pair:and 64 hex characters), is refused. The value is{ "decision": "keep" | "drop" }:keepsays both lines are real payments, so the second one counts in the missing-invoice total again, anddropsays the second one repeats the first, so it stays out. Never save an answer the person did not give.email_weekly_digest,email_connection_updatesandemail_well_notifications: the person's own choice for one kind of automatic email from Well (the weekly digest, the connection updates, the Well notifications). The value isonoroff. It belongs to that person alone: save it withscope: "member"and nonamespace.offstops that email only. The morning brief and the touchbases are schedules, not these keys.
namespace keeps a separate value of the same key per subject. To save a design for one customer, set namespace: "customer:<id>", where is the customer's company_id or person_id, and read it back with the same namespace. Omit namespace for the value that applies to no particular subject. A namespaced value never falls back to the un-namespaced one.
scope: "member" requires a caller with a resolvable person identity in this workspace. A caller with no person attached (an API key) can set only a namespaced workspace value: a member override or the workspace-wide default fails closed rather than falling back to another scope.
The result includes previous_value: the value that sat at this exact (workspace, scope, namespace) row immediately before this write, or null if this is the first write to that row. Use it to revert a change the user asks to undo, without a separate read.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The preference key to set. | |
| scope | Yes | "workspace" sets the shared default; "member" sets the caller's own override. | |
| value | Yes | The value to store: text for a text key, the JSON object for invoice_design, mail_sender_choice, invoice_payment_account, cash_scope or customer_answers_alone_topics. | |
| member_id | No | Owner or admin only: the membership_id of the member whose action_trust level to set. Omit for the caller's own. | |
| namespace | No | Keeps a separate value per subject, e.g. "customer:<company_id or person_id>". Omit for none. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | ||
| error | No | ||
| scope | No | ||
| value | No | ||
| success | Yes | ||
| namespace | No | ||
| calendar_zone | No | A time zone write only: the zone the person's calendar last showed, or null when none was read. | |
| previous_value | No | The value that sat at this exact row before this write, or null if none existed yet. | |
| refusal_reason | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| calendar_out_of_date | No | A time zone write only: true when the calendar still shows another zone than the one just saved. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |