Create a workspace
Sign up on Kommio Cloud (free, no sales call). The hosted app lives at app.kommio.io and the API under https://app.kommio.io/api; every credential you create is bound to your workspace, so there is nothing to put in the URL. The snippets below use KOMMIO_URL for it.
Add an inbox
Settings, Inboxes: an email inbox (a Microsoft 365 or Google sign-in, or IMAP and SMTP credentials validated before saving) or a website-chat inbox; the other channels (WhatsApp, Messenger, Instagram, Telegram, SMS, Slack) start from Settings › Marketplace. Note its id; you will start conversations in it. You can also create one through the API with POST /api/inboxes.
Create an API key
Settings, API keys. Tick the permissions the integration needs, for this quickstart conversations:read, conversations:reply, contacts:read, contacts:write and webhooks:manage. The key starts with kmk_ and is shown once.
shell
```
export KOMMIO_URL=https://app.kommio.io/api
export KOMMIO_KEY=<api key>
```

Start a conversation from your code

One call creates the contact if the email is new, opens the conversation in the inbox and sends the first message through the channel.

curl -X POST "$KOMMIO_URL/conversations" \
  -H "Authorization: Bearer $KOMMIO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4242-welcome" \
  -d '{
    "inbox_id": 3,
    "email": "[email protected]",
    "subject": "Your order 4242",
    "content": "Hi Ana, your order has shipped. Reply here with any question."
  }'

import { createKommioClient } from "@kommio/api-client";

const api = createKommioClient({ baseUrl: process.env.KOMMIO_URL!, apiKey: process.env.KOMMIO_KEY! });

const { data: conv } = await api.POST("/conversations", {
  body: {
    inbox_id: 3,
    email: "[email protected]",
    subject: "Your order 4242",
    content: "Hi Ana, your order has shipped. Reply here with any question.",
  },
});
console.log(conv.id, conv.display_id, conv.status);

import os, requests

BASE, KEY = os.environ["KOMMIO_URL"], os.environ["KOMMIO_KEY"]
H = {"Authorization": f"Bearer {KEY}", "Idempotency-Key": "order-4242-welcome"}

conv = requests.post(f"{BASE}/conversations", headers=H, json={
    "inbox_id": 3,
    "email": "[email protected]",
    "subject": "Your order 4242",
    "content": "Hi Ana, your order has shipped. Reply here with any question.",
}).json()
print(conv["id"], conv["display_id"], conv["status"])

body := map[string]any{"inbox_id": 3, "email": "[email protected]", "subject": "Your order 4242",
	"content": "Hi Ana, your order has shipped. Reply here with any question."}
b, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", os.Getenv("KOMMIO_URL")+"/conversations", bytes.NewReader(b))
req.Header.Set("Authorization", "Bearer "+os.Getenv("KOMMIO_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "order-4242-welcome")
res, err := http.DefaultClient.Do(req)

Response 201 Created

{
  "id": 4821, "display_id": 231, "inbox_id": 3, "contact_id": 77, "contact_name": "[email protected]",
  "status": "open", "status_category": "open", "priority": "none", "subject": "Your order 4242",
  "created_at": "2026-09-22T09:12:00Z", "last_message_preview": "Hi Ana, your order has shipped."
}

Reply and read the thread

curl -X POST "$KOMMIO_URL/conversations/4821/messages" \
  -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"content": "Tracking: 1Z999. Delivery Thursday.", "kind": "reply"}'

curl "$KOMMIO_URL/conversations/4821/messages" -H "Authorization: Bearer $KOMMIO_KEY"

await api.POST("/conversations/{id}/messages", {
  params: { path: { id: conv.id } },
  body: { content: "Tracking: 1Z999. Delivery Thursday.", kind: "reply" },
});
const { data: thread } = await api.GET("/conversations/{id}/messages", { params: { path: { id: conv.id } } });
for (const m of thread.messages) console.log(m.direction, m.kind, m.content);

requests.post(f"{BASE}/conversations/{conv['id']}/messages", headers=H,
              json={"content": "Tracking: 1Z999. Delivery Thursday.", "kind": "reply"})
thread = requests.get(f"{BASE}/conversations/{conv['id']}/messages", headers=H).json()
for m in thread["messages"]:
    print(m["direction"], m["kind"], m["content"])

Hear back when the customer answers

Register a webhook for message.created. Every delivery is signed; the webhooks guide has receivers in Node, Python and Go.

curl

curl -X POST "$KOMMIO_URL/webhooks" \
  -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"name": "orders", "url": "https://orders.example/hooks/kommio", "events": ["message.created", "conversation.updated"]}'

Response 201 Created

{ "id": 9, "name": "orders", "url": "https://orders.example/hooks/kommio", "events": ["message.created", "conversation.updated"], "status": "active", "secret": "whsec_8kP2mQ7vR4tX1yB6nC9zL3hJ0dF5gA" }

The secret is in this response only.

Conversations and messages →Webhooks →

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].

Quickstart

Create a workspace

Add an inbox

Create an API key

Start a conversation from your code

Reply and read the thread

Hear back when the customer answers