Kustomer

A read-only API key integration that syncs Kustomer conversations, messages, notes, customers, and agents into Rippit on a schedule. For what applies to every integration, see how data integrations work. For the security model, see Data integration security. Kustomer is in beta. It appears as a source only in workspaces where beta integrations are turned on.

Connection summary


Authorization	A Kustomer API key, sent as `Authorization: Bearer <key>`
Scope parameter	None. Access is set by the roles on the key
Key requirement	The org.user and org.admin read roles, plus org.admin.user, org.admin.content, and org.tracking
Writes to Kustomer	None. Every call is a `GET`
Credentials shared with Rippit	The API key. Rippit stores it and uses it for every sync
Credential check	The key is tested against Kustomer before the connection is created. Rejected credentials create no connection, and Rippit does not keep them
Connection identity	Your Kustomer org, read from the key. One connection per org
Required Rippit role	Workspace admin
API base	`https://<subdomain>.api.kustomerapp.com`
API version	`v1`, in the path
Sync method	Scheduled polling
Attachments	Downloaded and stored by Rippit, including images inline in message and note bodies
Maximum historical backfill	90 days, which is also the default
Field selection limit	150 columns

Before you connect

Rippit asks for two values. The subdomain is your org name in your Kustomer URL: acme in acme.kustomerapp.com. You can paste the whole URL, including an acme.api.kustomerapp.com URL, and Rippit extracts the subdomain. Create the API key in Kustomer under Settings, then Security, then API Keys. Give it the org.user and org.admin read roles, plus org.admin.user, org.admin.content, and org.tracking. Rippit reads your org from the key itself, so the key must belong to the org the subdomain names.

Data handling

Question	Answer
Is conversation content ingested, or only metadata?	Full content: messages, notes, satisfaction ratings and comments, handle time, tags, custom attributes you select, customers, and agents
Are notes ingested?	Yes. Notes are stored and marked as not public
Are attachments stored?	Yes. File attachments and inline images are downloaded and stored rather than linked
Can Rippit modify Kustomer?	No. No write code path exists
Is data used to train models?	No. Rippit does not train any AI models. Your data is used for inference only

What a conversation becomes in Rippit

Each Kustomer conversation becomes one conversation in Rippit.

Rippit record	Content
Subject	The conversation name
Agents	Every assigned user, the user who sent the first response, and the agents who wrote messages or notes
Start and end	The conversation’s created time and its last updated time
Status	The conversation status from Kustomer
Tags	Tag names, looked up from your org’s tags
Default selected fields	Subject, status, tags, all assignees, commenters, first commenter, and last commenter
Messages	Each message, attributed to the agent who sent it when outbound, or to the customer when inbound. Automated outbound messages are attributed to a bot. The text comes from the message’s `preview` field
Notes	Each note’s body, attributed to its author and marked as not public
Shortcuts	When a message uses a shortcut, Rippit records the shortcut’s name, its saved text, and the message as sent
Handle time	The conversation’s handle time from Kustomer, added as a private system comment
Satisfaction ratings	The rating, on a 1 to 5 scale, with any written answer added as a comment
Attachments	Files attached to messages, and images inline in message and note bodies
People	Agents, with name, display name, email, phone, and roles, and customers, with name, display name, and first phone number

The categoryTree and contactReasonTree custom attributes are synced as their display names rather than IDs. For tree attributes with several levels, the names are joined with commas. The field picker lists the attributes on recent conversations plus every conversation custom attribute defined in your org. Customer and agent fields, including custom attributes, are offered the same way. Each one is synced only if you select it. Conversations, messages, and notes deleted in Kustomer are marked as deleted in Rippit.

API endpoints

Authentication

Purpose	Endpoint	Method
Key check, which also reads the org the key belongs to	`/v1/auth/tokens/current`	GET
Credential check, conversation access	`/v1/conversations`	GET

Conversations, messages, and people

Object	Endpoint	Method
Conversations changed since the last sync	`/v1/conversations?pageSize=1000&sort=desc`	GET
Conversations, by ID	`/v1/conversations/<id>`	GET
A conversation’s handle time	`/v1/conversations/<id>/times`	GET
Messages changed since the last sync	`/v1/messages?pageSize=1000&sort=desc`	GET
A conversation’s messages, to re-sync it	`/v1/conversations/<id>/messages`	GET
Notes changed since the last sync	`/v1/notes?pageSize=1000&sort=desc`	GET
A conversation’s notes, to re-sync it	`/v1/conversations/<id>/notes`	GET
A message’s attachments	`/v1/messages/<id>/attachments`	GET
Attachments, by ID, to refresh a download URL	`/v1/attachments/<id>`	GET
All agents	`/v1/users?userType=user&pending=false`	GET
Agents, by ID	`/v1/users/<id>`	GET
Customers, by ID	`/v1/customers/<id>`	GET
Tags	`/v1/tags`	GET
Shortcuts	`/v1/shortcuts`	GET
Conversation custom attribute definitions	`/v1/metadata/conversation`	GET
Sample records and attribute definitions, for field discovery	`/v1/conversations`, `/v1/customers`, `/v1/users`, `/v1/metadata/customer`, and `/v1/metadata/user`	GET
Attachment files	The `links.related` URL on each attachment, as returned by Kustomer	GET

The list endpoints page with the links.next value in each response, and Rippit follows it until it is absent. Customers and agents are not read as a full list for each sync. Rippit fetches the customer on each message, and the agents assigned to or first responding on each conversation, by ID. Requests by ID send a comma-separated list of up to 100 IDs, or 99 for customers. Kustomer attachment URLs expire within minutes, so before downloading each file Rippit refetches the attachment by ID to get a fresh URL.

Sync behavior


Conversation discovery	Newest first by last updated time, read back until reaching records already synced
Messages and notes	Their own lists, read the same way, so a new message or note is picked up without refetching its conversation
Trailing buffer	Each sync reads up to 5 minutes before the current time
Handle time	Fetched for each conversation listed in a sync
Customers	Fetched by ID as messages reference them. Customers missing from conversations synced in the last 7 days are fetched by ID once a day
Agents, tags, shortcuts, and custom attribute definitions	Full list on every sync
Attachments	Downloaded after their message syncs. Downloads that failed in the last 5 days are retried once a day
Update handling	An updated conversation, message, or note is listed again and replaced with the latest copy
Resumption	High water mark on last updated time. Changed records only, no full rescan

Rate limiting

Kustomer limits API calls for each org. Rippit reads x-ratelimit-limit and x-ratelimit-remaining on each response and slows down as the remaining budget runs low. Requests by ID run up to 10 at a time.

Getting Started

Connecting your Data

Using Rippit

Connecting to your AI Agent

Use cases

Reference

Connection summary

Before you connect

Data handling

What a conversation becomes in Rippit

API endpoints

Authentication

Conversations, messages, and people

Sync behavior

Rate limiting

​Connection summary

​Before you connect

​Data handling

​What a conversation becomes in Rippit

​API endpoints

​Authentication

​Conversations, messages, and people

​Sync behavior

​Rate limiting

Connection summary

Before you connect

Data handling

What a conversation becomes in Rippit

API endpoints

Authentication

Conversations, messages, and people

Sync behavior

Rate limiting