Setup
How to set up a Zendesk Support integration
Learn how to set up a Zendesk Support integration, then increase agent productivity using the strategies in the Advanced Usage section.
Before you begin
This guide assumes you already have a your local environment set up for development on the Meya platform and that you’re connected to a test app you can experiment with.
If you’re using a virtual environment, make sure it’s activated.
If you haven’t setup your local environment yet, check out Getting started with local Meya development.
You’ll need to have the Administrator role in Zendesk Support to complete some of the steps.
Setup guide
Create the integration
- In your app’s root folder, create a folder called
integration
, if it doesn’t already exist. Inside, create a subfolder calledzendesk
. Inside the subfolder, create a file calledsupport.yaml
and enter this code:
type: meya.zendesk.support.integration
subdomain: (@ vault.zendesk.support.subdomain )
bot_agent_email: (@ vault.zendesk.support.bot_agent_email )
bot_agent_api_token: (@ vault.zendesk.support.bot_agent_api_token )
target_password: (@ vault.zendesk.support.target_password )
Go ahead and save the file, but don’t push the code yet.
Add the integration secrets
- Open
vault.yaml
and add the following lines:
zendesk.support.subdomain: zendesk_domain_name
zendesk.support.bot_agent_email: [email protected]
zendesk.support.bot_agent_api_token: xxx
zendesk.support.target_password: xxx
- Open
vault.secret.yaml
and add the same code:
zendesk.support.subdomain: zendesk_domain_name
zendesk.support.bot_agent_email: [email protected]
zendesk.support.bot_agent_api_token: xxx
zendesk.support.target_password: xxx
We’ll update this with the real information in a future step, but we need this here now in order to generate the integration webhook.
Save the file and upload the new secrets to your vault:
meya vault upload --file vault.secret.yaml
Retrieve the integration webhook
- Run this command in your terminal:
meya webhooks
Make a note of the Zendesk Support webhook. It’ll look something like this:

Create a bot agent
You’ll need to create a user in Zendesk Support that will represent your Meya app. Let’s do that now.
It’s important that you create a new user account specifically for the app. Sharing this user account with a human agent will result in unexpected behaviour.
- Log in to Zendesk Support. Click the gear icon to access the settings menu. Under Manage, select People. Click the Add user button.

- Give the user a name such as
Meya
orBot
. Enter an email address for the user.
If you don’t have an email account specifically for the bot user, you can use this method:
[email protected]_DOMAIN.com
For example, if your regular email address is
[email protected]
, you can set your bot’s email address to[email protected]
. Email address to this address will go to your regular inbox.
Click Add to finish creating the bot user.
- Log out of Zendesk and login using the bot agent account before continuing the setup instructions.
Create an API token
- Click the gear icon to access the settings menu. Under Channels, select API. Enable token access, then click the Add API Token button.

- Give your token a useful description, such as the name of your Meya app.
Copy the token somewhere before saving. You’ll need the token later and it won’t be possible to view it after saving the token.
Click Save.
Create a webhook
When migrating from target to webhook make sure to delete old targets before continuing with the configuration
Next, you’ll add your app’s Zendesk Support webhook to your Zendesk instance so Zendesk can send your app events. Later, we’ll create flows that respond to these ticket lifecycle events.
- Go to Admin Center and under Apps and Integrations select Webhooks then click Actions and Create Webhook.


- Fill the webhook data
- Endpoint URL: Integration webhook
- Request method: POST
- Request format: JSON
- Authentication: Basic Authentication
- Username: meya
- Password: choose

Make a note of the password. You’ll need to enter it in your app’s vault later.
- Make sure to Test webhook before creating.
Change Request JSON Body
{
"test": "abc"
}
Click Send test. You should get a 200
response code.

Create the webhook
Create the Zendesk trigger
Next, you’ll create a Zendesk trigger that notifies our webhook whenever a ticket is created or updated.
- Click the gear icon to access the settings menu. Under Business Rules, select Triggers. Click the Add trigger button.

- Give the trigger a descriptive name, like
Notify Meya
.
In the Conditions section, under Meet ANY of the following conditions, click the Add condition button. Select Ticket from the first dropdown and Created from the last dropdown.
Click the Add condition button to add a second condition. Select Ticket from the first dropdown and Updated from the last dropdown.
Under the Actions section, click Add action. From the dropdown, choose Notify active webhook. In the second dropdown, choose the webhook you created earlier. In the JSON body field, enter this code:
{
"ticket_id": "{{ticket.id}}",
"updated_at": "{{ticket.updated_at_with_timestamp}}",
"current_user_id": "{{current_user.id}}"
}
The form should look like this when you’re done:

