Create and manage Kustomer conversation timelines via API
domain: developer.kustomer.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Authenticate by including your Kustomer API key as a Bearer token in the Authorization header: 'Bearer YOUR_KEY'.
Create a new conversation with POST /v1/conversations, supplying 'name', 'status' (open/snoozed/done), 'channels' (an array with at least one channel object), and optionally 'assignedTeamId' or 'assignedUserId'.
Add a message (KObject) to the conversation timeline with POST /v1/conversations/{conversationId}/messages, providing 'body', 'direction' (in for inbound, out for outbound), 'channel', and 'subject' if email.
Add a note visible only to agents with POST /v1/conversations/{conversationId}/notes, supplying 'body' (HTML supported) and optionally mentioning agents with @-style identifiers as supported by Kustomer's note schema.
Retrieve the full timeline (messages and notes interleaved) with GET /v1/conversations/{conversationId}/timeline to inspect the ordered sequence of events.
Update conversation status or assignee with PATCH /v1/conversations/{conversationId} using a partial JSON body.
Known gotchas
Kustomer's data model is KObject-based — every message, note, and event is a KObject on the timeline; ensure your payload matches the correct KObject schema for each type or the API returns a schema validation error.
Direction matters for reporting: messages posted as 'out' count as agent-sent in metrics; posting internal integration events as 'out' will skew your reply-time and volume reports.
Kustomer enforces API rate limits per API key — if you are ingesting high volumes of historical conversation data, use the bulk import endpoints rather than individual create calls.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?