Zendesk
This guide explains how to integrate Zendesk with Bloomreach.
The Zendesk integration helps your support team handle customer support tickets. It helps you pass support ticket events, pass customer updates and events, and display customer data in the Bloomreach Zendesk sidebar.
Before you set up the integration, make sure you meet the prerequisites below. The integration supports customers, customer properties, and events.
Prerequisites
- A Bloomreach project with access to scenarios and integrations.
- A Zendesk account with admin permissions to create webhooks and triggers.
- Managed Endpoints API, to set up the Zendesk sidebar widget.
Bloomreach Zendesk sidebar widget
The Bloomreach Zendesk sidebar app lets all Zendesk Service users view customer data stored in Bloomreach when that customer has interacted with your support team.
The app helps you prioritize your tickets efficiently. For example, if you get 100 support tickets at once, you want to respond first to customers in the highest lifetime value or RFM segment. The app shows you task priority, so you can see what to do first.
The widget also gives you a full view of your customers, because all Bloomreach data is available inside the sidebar app. You can work with customer attributes, segmentations, detailed aggregates, lifetime value, loyalty tier, recent interactions with your product, and other data linked to the full customer profile in Bloomreach. This helps you deliver a personalized experience to your customers with your Support team.

Follow these steps to start using the Bloomreach Zendesk sidebar app.
Step 1: Install the app
Install the app from the Zendesk Marketplace. During installation, configure the fields in this table:
| Required field | Where to find the information |
|---|---|
| Title | The title displays as the headline of the sidebar widget. Example: Customer Details. |
| Hostname | Get this from the URL you use to log in to your Bloomreach project. Make sure the URL doesn't contain https or //. The value of this field should be demoapp.bloomreach.com. |
| Project Name | Enter your project name, which you can also find in your project URL. For example, if your URL is https://demoapp.exponea.com/p/clientproject/home, the project name is "clientproject". |
| Project Token | To find your project token, read Project settings first. It looks like this: cc7cc3c6-6b36-a11b-ffaa-52f58fe58f19. |
| API Base URL | Go to Project Settings > API Base URL in the Bloomreach app. For example: api-demoapp.exponea.com. |
| API Key ID and API Key Secret | Go to Project settings > Project > Access management > API. Generate an API key pair that belongs to a private group you create. Give the private group read-only access to Managed Endpoints API and all other fields you're interested in. To learn more about API groups and their settings, read the authentication article. |

Installation process of the Zendesk Sidebar Application
Step 2: Configure the fields
The final step of the installation is to configure the fields you want to display. You do this using Managed Endpoints API.
Follow the guide to configuring Managed Endpoints API in the Bloomreach app. Enable the managed endpoint, then copy the URL for this endpoint into the Bloomreach Managed Endpoint API URL field.
The managed endpoint payload is fully custom and should look like this:
{
"Name": "{{ customer.first_name }} {{ customer.last_name }}",
"Email engagement": "{{ segmentations['5fc3d611a59cf881d45b2ff6'] }}",
"Last cart update": "{{ expressions['5f5776b57e8f28c9c93d2c90'] | from_timestamp('US') }}",
"html": "<b>Recommendations:</b><table>{% for item in recommendations('5f5b6aabd0ef9bf5633ea54b', 8) %}<tr><td><a href='{{ item.url }}' target=_blank><img src='{{ item.image }}' width=64></a></td><td><a href='{{ item.url }}' target=_blank>{{ item.title }}</a></td></tr>{% endfor %}</table>"
}Step 3: Configure the webhook
If you want to send data and updates to Bloomreach, the webhook is already created for you automatically. The next two sections explain how to link triggers to the webhook and set their conditions and other details.
Send data from Zendesk to Bloomreach
Use these steps to send support_ticket events from Zendesk to Bloomreach.
Step 1: Link the webhook to a trigger
The webhook was created automatically through the Zendesk sidebar. Next, link it to a trigger in Zendesk. Go to Admin > Objects and rules > Business Rules > Triggers. Then create a new trigger and give it a name, description, and category.
Under Conditions, specify when the trigger runs. To notify Bloomreach when a ticket is created and then closed or solved, use the logic in this image.