Click Create to save the trigger.
Update the integration secrets
We now have all of the information we need to update our vault secrets and complete the integration.
-
In your code editor, open
vault.secret.yaml
. Update the Zendesk Support secrets with your Zendesk Support subdomain, the bot agent’s email address, the bot agent’s Zendesk API token, and the Zendesk target’s password. -
Save the file and upload the new secrets:
meya vault upload --file vault.secret.yaml
Create a flow
Let’s create a flow that will create a ticket in Zendesk Support.
- In your app’s
flow
folder, create a subfolder calledzendesk
. Inside the subfolder, create a file calledescalate.yaml
. Copy this code into the file:
triggers:
- keyword: escalate
steps:
- (check_name)
- if: (@ user.name )
then:
jump: check_email
else: next
- ask: What is your name?
- user_set:
name: (@ flow.result )
- (check_email)
- if: (@ user.name )
then:
jump: create
else: next
- ask: What is your email?
- user_set:
email: (@ flow.result)
- (create)
- type: meya.zendesk.support.component.user.create_or_update
integration: integration.zendesk.support
name: (@ user.first_name )
email: (@ user.email )
- type: meya.zendesk.support.component.ticket.create
integration: integration.zendesk.support
requester_id: (@ flow.result.id )
subject: This is a test subject
- say: 'Ticket #(@ flow.result.id ) created. An agent will be here shortly...'
This flow will be triggered with the keyword escalate
. In production you’ll want to find a more user-friendly way of launching this flow, such as a button or natural language.
Next, we collect some info from the user. While not required, we collect this info so we can pass it on to Zendesk.
For a complete list of user data you can send to Zendesk, take a look at our documentation for the zendesk.support.user.create_or_update component.
The create_or_update component returns an object representing the Zendesk user. In the next step, we create the Zendesk ticket and use the user’s Zendesk ID in the requester_id field.
The ticket.create component returns an object representing the Zendesk ticket. In the final step, we use this object to print the ticket ID.
Save the file and upload it:
meya format
meya push
Test the integration
- In the chat simulator, type
escalate
to trigger the new flow. If you don’t have values already stored atuser.name
anduser.email
, you’ll be asked to provide those. The bot should then provide you with a ticket ID.

- Log in to Zendesk Support as a human agent (do not use the bot agent’s account). Open Zendesk Support and confirm the ticket has been created.

- Enter a public reply, submit the ticket, and return to the chat simulator. Confirm that the agent’s message appears in the chat.

The Zendesk Support integration is now setup! Check out the Advanced Usage section below for next steps.
Troubleshooting
Zendesk user
Did you create a separate Zendesk user for the Meya app? The Meya app cannot share an account with a human agent as this can cause unexpected behaviour.
API token
When generating the Zendesk API token were you logged into the bot agent account? The API token is associated with the user that created it, so if you didn’t create the token as the bot agent, do that now, and update your vault secrets.
Upload vault secrets
Saving new data in vault.secret.yaml
doesn’t update your remote vault. Remember to run this command whenever you update the vault:
meya vault upload --file vault.secret.yaml
Check the logs
From the app’s Logs page, do a search for url:*zendesk*
. This will return all incoming and outgoing calls to Zendesk. Check the payloads for error messages.
Target failures
In Zendesk, click the gear icon. Under Channels, select API, then select the Target Failures tab. If you see any entries here, you likely made an error when setting up the target. Update the target settings, test the target within Zendesk, save the updates, and test the bot again.
Zendesk will deactivate targets that have too many failures. It’s a good idea to use an external service to monitor your Meya webhook to make sure it continues to exist, is valid, and active. See Monitor and reactivate Zendesk Support webhooks for more information.
Advanced usage
Agent commands
Did you know your agents can send commands to your Meya app and have it launch flows? Here’s how.
- Create a new flow called
say_hi.yaml
that uses the agent_command trigger:
triggers:
- agent_command: say_hi
steps:
- say: The agent says hi :)
Save the file and upload it:
meya format
meya push
-
In the chat simulator, run the
escalate.yaml
flow to create a ticket in Zendesk. -
In Zendesk, open the ticket, make sure you have Internal note selected, and enter this text:
/say_hi
Submit the ticket. Back in the chat simulator you should see the text from the say_hi flow.

