Zendesk Chat is a contact platform that is mainly used for chats. More information about Zendesk Chat can be found here. In order to connect to Zendesk Chat you will first need to connect to Zendesk support.
This article will walk through how to set up the integration and verify the data Assembled pulls in is correct.
Preparing Zendesk Chat for Assembled
Before you connect your Zendesk Chat instance to Assembled, we recommend working with your team’s Zendesk Chat administrator to prepare your Zendesk Chat data as follows:
-
Channel: Assembled’s Zendesk Chat integration requires that all Zendesk Chat tickets be mapped to a specific channel, using the Zendesk Chat channel field. Assembled can ingest Zendesk Chat cases that have one of the following values in the Zendesk Chat channel field:
chat -
Ticket fields : Assembled can create queues based on one of the following ticket fields. If you plan to separate your Zendesk Chat data into multiple queues within Assembled, you should ensure that each Zendesk Chat case has one of the following fields:
- Department ID
- Ticket tag
Connecting to Zendesk Chat
Assembled connects to Zendesk Chat via OAuth 2.0 which allows Assembled to make API requests I on behalf of your account. As a result, this will cause an overall increase in your API usage. We pull data from Zendesk Chat at a rate of 200 requests / minute.
To connect your Zendesk Chat instance to your Assembled instance, you will need a Zendesk Chat admin to navigate to Assembled's Configure > Third-party integrations > Available and click Connect integration on the Zendesk Chat card. You can type Zendesk Chat in the search box to find it.
IMPORTANT: any changes to the Zendesk Chat admin's account that affect the permissions- such as the account being deleted- will break the integration in Assembled.
If the admin who enabled the integration is leaving, a new Zendesk Chat admin will need to disable and then re-enable the integration to use their permissions and prevent a loss of data.
If you have successfully connected to Zendesk Chat, you will see a Synced, Sync in progress, or Connected field on the Zendesk Chat-specific card in Assembled’s Configure > Third-party integrations page.
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 Zendesk Chat integration has been correctly added: the Real-time agent analysis page (Monitor > Real-time agent analysis) and the Staffing timeline.
-
The Monitor > Real-time agent analysis page will display agent states and current adherence. Use this dashboard to make sure agent states from Zendesk Chat are being synced to Assembled correctly. To narrow the page to one platform, use Add filter and pick Source.
-
The Staffing timeline displays the contacts of Zendesk Chat. 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.
If either of these display zero or unexpected numbers that do not match your Zendesk Chat case volume, please reach out to our Support team.
Adding agents from Zendesk Chat
To add agents into Assembled you can follow the steps in our People management page guide. Agents can be added manually or in bulk via Import from Zendesk (under the Add person button), CSV upload, or through the API.
In addition, please note that Assembled will map Zendesk Chat’s users with the following permission levels:
| Zendesk Chat | Assembled |
|---|---|
| admin | Admin |
| agents | Standard |
Setting up Assembled queues for Zendesk Chat
To set up your Assembled queues for your new Zendesk Chat integration, we recommend following the steps in our queue configuration guide.
In addition, please note the following Zendesk Chat specific details:
-
Assembled will map Zendesk Chat channels to Assembled channels as follows:
Zendesk Chat Assembled chat chat - Any cases for which the channel field is blank will be automatically excluded from Assembled.
-
Within Assembled, you can create queues based on the following Zendesk Chat attributes:
Setting up Assembled agent states for Zendesk Chat
We use the agent timeline endpoint to collect information about agent states. This endpoint will pull in the following states : Away, Invisible, Offline, On chat, Online.
To set up your Assembled agent states for your new Zendesk Chat integration, we recommend following the steps in our agent states setup guide.
Note: if an agent is in a different state in Zendesk Chat from what you’re seeing in Assembled, please reach out to Support.
Understanding how Zendesk Chat data maps to data attributes in Assembled
Ticket data (chat)
| Zendesk Chat | Assembled |
|---|---|
| response_time.first (SLA) | firstResponseDurationSeconds |
| zendesk_ticket_id | importedId |
| id | zendeskChatId |
| tags | tags |
| timestamp + response_time.first | firstRespondedAt |
| timestamp | chatStartedAt |
| timestamp + duration | chatEndedAt |
| Zendesk Chat (if chat was updated) | Assembled (if chat was updated) |
| updateTimestamp | externalUpdatedAt |
Ticket status
| Zendesk Chat | Assembled |
|---|---|
| status | solved |
FAQs
- Q: What should I do if I see a sync invalid from the Zendesk 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.
- If you see a generic error please reach out to our Support Team and we can help diagnose the root cause.
-
- A: This could mean a few things so we recommend hovering over the message :
- Q: What if an agent’s state is not showing up in Assembled after a few minutes ?
- A: There is a 5-minute delay from their API to update agent states. i.e. We’re only able to retrieve Zendesk Chat states older than 5 minutes. So at 6 pm, for example, we can only know what happened as of 5:55 pm. To mitigate this, we can turn on a feature flag to make this faster, but it’ll result in the loss of occupancy metrics & the
On Chatstate. If you like to turn this on for your account, please reach out to our Support team
- A: There is a 5-minute delay from their API to update agent states. i.e. We’re only able to retrieve Zendesk Chat states older than 5 minutes. So at 6 pm, for example, we can only know what happened as of 5:55 pm. To mitigate this, we can turn on a feature flag to make this faster, but it’ll result in the loss of occupancy metrics & the
- Q: Why don’t I see any “open”, “pending” or “on hold” chat tickets in the Real-time overview ?
- A: By default, we do not merge Zendesk chat and Zendesk email tickets. This means that if a ticket moves from chat to email, we will not get ticket status updates on the ticket. Therefore the ticket will stay in the chat channel and we will not count reopens. If you would like to discuss merging and the repercussions of making this switch, please reach out to our support team.