Transactional surveys are sent when an external event is triggered. In simpler words, when something happens outside of Retently, a survey is triggered.
Retently email and in-app transactional surveys can be triggered by multiple external services.
In this article, we will cover how you can trigger a survey via Zendesk.
Set up Zendesk events for your survey campaign
IMPORTANT: Initially, the whole setup relied on Zendesk HTTP Targets (as they were the Zendesk object that could host the Retently webhook link). However, HTTP Targets got deprecated in February 2022, and now you will need to use Zendesk's Webhooks option, which works equally great and perfectly fits our transactional survey setup.
If you've been using HTTP Targets up until now, then the good news is that you can easily convert them to webhooks. Click here to reach Zendesk's official tutorial on migrating HTTP Targets to Webhooks.
Further in this article, we will cover the Webhooks setup.
Set up a Zendesk webhook
Zendesk webhooks let you notify external systems about a new ticket or a status change of an existing ticket. In our case, we will create a webhook containing the Retently webhook link. Therefore, whenever a specific trigger or automation is actioned, the notification will go through the webhook link and will trigger the transactional survey in Retently.
To create a new webhook, you will need to access the Admin area in your Zendesk workspace and go to the "Apps and integrations" section and click the "Webhooks" category.
On the Webhooks page, click the Actions menu and choose the "Create webhook" option.
In the target editor fill in the following fields:
Name: Give your target a name so that it’s easy to identify its purpose later.
Description (optional): You can add more details about how this webhook will be used. For example, it might host a webhook link from a particular Retently survey campaign that you'd want to list here for further reference.
Endpoint URL: Insert the Retently webhook link from the Setup page in your transactional campaign.
Request method: Make sure the “POST” option is selected.
Request format: Make sure “JSON” is selected. This is the format of the data that will be sent from Zendesk to Retently.
Authentication: Leave this option at "None".
Finally, hit the “Create webhook” button.
Now that you have successfully created the webhook, you can add it either to a Zendesk trigger or automation.
Configure a Zendesk trigger (or automation)
Zendesk supports both Triggers and Automations. The main difference between them is that:
Triggers are event-based
Automations are time-based
Other than that, the setup of both Triggers and Automations are identical. Further in this article, we will focus on Triggers mainly, but feel free to adapt this setup to Automations if you need to.
In your Admin Center, find the "Objects and rules" section, in the "Business rules" category access the "Triggers" page.
To create a new one, click the “Add trigger” button.
In the trigger editor, give it a name and description and configure the conditions that will eventually fire the trigger, and send a transactional survey in Retently.
For our tutorial, we have the following condition:
Next, scroll down the page, and in the Actions section, choose the “Notify active webhook” option and choose the Webhook that we've created in the previous chapter.
Once you select the webhook, an additional text input area will appear. In this area, you have to specify what data will be sent to Retently when your Zendesk trigger is activated. By default, Retently will accept the following data from your Zendesk workspace:
Email address of the contact (ticket requester);
First and last name of the contact;
Company name of the contact;
Tags that are assigned to the contact.
Note: From the properties listed above, only the email address is mandatory. The other properties are optional and you can delete them from the text area if needed.
This contact data is needed because before sending the transactional survey, the contact will be created as a new customer in your Retently account so that you can store their historical survey feedback and analyze their satisfaction with your company or product over time.
You can copy the following code:
{
"email": "{{ticket.requester.email}}",
"first_name": "{{ticket.requester.first_name}}",
"last_name": "{{ticket.requester.last_name}}",
"company": "{{ticket.organization.name}}",
"tags": "{{ticket.tags}}",
"ticket_id": "{{ticket.id}}",
"ticket_url": "{{ticket.url}}"
}
Finally, create your trigger. From now on, every time a ticket will match your trigger’s conditions, the contact will be added to Retently and a transactional email survey will be sent immediately or according to your campaign’s schedule.
Manage custom properties via Zendesk
Additionally to the default properties, you can also pass other Zendesk fields as custom properties.
Create customer property in Retently
Start with creating a customer property in your Retently account, in the "Props & Tags" category. To create a new one, click the "Create property" button.
A popup will ask you to write the name of the new property (ex: Subscription, Signup date, Product name, etc.) and choose the type of value that will be stored in the new property.
Retently supports the following four data types:
Text: The value will be stored as regular text.
Number: This property can store only numbers (this data type also supports numbers with decimals).
Collection: You can store an array of keywords (ex: "item 1, item 2, item 2").
After you have created the property, it will be available to be added to your JSON text field in the Zendesk advanced automation option.
Identify the property name
By default, in Retently props are displayed in a user-friendly format, which supports capital letters and spaces. Basically, your property will look exactly as you have written it. This is known as the property's label.
However, dues to technical requirements, when saving the property in our database, we have to transform it into a supported format: all lower-case and with underscores instead of spaces. This is known as the property name.
Whenever you want to manage properties via transactional integrations or our API, you will need to use a property's name, because the label will simply not work.
But it's very easy to figure out what is the name of a property. All you have to do is to make all the letters lowercase and replace spaces with underscores.
Below I will list a few examples so that it's easier to understand how this works:
Label: Subscription (name: subscription)
Label: Subscription Name (name: subscription_name)
Label: This Is A Custom Prop (name: this_is_a_custom_prop)
Assign a property to a customer
After you have identified the property name, all you have to do is to add it to the JSON text field in your Zendesk automation.
After that, every time when the automation will be triggered, the contact will be added as a new customer in your Retently account, and the properties from the JSON field will be assigned, along with the values from the specified Zendesk placeholders.
Update the value of an assigned customer property
The values in a property that is already assigned to a customer will be updated automatically the next time your automation will be triggered and the contacts will match the automation rules.
Unassign customer property
Every time an automated rule is triggered, the contact's properties will be updated with the new values that will be sent via the Retently webhook. However, if no value is available for a particular property, then the property will be unassigned from the customer's record in Retently.
Click here to learn about other trigger services that we’re supporting.