Concepts
The nine objects every integration touches, and how they relate. Read once; the guides assume it.
Last updated
| Object | What it is | Where it lives |
|---|---|---|
| Workspace | One customer of Kommio: its people, inboxes, conversations and settings. Every credential resolves to exactly one; the API host is the same for all workspaces (app.kommio.io). A person who belongs to several (one brand per workspace) switches between them, or reads All brands, one read-only list over every workspace they belong to, each read with their role there (GET /me/conversations, under the session only). | /account |
| Inbox | One channel connection: a mailbox, a website-chat key, a WhatsApp number, a Facebook Page or Instagram account, a Telegram bot, an SMS number, a set of Slack channels. Conversations belong to an inbox; members are assigned per inbox, and an inbox can assign its own conversations by skills and load. | /inboxes |
| Contact | A customer. Identities (email, phone, external id, visitor) attach to it and are how inbound messages find it. Contacts can be merged. | /contacts |
| Conversation | One thread with one contact in one inbox. Has a status (category open, pending, snoozed, resolved, closed), priority, assignee, team, tags, subject and custom attributes. A chat that becomes an email is still one conversation. | /conversations |
| Message | Inbound or outbound; kind reply (delivered through the channel), note (private, role-gated) or activity (system line). Text, HTML (sanitised) or Markdown. | /conversations/{id}/messages |
| Member, team, role | People in the workspace, their teams, and the role that decides permissions, visibility scope and field masking. | /account/members, /teams, /roles |
| Event | A durable record of a change, published in the same transaction. Webhooks, apps, bots and the realtime socket consume events. | catalogue |
| Automation, macro | A rule (an event or time trigger, conditions, actions, a delay or threshold, a budget) that runs with its author's permissions in a set order; a macro is the same action list applied by hand. Assignment (by team or inbox, skills, capacity and routing), chatbot flows and SLA policies sit beside them. | /automations, /macros, /sla/policies |
| Extension | One thing a workspace adds from Settings › Marketplace, with one or more capabilities: a sidebar panel or message hook (an app you host), an event subscription (a webhook), an agent bot that holds an inbox until it hands off, a remote data lookup, an automation action, a rule or flow template, a channel. Offered is not installed: each workspace installs and sets up its own. | /integrations, /apps, /bots |
Ids and addressing
Every object has a numeric id unique within the workspace; conversations also carry a human display_id (the number agents see). Contacts can be addressed by external id through their identities, which is how you link Kommio to your own user ids without storing Kommio ids.
Statuses
Statuses are data: each has a key, a label and a category that drives behaviour. The built-in keys are open, pending, snoozed, resolved and closed; a workspace can add its own under the same categories ("waiting on engineering" as a pending). Filter by category when you want behaviour, by status when you want the exact key.
Visibility
What a call returns depends on who calls. A person sees conversations within their role's scope (all, team, inbox, assigned, unassigned); API keys and app tokens see the whole workspace within their permissions; a bot sees only the conversations it holds; a visitor sees only their own. Sensitive fields come back visible, masked or hidden per role, with the list under _redacted.
Every claim on these pages is covered by a test in the repository, and the API reference is generated from the same contract every server serves at /api/openapi. Corrections to [email protected].