Consider using agent commands for tasks like collecting additional information from users.
Detect ticket updates
You can use the meya.zendesk.support.trigger.ticket.update
trigger to detect ticket updates. One way to use this feature is to offer “signposts”, like “Ticket was assigned”.
- Create a new flow called
ticket_update.yaml
. Copy this code into the file:
triggers:
- type: meya.zendesk.support.trigger.ticket.update
bot: bot.notification
steps:
- (check_status)
- if: (@ flow.ticket.status != flow.old_ticket.status )
then: next
else:
jump: check_assignee
- status: Ticket (@ flow.ticket.id) is now (@ flow.ticket.status )
- (check_assignee)
- if: (@ flow.ticket.assignee_id != flow.old_ticket.assignee_id )
then: next
else:
jump: solved
- if: (@ not flow.ticket.assignee_id )
then:
jump: no_assignee
else: next
- type: meya.zendesk.support.component.user.show
integration: integration.zendesk.support
user_id: (@ flow.ticket.assignee_id )
- status: >
Ticket (@ flow.ticket.id) is now assigned to
(@ flow.result.alias or flow.result.name )
- jump: solved
- (no_assignee)
- status: Ticket (@ flow.ticket.id) status is now unassigned
- jump: solved
- (solved)
- if: (@ flow.ticket.status != flow.old_ticket.status and flow.ticket.status ==
"solved" )
then:
lifecycle: flow.zendesk.support.webhook.ticket_solved
else: end
Reading through the code, you’ll see that it alerts the user to a change in ticket status, and ticket assignee.
When the ticket is solved, the flow emits the flow.zendesk.support.webhook.ticket_solved
lifecycle event. See Ticket resolution survey below for an example of how you can use this webhook event.
Save the file and upload it:
meya format
meya push
To test it out, create a ticket using the escalate.yaml
flow, then change the ticket status in Zendesk Support. The ticket_update.yaml
flow should run.
Ticket resolution survey
It’s a good idea to have the user confirm that their issue has been resolved. You can take advantage of Zendesk Support webhook events to do this.
- Create a new flow called
ticket_solved.yaml
. Copy this code into the file:
triggers:
- lifecycle_id: flow.zendesk.support.webhook.ticket_solved
steps:
- thread_set:
mode: bot
- ask: Did we solve your problem?
quick_replies:
- Yes
- No
- if: (@ flow.result == "Yes" )
then: next
else:
jump: reopen
- type: meya.zendesk.support.component.ticket.update
integration: integration.zendesk.support
status: closed
- say: Glad to help!
- end
- (reopen)
- thread_set:
mode: agent
- type: meya.zendesk.support.component.ticket.update
integration: integration.zendesk.support
status: open
- say: Sorry, to hear that 😢
The lifecycle trigger lets you listen for the ticket_solved webhook event.
Save the file and upload it:
meya format
meya push
To test it out, create a ticket using the escalate.yaml
flow, then resolve the ticket in Zendesk Support. The ticket_solved.yaml
flow should run.
Custom fields
If you have custom ticket fields in Zendesk Support, you can have your Meya app populate them.
- In Zendesk Support, click the gear icon to open the settings menu. Under Manage, select Ticket Fields. Make a note of the Field ID for the fields you want to populate from the Meya app.

- Update the
escalate.yaml
flow so it looks like this:
triggers:
- keyword: escalate
steps:
- (check_name)
- if: (@ user.name )
then:
jump: check_email
else: next
- ask: What is your name?
- user_set:
name: (@ flow.result )
- (check_email)
- if: (@ user.name )
then:
jump: create
else: next
- ask: What is your email?
- user_set:
email: (@ flow.result)
- (create)
- type: meya.zendesk.support.component.user.create_or_update
integration: integration.zendesk.support
name: (@ user.first_name )
email: (@ user.email )
- type: meya.zendesk.support.component.ticket.create
integration: integration.zendesk.support
requester_id: (@ flow.result.id )
subject: This is a test subject
custom_fields:
- id: FIELD_ID_1
value: 123
- id: FIELD_ID_2
value: foo
- id: FIELD_ID_3
value: (@ user.some_value )
- say: 'Ticket #(@ flow.result.id ) created. An agent will be here shortly...'
Replace FIELD_ID_X
with the IDs of the fields you want to populate. Note that the custom_fields
property is a YAML list.
Make sure the value field is properly indented or it won’t work.
Save the file, then upload it:
meya format
meya push
IP Restrictions
If you have enabled IP restrictions in the Zendesk Admin center, then you will need to add the Meya platform's Meya Source IP to your list of Allowed IP ranges.
Updated 4 months ago