Skip to main content
  1. Assembled
  2. Integrations
  3. Other contact platforms

How to connect Kustomer

Updated

Assembled integrates with the Kustomer contact platform allowing your ticket data to be forecasted and tracked in our system. This article will walk through how to setup the integration and verify the data Assembled pulls in is correct.

Preparing your Kustomer data for Assembled

Before you connect your Kustomer instance to Assembled, we recommend working with your team’s Kustomer administrator to prepare your Kustomer data as follows:

  • Channel: Assembled’s Kustomer integration requires that all Kustomer conversations have an assigned value in the channel field. Assembled can ingest Kustomer conversations that have one of the following values in the Kustomer channel field: email, chat, voice, sms, facebook, twitter-dm, twitter-tweet, instagram.
  • Conversation properties: Assembled can create queues based on one of the following conversation properties. If you plan to separate your Kustomer data into multiple queues within Assembled, you should ensure that each Kustomer conversation has one of the following properties:
    • Tag
    • Channel
    • Last Message Meta Queue
    • Queue Name
    • Queue ID
    • Assistant Name
    • Assistant Status
    • Assigned Team

  • API Key: Below is a list of the necessary API key permissions and the use case for each permission:

    For ticket data, you will need to enable:

    • org.permission.search.read
    • org.permission.conversation.read
    • org.permission.message.read
    • org.permission.search.create

    For agent state data, you will need to enable:

    • org.permission.read
    • org.permission.customer.read
    • org.permission.routing.read

Connecting to Kustomer

Connecting Kustomer to Assembled allows Assembled to make API requests to the Kustomer API on behalf of your Kustomer account. As a result, this will cause an overall increase in your Kustomer API usage. We pull data from Kustomer at a maximum rate of 500 requests per minute.

  • To connect your Kustomer instance to your Assembled instance, you will first need to create a Kustomer API key within Kustomer with all the necessary API key permissions.

  • Once you have created this API key, select Kustomer from the Assembled Third-party integrations page (Available tab). You will be prompted to enter the Kustomer API key. You should then click Connect with Kustomer.

    Kustomer connection window listing the required permission scopes, the API key field and the Connect with Kustomer button

  • If you have successfully connected to Kustomer, you will see a Synced, Sync in progress, or Connected field on the Kustomer-specific card in Assembled’s Configure > Third-party integrations page.Kustomer card on Configure > Third-party integrations showing Connected, Backfilled until 6 years ago, Manage queues, mappings, and exclusions, Authorized 1 year ago, and Outbound webhook Enabled

If you run into any issues during this step, please reach out to our Support team.

Verifying the connection

There are two places in Assembled for you to verify if the Kustomer integration has been correctly added: the Real-time agent analysis (Monitor > Real-time agent analysis) and the Staffing timeline.

The Real-time agent analysis (shown below) will display agent states and current adherence. Use these dashboards to make sure agent states from Kustomer are being synced to Assembled correctly.

Real-time agent analysis filtered to Source: Kustomer, listing agents with their current state and state duration (agent names blurred)

The Staffing timeline displays the contacts of Kustomer. Select New and Reopened Cases to see a line graph displaying how many tickets over time. This graph will show if the sync for tickets is working.

Staffing timeline New and reopened cases tab showing forecasted and actual cases by channel over the day

If either of these display zero or abnormal numbers, please reach out to our Support team.

Adding agents from Kustomer

To add agents into Assembled directly from Kustomer, you can follow the steps in our People management page guide (Manage team > People management). In addition, please note that Assembled will map Kustomer’s users with the following permission levels:

Kustomer Assembled
Agent Standard

Setting up Assembled queues for Kustomer conversations

To set up your Assembled queues for your new Kustomer integration, we recommend following the steps in our queue configuration guide.

In addition, please note the following Kustomer-specific details:

  • Assembled will map Kustomer channels to Assembled channels as follows:

    Kustomer Assembled
    voice Phone
    chat Chat
    email Email
    sms SMS
    facebook, twitter-dm, twitter-tweet, instagram Social
  • Assembled automatically excludes outbound Kustomer conversations (direction field = out).
  • For multi-channel tickets, Assembled uses the channel of the first message.
  • Any conversations for which the channel field is blank will be automatically excluded from Assembled.
  • Within Assembled, you can create queues based on the following Kustomer attributes:

