The Kustomer connector lets your AI agent act in each user's Kustomer account. Each user connects their own Kustomer access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 26 tools.
- Tools
- 26
- What they doRead · write · destructive
- 17 · 9 · 017 read9 write0 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Kustomer connection
In AgentKit > Connections, create a Kustomer connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'kustomer'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Kustomer:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'kustomer_current_user_get',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "kustomer"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Kustomer:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="kustomer_current_user_get",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Kustomer credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolkustomer_companies_listList companies, optionally by name or external ID.Read-onlyList Companies
List companies, optionally by name or external ID. Returns data[] of companies with name, externalId, domains, emails, phones and tags. Use kustomer_companies_list to find a company ID. Needs the API key role org.permission.company.read (legacy org.user.company.read); without it Kustomer returns 401.
Inputs
external_idstring- Your external ID for the company. Example: acct-2201
filterstring- Company name to filter by. Example: Acme
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
kustomer_company_getGet one company by ID.Read-onlyGet Company
Get one company by ID. Returns the company's name, externalId, domains, contact details, tags and custom attributes. Use kustomer_company_get for a known ID. Needs the API key role org.permission.company.read (legacy org.user.company.read); without it Kustomer returns 401.
Inputs
company_idstringrequired- ID of the company (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
kustomer_conversation_getGet one conversation by ID, or several with comma-separated IDs.Read-onlyGet Conversation
Get one conversation by ID, or several with comma-separated IDs. Returns status, priority, channels, customer, assignment, tags, SLA metrics and message counts. Use kustomer_conversation_get for a known ID. Needs the API key role org.permission.conversation.read (legacy org.user.conversation.read); without it Kustomer returns 401.
Inputs
conversation_idstringrequired- ID of the conversation (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
includestring- Set to customer to side-load the customer. Example: customerone of
customer
kustomer_conversation_messages_listList the messages in a conversation.Read-onlyList Conversation Messages
List the messages in a conversation. Returns data[] of messages with channel, direction, preview, subject, sentAt, createdBy and attachments. Use kustomer_conversation_messages_list to read a conversation. Use kustomer_conversation_notes_list for internal notes. Needs the API key role org.permission.message.read (legacy org.user.message.read); without it Kustomer returns 401.
Inputs
conversation_idstringrequired- ID of the conversation (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
channelstring- Only messages on this channel. Example: emailone of
emailsmschatfacebooktwitter-dmtwitter-tweetvoiceinstagramwhatsapp pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
sortstring- Sort order; prefix a field with - for descending. Example: createdAt
kustomer_conversation_notes_listList the internal notes on a conversation.Read-onlyList Conversation Notes
List the internal notes on a conversation. Returns data[] of notes with body, userMentions, createdBy and createdAt. Use kustomer_conversation_notes_list to read agent notes. Needs the API key role org.permission.note.read (legacy org.user.note.read); without it Kustomer returns 401.
Inputs
conversation_idstringrequired- ID of the conversation (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
sortstring- Sort order; prefix a field with - for descending. Example: createdAt
kustomer_conversations_listList the organization's conversations with paging.Read-onlyList Conversations
List the organization's conversations with paging. Returns data[] of conversations with name, status, priority, customer, assignedUsers, assignedTeams, tags and timestamps. Use kustomer_conversations_list to browse. Use kustomer_search for open conversations or other filters. Needs the API key role org.permission.conversation.read (legacy org.user.conversation.read); without it Kustomer returns 401.
Inputs
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
populate_linked_conversationsboolean- true to fill in linked conversation fields. Example: false
sortstring- Sort order; prefix a field with - for descending. Example: desc
kustomer_current_user_getGet the user behind the API key (for an API key, its machine user).Read-onlyGet Current User
Get the user behind the API key (for an API key, its machine user). Returns data with the user id, name, email, userType and roles. Works with any valid API key.
Inputs
This tool takes no inputs.
kustomer_customer_conversations_listList one customer's conversations.Read-onlyList Customer Conversations
List one customer's conversations. Returns data[] of conversations with name, status, channels, priority, assignedUsers, assignedTeams, tags and timestamps. Use kustomer_customer_conversations_list to see a customer's history. Use kustomer_conversation_messages_list for a conversation's messages. Needs the API key role org.permission.conversation.read (legacy org.user.conversation.read); without it Kustomer returns 401.
Inputs
customer_idstringrequired- ID of the customer (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
kustomer_customer_getGet one customer by ID, or several with comma-separated IDs.Read-onlyGet Customer
Get one customer by ID, or several with comma-separated IDs. Returns the customer with name, emails, phones, externalId, tags, custom attributes and conversation counts. Use kustomer_customer_get for a known ID. Use kustomer_customer_get_by_email to find by email. Needs the API key role org.permission.customer.read (legacy org.user.customer.read); without it Kustomer returns 401.
Inputs
customer_idstringrequired- ID of the customer (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
includestring- Set to company to side-load the customer's company. Example: companyone of
company
kustomer_customer_get_by_emailFind a customer by email address.Read-onlyGet Customer by Email
Find a customer by email address. Returns the matching customer, or 404 when no customer has that email. Use kustomer_customer_get_by_email before kustomer_customer_create to avoid duplicates. Needs the API key role org.permission.customer.read (legacy org.user.customer.read); without it Kustomer returns 401.
Inputs
emailstringrequired- Customer email address. Example: jane@example.com
includestring- Set to company to side-load the customer's company. Example: companyone of
company
kustomer_customer_messages_listList messages to and from one customer across conversations.Read-onlyList Customer Messages
List messages to and from one customer across conversations. Returns data[] of messages with channel, direction, preview, subject, sentAt and conversation. Use kustomer_customer_messages_list for a customer's recent messages. Needs the API key role org.permission.message.read (legacy org.user.message.read); without it Kustomer returns 401.
Inputs
customer_idstringrequired- ID of the customer (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
channelstring- Only messages on this channel. Example: emailone of
emailsmschatfacebooktwitter-dmtwitter-tweetvoiceinstagramwhatsapp pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
sortstring- Sort order; prefix a field with - for descending. Example: -createdAt
kustomer_customer_notes_listList internal notes on one customer's conversations.Read-onlyList Customer Notes
List internal notes on one customer's conversations. Returns data[] of notes with body, createdBy, conversation and createdAt. Use kustomer_customer_notes_list to read agent notes about a customer. Needs the API key role org.permission.note.read (legacy org.user.note.read); without it Kustomer returns 401.
Inputs
customer_idstringrequired- ID of the customer (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
kustomer_customers_listList customers, by default newest activity first, with paging.Read-onlyList Customers
List customers, by default newest activity first, with paging. Returns data[] of customers (id, attributes with name, emails, phones, tags, lastActivityAt) plus links and meta. Use kustomer_customers_list to browse. Use kustomer_search for filtered queries and kustomer_customer_get_by_email to look up one person. Needs the API key role org.permission.customer.read (legacy org.user.customer.read); without it Kustomer returns 401.
Inputs
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
sortstring- Sort order; prefix a field with - for descending. Example: -createdAt
kustomer_message_getGet one message by ID.Read-onlyGet Message
Get one message by ID. Returns channel, direction, preview, subject, meta (such as email addresses), attachments, conversation and customer. Use kustomer_message_get for a full message. Needs the API key role org.permission.message.read (legacy org.user.message.read); without it Kustomer returns 401.
Inputs
message_idstringrequired- ID of the message (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
kustomer_searchSearch customers, conversations, messages, companies or notes with attribute filters, sorting and paging (records updated in the last 2 years).Read-onlySearch
Search customers, conversations, messages, companies or notes with attribute filters, sorting and paging (records updated in the last 2 years). Returns data[] of the chosen record type plus meta.total; at most 10,000 matches can be paged. Use kustomer_search for filtered queries such as open conversations or customers by attribute. Use the list tools to browse without filters. Needs the API key role org.permission.search.create or org.permission.search.update (legacy org.user.search.read or org.admin.search.read); without it Kustomer returns 401.
Inputs
query_contextstringrequired- Record type to return: customer, conversation, message, company, note, kobject (or kobject_<klassName>), conversation_time, work_session or work_item. Example: conversation
andarray- Criteria that must all match; each is {"<attribute>": {"<operator>": value}} with operators such as equals, contains, gte, lte, gt, lt. Example: [{"conversation_status": {"equals": "open"}}, {"conversation_updated_at": {"gte": "2026-11-01T00:00:00Z"}}]
orarray- Criteria where any one must match, same shape as and. Example: [{"customer_emails": {"equals": "jane@example.com"}}, {"customer_phones": {"equals": "+15555550100"}}]
pageinteger- Page number. Example: 1
page_sizeinteger- Results per page, up to 500; 0 returns only counts. Example: 100
sortarray- Sort order as [{"<attribute>": "asc|desc"}]. Example: [{"conversation_updated_at": "desc"}]
time_zonestring- Time zone for date-only values (default GMT). Example: America/New_York
kustomer_teams_listList the organization's teams.Read-onlyList Teams
List the organization's teams. Returns data[] of teams with name, displayName, members and roleGroups. Use kustomer_teams_list to find team IDs for assignment. Needs the API key role org.permission.team.read (legacy org.user.team.read or org.admin.team.read); without it Kustomer returns 401.
Inputs
deletedboolean- false to return only teams that are not deleted. Example: false
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
kustomer_users_listList the organization's users (agents, machine users and collaborators).Read-onlyList Users
List the organization's users (agents, machine users and collaborators). Returns data[] of users with name, email, userType, roles and teams. Use kustomer_users_list to find user IDs for assignment. Needs the API key role org.permission.user.read (legacy org.user.read); without it Kustomer returns 401.
Inputs
deletedboolean- true for only deactivated users, false for only active ones. Example: false
emailstring- Only the user with this email. Example: agent@example.com
pageinteger- Page number, starting at 1. Example: 2
page_sizeinteger- Results per page (up to 1000). Example: 100
pendingboolean- true for only users with a pending invitation, false for only active ones. Example: false
user_typestring- user (full users), machine (API users) or limited (collaborators). Example: userone of
usermachinelimited
kustomer_company_createCreate a company to group customers.WriteCreate Company
Create a company to group customers. Returns the new company with its id. Use kustomer_company_create, then set company on customers with kustomer_customer_update. Needs the API key role org.permission.company.create (legacy org.user.company.write); without it Kustomer returns 401.
Inputs
namestringrequired- Company name (3 to 256 characters). Example: Acme Inc
domainsarray- Domains, each {"domain": ...}. Example: [{"domain": "acme.com"}]
emailsarray- Emails, each {"email": ..., "type": "work"}. Example: [{"type": "work", "email": "billing@acme.com"}]
external_idstring- Your system's ID for the company. Example: acct-2201
phonesarray- Phones, each {"phone": ..., "type": "work"}. Example: [{"type": "work", "phone": "+15555550101"}]
tagsarray- Tag names. Example: ["enterprise"]
kustomer_company_updateUpdate a company; the attributes you send are merged in.WriteUpdate Company
Update a company; the attributes you send are merged in. Returns the updated company. Use kustomer_company_update to change a company's name, domains or tags. Needs the API key role org.permission.company.update (legacy org.user.company.write); without it Kustomer returns 401.
- Idempotent
Inputs
company_idstringrequired- ID of the company to update (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
domainsarray- Domains, each {"domain": ...}. Example: [{"domain": "acme.com"}]
emailsarray- Emails, each {"email": ..., "type": "work"}. Example: [{"type": "work", "email": "billing@acme.com"}]
external_idstring- Your system's ID for the company. Example: acct-2201
namestring- Company name (3 to 256 characters). Example: Acme Incorporated
phonesarray- Phones, each {"phone": ..., "type": "work"}. Example: [{"type": "work", "phone": "+15555550101"}]
tagsarray- Tag names. Example: ["enterprise"]
kustomer_conversation_createCreate a conversation for a customer; nothing is sent to the customer.WriteCreate Conversation
Create a conversation for a customer; nothing is sent to the customer. Returns the new conversation with its id. Use kustomer_conversation_create, then kustomer_conversation_message_create to add messages or kustomer_conversation_note_create for internal notes. Needs the API key role org.permission.conversation.create (legacy org.user.conversation.write); without it Kustomer returns 401.
Inputs
customerstringrequired- ID of the customer the conversation belongs to. Example: 5faaf4a6ea0cb48cd0801bbe
assigned_teamsarray- Team IDs to assign (up to 10). Example: ["5faaf4a6ea0cb48cd0801bc2"]
assigned_usersarray- User IDs to assign (up to 10). Example: ["5faaf4a6ea0cb48cd0801bc1"]
customobject- Custom attributes with type suffixes. Example: {"orderNumberStr": "1001"}
directionstring- in if the customer started it, out if your team did. Example: inone of
inout external_idstring- Your thread ID. Example: thread-88231
namestring- Conversation subject shown to agents. Example: Order 1001 arrived damaged
priorityinteger- Priority from 1 (lowest) to 5 (highest). Example: 3
statusstring- open or done (update also allows snoozed). Example: openone of
opendone tagsarray- Tag names (up to 20). Example: ["damaged"]
kustomer_conversation_message_createRecord a message in a conversation, for example from a custom channel; this logs the message and does not send it to the customer.WriteCreate Conversation Message
Record a message in a conversation, for example from a custom channel; this logs the message and does not send it to the customer. Returns the new message with its id. Use kustomer_conversation_message_create to import messages. Use kustomer_conversation_note_create for internal notes. Needs the API key role org.permission.message.create (legacy org.user.message.write); without it Kustomer returns 401.
Inputs
appstringrequired- Name of the app or system the message comes from. Example: acme-inbox
channelstringrequired- Message channel. Example: chatone of
emailsmschatfacebooktwitter-dmtwitter-tweetvoiceinstagramwhatsapp conversation_idstringrequired- ID of the conversation (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
directionstring- in for a customer message, out for one from your team. Example: inone of
inout external_idstring- Your message ID, so it is imported only once. Example: msg-55120
previewstring- Message text (up to 10,240 characters). Example: My order arrived damaged.
sent_atstring- When the message was sent (ISO 8601). Example: 2026-11-15T10:00:00Z
subjectstring- Subject line. Example: Order 1001
kustomer_conversation_note_createAdd an internal note to a conversation; notes are visible to agents only.WriteCreate Conversation Note
Add an internal note to a conversation; notes are visible to agents only. Returns the new note with its id. Use kustomer_conversation_note_create to leave context for agents. Needs the API key role org.permission.note.create (legacy org.user.note.read); without it Kustomer returns 401.
Inputs
bodystringrequired- Note text (1 to 10,240 characters). Example: Customer sent photos; approved replacement.
conversation_idstringrequired- ID of the conversation (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
external_idstring- Your note ID. Example: note-771
user_mentionsarray- Users or teams to mention, each {"user": id} or {"team": id}. Example: [{"user": "5faaf4a6ea0cb48cd0801bc1"}]
kustomer_conversation_updateUpdate a conversation's status, priority, assignment, tags or custom attributes; the attributes you send are merged in.WriteUpdate Conversation
Update a conversation's status, priority, assignment, tags or custom attributes; the attributes you send are merged in. Returns the updated conversation. Use kustomer_conversation_update to close, reassign or reprioritize. Use kustomer_conversation_tags_add to add tags without replacing the list. Needs the API key role org.permission.conversation.update (legacy org.user.conversation.write); without it Kustomer returns 401.
- Idempotent
Inputs
conversation_idstringrequired- ID of the conversation to update (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
assigned_teamsarray- Team IDs to assign (up to 10). Example: ["5faaf4a6ea0cb48cd0801bc2"]
assigned_usersarray- User IDs to assign (up to 10). Example: ["5faaf4a6ea0cb48cd0801bc1"]
customobject- Custom attributes with type suffixes. Example: {"orderNumberStr": "1001"}
directionstring- in if the customer started it, out if your team did. Example: inone of
inout external_idstring- Your thread ID. Example: thread-88231
namestring- Conversation subject shown to agents. Example: Order 1001 arrived damaged
priorityinteger- Priority from 1 (lowest) to 5 (highest). Example: 3
statusstring- open, snoozed or done. Example: doneone of
opensnoozeddone tagsarray- Tag names (up to 20). Example: ["damaged"]
kustomer_customer_createCreate a customer record.WriteCreate Customer
Create a customer record. Returns the new customer with its id. Use kustomer_customer_create after kustomer_customer_get_by_email finds nothing. Use kustomer_customer_update to change an existing customer. Needs the API key role org.permission.customer.create (legacy org.user.customer.write); without it Kustomer returns 401.
Inputs
companystring- ID of the company the customer belongs to. On update, leaving it empty unlinks the customer from its company, so resend the current value. Example: 5faaf4a6ea0cb48cd0801bc0
customobject- Custom attributes; names end in a type suffix such as Str, Num, Bool, At or Url. Example: {"loyaltyTierStr": "gold"}
emailsarray- Email addresses (up to 10), each {"email": ..., "type": "home|work|other"}. Example: [{"type": "work", "email": "jane@example.com"}]
external_idstring- Your system's ID for the customer, unique in Kustomer. Example: crm-10293
localestring- Locale, such as en_US. Example: en_US
namestring- Customer's full name. Example: Jane Doe
phonesarray- Phone numbers (up to 10), each {"phone": ..., "type": "mobile|home|work|fax|other"}. Example: [{"type": "mobile", "phone": "+15555550100"}]
tagsarray- Tag names (up to 20). Example: ["vip"]
time_zonestring- IANA time zone. Example: America/New_York
usernamestring- Username. Example: janed
kustomer_customer_updateUpdate a customer; the attributes you send are merged into the record, except that leaving out company unlinks the customer from its company.WriteUpdate Customer
Update a customer; the attributes you send are merged into the record, except that leaving out company unlinks the customer from its company. Lists such as emails replace the stored list. Returns the updated customer. Use kustomer_customer_update to change details or tags. Needs the API key role org.permission.customer.update (legacy org.user.customer.write); without it Kustomer returns 401.
- Idempotent
Inputs
customer_idstringrequired- ID of the customer to update (24-character Kustomer ID). Example: 5faaf4a6ea0cb48cd0801bbf
companystring- ID of the company the customer belongs to. On update, leaving it empty unlinks the customer from its company, so resend the current value. Example: 5faaf4a6ea0cb48cd0801bc0
customobject- Custom attributes; names end in a type suffix such as Str, Num, Bool, At or Url. Example: {"loyaltyTierStr": "gold"}
emailsarray- Email addresses (up to 10), each {"email": ..., "type": "home|work|other"}. Example: [{"type": "work", "email": "jane@example.com"}]
external_idstring- Your system's ID for the customer, unique in Kustomer. Example: crm-10293
localestring- Locale, such as en_US. Example: en_US
namestring- Customer's full name. Example: Jane Doe
phonesarray- Phone numbers (up to 10), each {"phone": ..., "type": "mobile|home|work|fax|other"}. Example: [{"type": "mobile", "phone": "+15555550100"}]
tagsarray- Tag names (up to 20). Example: ["vip"]
time_zonestring- IANA time zone. Example: America/New_York
usernamestring- Username. Example: janed
No tools match.