Under Actions, select Notify active webhook and choose your webhook from the second dropdown.
You need to configure the request body that's sent when the webhook triggers. It must follow the format of the Bloomreach API endpoint. This example uses the Add Event endpoint.
You can also use the Customer Update endpoint, or the Batch endpoint to combine a customer update and an event addition in a single API call.
{
"customer_ids": {
"registered": "{{ticket.requester.email}}"
},
"properties": {
"body": "{{ticket.description}}",
"status": "{{ticket.status}}",
"subject": "{{ticket.title}}",
"type": "{{ticket.ticket_type}}",
"ticket_id": "{{ticket.id}}",
"priority": "{{ticket.priority}}",
"support_suite": "Zendesk"
},
"event_type": "support_ticket"
}Zendesk placeholders as Jinja tokens
Zendesk placeholders work the same way as Jinja tokens in Bloomreach. When you use them, they pass dynamic values in the body of your API request. For example: {{ticket.requester.email}}.
You can even run functions on top of placeholders, just like in Jinja. Placeholders use the Liquid language, so you can add functions with Liquid markup. For example: {{ticket.requester.email | downcase }}.
To learn more about Liquid functions, read the introduction to Liquid.
Step 2: Check if trigger works correctly
Once you're done, save your trigger and make sure it's active. Then go to the regular Zendesk Support UI and create a test ticket to check that your webhook and trigger work as expected.
Send data from Bloomreach to Zendesk
Before you start, it helps to get familiar with Zendesk's API. Read the Zendesk developer platform.
Step 1: Set up the Zendesk API endpoint
The endpoint is Create or Update User (more info in Zendesk's API reference). The Zendesk API requires Base64 encoding of your username and API token.
First, generate a new Zendesk API token. Go to Admin > Apps and integrations > APIs > Zendesk API > Settings.
Copy your API token and save it somewhere safe.
Step 2: Webhook template integration
In the Bloomreach app, create a new webhook template integration. After you add a description, use a POST request. The URL of the endpoint should look like this:
POST https://{your_subdomain}.zendesk.com/api/v2/users/create_or_update
{your_subdomain} is your Zendesk subdomain. For example, use acme for acme.zendesk.com.
Example of the payload:
{
"user": {
"email": "{{ customer_ids.registered }}",
"name": "{{ customer.first_name ~ " " ~ customer.last_name }}",
"user_fields": {
"rfm": "{# RFM #}{{ segmentations[‘,YOUR SEGMENT ID>’] }}",
"lifetimevalue": "{# Lifetime value ($) #}{{aggregates['<YOUR
AGGREGATE ID>'] }}"
}
}
}How does it work?
The endpoint looks for a customer based on the email field. If no customer has that email, it creates one. If a customer exists, it updates the record. Values in the request overwrite the customer's existing values.
You can customize this payload to include any fields you want to pass from Bloomreach to Zendesk. These can be regular customer fields in Zendesk, custom user fields that you defined in your Zendesk instance, or both.
Possible error messagesIf you send a field that isn't defined in Zendesk, the API doesn't return an error. It ignores that field.
If you send a value that doesn't match the field's data type (for example, string, integer, decimal, or boolean), the API returns an error.
Step 3: Finish the setup
It processes the response as JSON. Add a throughput policy and consent category if needed, then save it. You can now use the saved Zendesk webhook in a scenario in the Bloomreach app.
Limitations
Zendesk limits this endpoint to 5 requests per minute for each end user profile. The limit counts per user, so you can send 10 requests in one minute if 5 go to one user and 5 to another. You should also follow the Retry-After header values. Learn about Zendesk limits from their Rate limits documentation.
Updated 5 days ago

