Zendesk Help Center

Find and display articles from Zendesk Help Center

With Zendesk Help Center (also known as Zendesk Guide) you can build an integrated help center and community forum. Customers can resolve issues at their own pace — while reducing resolution times for agents.

With the Zendesk Help Center integration, you can:

  • retrieve a specific article by its ID
  • search for articles using search terms
  • trigger a flow when an article is found
  • filter results by category, section, labels, and more
  • sort articles by relevance or recency so your users are getting the best info first

Keep reading to learn how to set up the integration.

📘

If you've already added the Zendesk Support integration, you'll already have the credentials in your vault. In that case, you can skip ahead to the Add the integration step.

If you haven't added the Zendesk Support integration, keep reading.

Create a bot agent

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

🚧

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.

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

Update the vault

We now have all of the information we need to update our vault secrets and complete the integration.

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

Save the file and upload the new secrets to your vault:

meya vault upload --file vault.secret.yaml

Add the integration

With our secrets safely stored in the vault, it's time to create the integration.

In your app's integration folder, create a subfolder called zendesk. Inside, create a file called help_center.yaml and copy this code into it:

type: meya.zendesk.help_center.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 )

Add flows

We're almost there! Let's add a few flows to test out the integration's features.

In your app's flow folder, created a subfolder called zendesk and subfolder within there called help_center. Inside the help_center folder, you'll create four files. The file names and their code are shown in the code box below. Copy the code into the files.

triggers:
  - keyword: zendesk_help_center_get

steps:
  - ask: What's the article id?
  - type: meya.zendesk.help_center.component.article.get
    article_id: (@ flow.result | int)
    integration: integration.zendesk.help_center

  - type: meya.zendesk.help_center.component.display
    search_response: (@ flow.get("result") )

  - ask: Articles
    button_style: text
    tiles: (@ flow.result)
triggers:
  - keyword: zendesk_help_center_search

steps:
  - (ask search term)
  - ask: What would you like to search for? (e.g. Help)
  - flow_set: search_query

  - (search)
  - type: meya.zendesk.help_center.component.search
    query: (@ flow.search_query )
    per_page: 2
    page: (@ flow.get('page', 1))
    integration: integration.zendesk.help_center
  - flow_set: search_result

  - type: meya.zendesk.help_center.component.display
    search_response: (@ flow.get("result") )

  - if: (@ flow.result )
    then: next
    else:
      jump: not found

  - ask: Articles
    button_style: text
    tiles: (@ flow.result)

  - if: (@ flow.search_result.next_page )
    then:
      jump: see more
    else: next
  - end

  - (see more)
  - flow_set:
      page: (@ flow.get('page', 1) + 1)

  - say:
    quick_replies:
      - text: Show me more
        action:
          jump: search
      - text: Try again
        action:
          jump: ask search term
  - end

  - (not found)
  - say: Sorry, I couldn't find anything for '(@ flow.search_query)'
    quick_replies:
      - text: Try again
        action:
          jump: ask search term
triggers:
  - expect: zendesk_help_center
    integration: integration.zendesk.help_center

steps:
  - type: meya.zendesk.help_center.component.display
    search_response: (@ flow.zendesk_help_desk_response)

  - ask: Hey! Check the articles I found
    button_style: text
    tiles: (@ flow.result)
triggers:
  - expect: dialogflow
    integration: integration.google.dialogflow.dialogflow
    language: en
    intent: price_calculator
    action:
      jump: dialogflow

  - expect: wit
    integration: integration.facebook.wit
    intent: documentation

steps:
  - type: component.facebook.wit.parse_entities
    entities: (@ flow.wit_response.entities)
  - flow_set:
      query_term: (@ flow.get('entities', [{}])[0].get('value', 'help') | string)

  - jump: search article

  - (dialogflow)
  - flow_set:
      query_term: (@ flow.result)

  - (search article)
  - type: meya.zendesk.help_center.component.search
    query: (@ flow.query_term)
    integration: integration.zendesk.help_center

  - type: meya.zendesk.help_center.component.display
    search_response: (@ flow.get("result") )
  - if: (@ flow.result)
    then: next
    else:
      jump: not found

  - ask: Look what I found for '(@ flow.query_term)'
    button_style: text
    tiles: (@ flow.result)
  - end

  - (not found)
  - say: >
      Sorry didn't find any article for '(@ flow.query_term)', please try to refine
      your question
  - endtriggers:
  - keyword: zendesk_help_center_search

steps:
  - (ask search term)
  - ask: What would you like to search for? (e.g. Help)
  - flow_set: search_query

  - (search)
  - type: meya.zendesk.help_center.component.search
    query: (@ flow.search_query )
    per_page: 2
    page: (@ flow.get('page', 1))
    integration: integration.zendesk.help_center
  - flow_set: search_result

  - type: meya.zendesk.help_center.component.display
    search_response: (@ flow.get("result") )

  - if: (@ flow.result )
    then: next
    else:
      jump: not found

  - ask: Articles
    button_style: text
    tiles: (@ flow.result)

  - if: (@ flow.search_result.next_page )
    then:
      jump: see more
    else: next
  - end

  - (see more)
  - flow_set:
      page: (@ flow.get('page', 1) + 1)

  - say:
    quick_replies:
      - text: Show me more
        action:
          jump: search
      - text: Try again
        action:
          jump: ask search term
  - end

  - (not found)
  - say: Sorry, I couldn't find anything for '(@ flow.search_query)'
    quick_replies:
      - text: Try again
        action:
          jump: ask search term

get_component.yaml demonstrates how to retrieve a specific article using its article ID.

search_component.yaml shows how to search your help center articles for a specific term. Multiple articles might be returned.

trigger.yaml provides an example of a trigger that will search your help center using the user's input and store the resulting article at flow.result.

nlu.yaml demonstrates how you can combine Zendesk Help Center with a natural language understanding service, like Dialogflow or Wit. After parsing the user's input for their intent, the intent is used to perform a search of the articles in your help center.

Save the files and push them to the Grid by running these commands in your terminal:

meya push

Test it out

In your app's simulator, enter zendesk_help_center_get to trigger the get_component.yaml flow. Submit an article ID from your Help Center and check out the result!

👍

Great! You've set up the Zendesk Help Center integration.

Suggested reading

📘

Did you know you can filter and sort the results returned by Zendesk Help Center? Learn more about the Zendesk Help Center integration with these resources: