Search and filter
List conversations by any combination of status, inbox, assignee, team, tag, priority and time; save the filter as a view; and search inside messages with full-text queries.
Last updated
Listing with parameters
# open, unassigned, in inbox 3, oldest waiting first
curl "$KOMMIO_URL/conversations?category=open&unassigned=true&inbox_id=3&sort=oldest_waiting&limit=50" \
-H "Authorization: Bearer $KOMMIO_KEY"
# next page: pass the cursor back
curl "$KOMMIO_URL/conversations?category=open&cursor=eyJ0IjoiMjAyNi0wOS0yMlQwOToxMjowMFoiLCJpZCI6NDgyMX0" -H "Authorization: Bearer $KOMMIO_KEY"import { paginate } from "@kommio/api-client";
for await (const c of paginate((cursor) => api.GET("/conversations", { params: { query: { category: "open", unassigned: true, inbox_id: 3, sort: "oldest_waiting", cursor } } })))
console.log(c.display_id, c.subject, c.last_activity_at);def pages(path, **params):
cursor = None
while True:
r = requests.get(f"{BASE}{path}", headers=H, params={**params, "cursor": cursor}).json()
yield from r["items"]
cursor = r.get("next_cursor")
if not cursor:
return
for c in pages("/conversations", category="open", unassigned="true", inbox_id=3, sort="oldest_waiting"):
print(c["display_id"], c["subject"])Parameters: category, status (exact key), inbox_id, assignee_id, unassigned, team_id, tag_id, contact_id, priority, q (subject and preview substring), sort (last_activity, oldest_waiting, priority, created), limit up to 100, cursor.
Condition trees
For anything the parameters cannot say, pass a JSON condition tree as filter. It is the same language saved views use. Nodes are all, any and not; leaves are field, op, value.
{ "all": [
{ "field": "status_category", "op": "in", "value": ["open", "pending"] },
{ "field": "priority", "op": "in", "value": ["high", "urgent"] },
{ "any": [
{ "field": "tags", "op": "has", "value": 4 },
{ "field": "subject", "op": "contains", "value": "refund" }
] },
{ "not": { "field": "last_inbound_at", "op": "within", "value": "PT2H" } }
] }FILTER='{"all":[{"field":"status_category","op":"in","value":["open","pending"]},{"field":"priority","op":"in","value":["high","urgent"]}]}'
curl -G "$KOMMIO_URL/conversations" --data-urlencode "filter=$FILTER" -H "Authorization: Bearer $KOMMIO_KEY"const filter = { all: [{ field: "status_category", op: "in", value: ["open", "pending"] }, { field: "priority", op: "in", value: ["high", "urgent"] }] };
const { data } = await api.GET("/conversations", { params: { query: { filter: JSON.stringify(filter) } } });| Field | Kind | Operators |
|---|---|---|
status_category, priority | enum | eq, neq, in |
status_id, inbox_id, assignee_id, team_id, contact_id | reference | eq, neq, in, is_empty |
subject | string | eq, contains, not_contains, starts_with, is_empty |
unread_count | number | eq, gt, gte, lt, lte |
tags | set | has, has_not, has_any |
created_at, last_activity_at, last_inbound_at, first_response_at, resolved_at, snoozed_until | time | before, after, within, older_than (ISO 8601 durations such as PT2H, P3D) |
GET /views/schema returns this catalogue with labels and reference lists, which is what the view editor renders. Save a tree with POST /views and reuse it as ?view_id=.
Full-text search
GET /conversations/search?q= searches message bodies, subjects and contact names with websearch syntax: words, "exact phrases", -excluded. One hit per conversation, ranked, with a highlighted fragment; private notes only when the caller may read them.
curl -G "$KOMMIO_URL/conversations/search" --data-urlencode 'q="order 4242" -refund' --data-urlencode 'inbox_id=3' \
-H "Authorization: Bearer $KOMMIO_KEY"const { data } = await api.GET("/conversations/search", { params: { query: { q: '"order 4242" -refund', inbox_id: 3 } } });
for (const h of data.hits) console.log(h.conversation.display_id, h.matched_in, h.snippet);Response 200 OK
{ "q": "\"order 4242\" -refund", "has_more": false, "hits": [
{ "conversation": { "id": 4821, "display_id": 231, "subject": "Your order 4242", "status_category": "open" }, "message_id": 55010, "matched_in": "message", "rank": 0.61, "snippet": "where is my <b>order</b> <b>4242</b>? It was due Monday" }
] }Counts for a dashboard
curl "$KOMMIO_URL/conversations/counts" -H "Authorization: Bearer $KOMMIO_KEY"
# { "open": 42, "pending": 7, "snoozed": 3, "unassigned": 12, "mine": 5, "by_inbox": { "3": 30, "4": 12 } }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].