The Support API reference

The guide is The Support API, Chatwoot's. This page says exactly what is there.

A subscription carries a source: one somebody made through this API is hand and is theirs, and one a deployment ships declared in platformkit.config.js is file and is the projection's to replace — see Declarations and state.

Base, keys, headers

The Client API

A message: { id, content, inbox_id: 1, conversation_id, message_type (0 incoming · 1 outgoing · 2 activity), content_type: 'text', content_attributes, status: 'sent', private: false, created_at (unix seconds), sender ({ id, name, email, type: 'contact' | 'user', identifier, custom_attributes } — null for an activity line), attachments: [{ id, file_type: image | audio | file, extension, data_url (the site's signed url, an hour), thumb_url, file_size, duration? }], echo_id? }; a voice note carries content_attributes: { kind: 'voice', seconds }. A bot's answer that ends in choices carries them as Chatwoot does: content_type: 'input_select' and content_attributes: { items: [{ title, value }], taken? } — taken is the value already chosen, since an offer is taken once. Taking one through the API is posting its title as the contact's line; the offer is marked only through the widget's own door.

The Application API

A conversation: { id, inbox_id: 1, account_id: 1, status, muted: false, can_reply: true, channel: 'Channel::WebWidget', timestamp, created_at, updated_at (unix seconds), unread_count (the contact's lines since the agent read), first_reply_created_at, waiting_since (the first unanswered line's time), agent_last_seen_at, contact_last_seen_at, additional_attributes: { path, source, prompt_id, resolved_at }, custom_attributes, labels: [], messages, last_non_activity_message, meta: { sender, assignee, hmac_verified: false } }. A contact: { id, name (Guest for a guest), email, identifier (the user id), custom_attributes, additional_attributes: { kind: guest | user | customer, verified, last_path, notes, orders }, contact_inboxes: [{ source_id, inbox }], created_at, last_activity_at } — source_id is never answered to the desk (it is the contact's secret).

Webhooks

support_webhooks (id, url, subscriptions, created_by, last_at, last_error; the staff read under RLS, the service role writes). Events: conversation_created (an insert), conversation_status_changed, conversation_updated (the assignee or the custom attributes), message_created (every line — a contact's, an agent's, a system one), contact_created; message_updated, contact_updated and webwidget_triggered are accepted in a subscription and never sent. The triggers (support_api_on_message, support_api_on_conversation, support_api_on_contact) ask support_api_notify(event, id), which posts to the function over pg_net with app_settings' url and secret — nothing while no subscription exists. The payload: for a message, { event, id, content, message_type: 'incoming' | 'outgoing' | 'activity', content_type, content_attributes, created_at (ISO), sender, attachments, conversation (with meta, without messages), inbox: { id, name }, account: { id, name } }; for a conversation, { event, …the conversation with its messages, inbox, account }; for a contact, { event, …the contact, account }. A delivery is one POST with a JSON body; a non-2xx answer is kept as last_error.

The snippet and window.$chatwidget

GET /api/desk/packs/js/sdk.js — one script (Vue and the widget inside; ~165 KB gzipped), built by the support-sdk step into dist/api/desk/packs/js/sdk.js, the dev server serving it once built (node build/support-sdk.mjs). window.chatwootSDK.run({ websiteToken, baseUrl }) mounts the widget once; websiteToken must equal the site's space id, and baseUrl (else the script's own origin) is the site every path of ours resolves against — a prompt's picture included. The bundle carries the theme's tokens and the site's look, and styles nothing outside the widget: the page it lands on keeps its own type and colour. window.$chatwidget — and window.$chatwoot, the same object: hasLoaded (true), isOpen, toggle(state?), toggleBubbleVisibility(state?), popoutChatWindow() (opens <baseUrl>/support), setUser(identifier, attrs), setCustomAttributes(attrs), deleteCustomAttribute(key), setConversationCustomAttributes(attrs), deleteConversationCustomAttribute(key) (kept for the next conversation), setLabel, removeLabel, setLocale (no-ops), reset(). Events on window: chatwidget:ready, chatwidget:on-message (detail.message) and chatwidget:error, each fired under Chatwoot's name beside it (chatwoot:ready, chatwoot:on-message, chatwoot:error) with the same detail. The same object is on the site's own pages. The loader keeps Chatwoot's name (window.chatwootSDK.run), since their snippet calls it; window.PlatformKitSupport.run is the same loader. /support (ROUTES.support, noindex, no chrome) is the panel on a page of its own.

The keys

api_keys.kind gains support (Settings → API: Support — the desk: conversations, replies, contacts, webhooks). The module switches are support and api.