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

1. In your app’s root folder, create a folder called integration, if it doesn’t already exist. Inside, create a subfolder called zendesk. Inside the subfolder, create a file called support.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

1. 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

2. 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

1. 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.

1. Log in to Zendesk Support. Click the gear icon to access the settings menu. Under Manage, select People. Click the Add user button.

2. Give the user a name such as Meya or Bot. 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.

3. Log out of Zendesk and login using the bot agent account before continuing the setup instructions.

Create an API token

1. Click the gear icon to access the settings menu. Under Channels, select API. Enable token access, then click the Add API Token button.

2. 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 target

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.

1. Click the gear icon to access the settings menu. Under Settings, select Extensions. Click the add target button.

2. Choose HTTP target from the list of options.

3. Make sure your settings look like this:

Title: Meya

Url: ZENDESK_SUPPORT_WEBHOOK (retrieved earlier in your terminal)

Method: POST

Content type: JSON

Basic Authentication: enabled

Username: meya

Password: A_PASSWORD

Here’s what it should look like when you’re done:

📘

Make a note of the password. You’ll need to enter it in your app’s vault later.

4. Make sure Test target is selected in the dropdown menu and click Submit. In the pop-up box, enter this code:

{
  "test": "abc"
}

Click Submit. You should get a 200 response code. Close the pop-up window.

5. From the dropdown menu, select Create target and click Submit.

Create the Zendesk trigger

Next, you’ll create a Zendesk trigger that notifies our webhook whenever a ticket is created or updated.

1. Click the gear icon to access the settings menu. Under Business Rules, select Triggers. Click the Add trigger button.

2. 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 target. In the second dropdown, choose the target 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.

1. 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.

2. 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.

1. In your app’s flow folder, create a subfolder called zendesk. Inside the subfolder, create a file called escalate.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

1. In the chat simulator, type escalate to trigger the new flow. If you don’t have values already stored at user.name and user.email, you’ll be asked to provide those. The bot should then provide you with a ticket ID.

2. 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.

3. 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.

1. 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

2. In the chat simulator, run the escalate.yaml flow to create a ticket in Zendesk.

3. 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”.

1. 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.

1. 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.

1. 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.

2. 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