Add queue rule for Kustomer dialog with the Ticket property list open: Assigned Team, Assistant Name, Assistant Status, Channel, Last Message Meta Queue, Queue ID, Queue Name, Tag

Setting up Assembled agent states for Kustomer

To set up your Assembled agent states for your new Kustomer integration, we recommend following the steps in our agent states setup guide.

Configure > Agent states Mappings tab filtered to Platform: Kustomer, listing agent states with their matched events and channels

Understanding how Kustomer data maps to data attributes in Assembled

We track the SLA for calls via the meta.answeredAt - meta.placedAt metrics from Kustomer.

We track the SLA for chats, social and SMS via the first_responded_at - external_created_at metrics. We track the SLA for e-mails via the first_responded_at - external_created_at metric. If you would like us to calculate first response times based on business hours, please reach out to our Support team.

Conversation data (Email)

Kustomer Assembled
firstResponse.createdAt (if present) OR externalTimestamp (if firstResponse is empty but earliestResponseMessage is not) first_responded_at
first_responded_at - external_created_at OR firstResponse.businessTime/1000 (if kustomer.use_business_time is turned on) (SLA) first_response_duration

Conversation data (Chat, SMS, Social)

Kustomer Assembled
firstResponse.createdAt (if present) OR externalTimestamp (if firstResponse is empty but earliestResponseMessage is not) first_responded_at
first_responded_at - createdAt OR firstResponse.businessTime/1000 (if kustomer.use_business_time is turned on) (SLA) first_response_duration

Conversation data (Phone)

Kustomer Assembled
meta.answeredAt first_responded_at
meta.answeredAt - meta.placedAt (SLA) first_response_duration

Conversation status

Kustomer Assembled
open open
snoozed snoozed
done closed
  empty

What Assembled syncs from Kustomer

Once connected, Assembled runs these sync jobs:

Sync job What it syncs How often
backfill Historical data, up to 5 years back from when the sync job was created As fast as possible
default New and updated conversations Every minute
agent_states Agent states Every 15 seconds

Assembled calls these Kustomer endpoints:

Kustomer endpoint Data How often Assembled calls it
/v1/customers/search Ticket data Every minute (higher during the initial backfill)
/v1/conversations Ticket data Every minute (higher during the initial backfill)
/v1/conversations/<conversationId>/events Ticket event data Every minute (higher during the initial backfill)
/v1/conversations/<conversationId>/messages Ticket data Every minute (higher during the initial backfill)
/v1/routing/queues Queue data Every 15 seconds
/v1/routing/statuses Agent states Every 15 seconds
/v1/routing/work-sessions Ticket event data Every 15 seconds
/v1/assistants Ticket data (mainly chatbots) Every 15 seconds
/v1/tags Queue data On demand
/v1/teams Queue data On demand
/v1/users User data On demand

Kustomer shares one API rate limit across all endpoints: 1,000 requests per minute, or 2,000 on the Ultimate plan. Assembled pulls at most 500 requests per minute.

Assembled stores conversation data by default. You can limit the data the Kustomer API returns to Assembled.

FAQs

  • Q: What should I do if I see a sync invalid from the Kustomer integration in Configure > Third-party integrations ?
    • A: This could mean a few things so we recommend hovering over the message :
      • If you see any 400 errors those usually are permissions-related. This sometimes happens when the person who originally authorized does not have proper permissions, the person who originally authorized leaves the company, or if someone changed the permissions settings. In order to continue to have data flowing into Assembled and receive accurate reporting, you will need someone with admin permissions to reauthorize the sync.Kustomer card with a Sync invalid badge and the Issue detected tooltip showing a 401 Unauthorized error
      • If you see a generic error please reach out to our Support Team and we can help diagnose the root cause.
  • Q: What do I do if all my tickets are getting excluded but I do not have any exclusions set up ?
    • A: The most common reason is that you are using Kustomer channel values that are not listed on this page. If that's the case, please reach out to the Support Team and we can help set up these values for you.

Related articles

Still have questions?