Zendesk Guide is a smart knowledge base that helps customers harness the power of institutional knowledge. It enables users to build a customizable help center and customer portal.

This post shows how to implement a bidirectional event orchestration pattern between AWS services and an Amazon EventBridge third-party integration partner. This example uses support ticket events to build a customer self-service knowledge repository. It uses the EventBridge partner integration with Zendesk to accelerate the growth of a customer help center.

The examples in this post are part of a serverless application called FreshTracks. This is built in Vue.js and demonstrates SaaS integrations with Amazon EventBridge. To test this example, ask a question on the Fresh Tracks application.

The backend components for this EventBridge integration with Zendesk have been extracted into a separate example application in this GitHub repo.

How the application works

1. A user searches the knowledge repository via a widget embedded in the web application.


2. If there is no answer, the user submits the question via the web widget.


3. Zendesk receives the question as a support ticket.


4. Zendesk emits events when the support ticket is resolved.


5. These events are streamed into a custom SaaS event bus in EventBridge.


6. Event rules match events and send them downstream to an AWS Step Functions Express Workflow.


7. The Express Workflow orchestrates Lambda functions to retrieve additional information about the event with the Zendesk API.


8. A Lambda function uses the Zendesk API to publish a new help article from the support ticket data.


9. The new article is searchable on the website widget for other users to read.

Before deploying this application, you must generate an API key from within Zendesk.

Creating the Zendesk API resource

Use an API to execute events on your Zendesk account from AWS. Follow these steps to generate a Zendesk API token. This is used by the application to authenticate Zendesk API calls.

To generate an API token

1. Log in to the Zendesk dashboard.


2. Click the Admin icon in the sidebar, then select Channels > API.


3. Click the Settings tab, and make sure that Token Access is enabled.


4. Click the + button to the right of Active API Tokens.
   
   
   
   
   

   Creating a Zendesk API token.

   
   


5. Copy the token, and store it securely. Once you close this window, the full token is not displayed again.


6. Click Save to return to the API page, which shows a truncated version of the token.
   
   
   
   
   

   Zendesk API token.

   
   

Configuring Zendesk with Amazon EventBridge

Step 1. Configuring your Zendesk event source.

1. Go to your Zendesk Admin Center and select Admin Center > Integrations.


2. Choose Connect in events Connector for Amazon EventBridge to open the page to configure your Zendesk event source.
   
   
   
   
   

   Zendesk integrations

   
   


3. Enter your AWS account ID in the Amazon Web Services account ID field, and select the Region to receive events.


4. Choose Save.
   
   
   
   
   

   Zendesk Amazon EventBridge configuration.

   
   

Step 2. Associate the Zendesk event source with a new event bus: 

1. Log into the AWS Management Console and navigate to services > Amazon EventBridge > Partner event sources
   
   
   
   

   New event source

   
   

    



2. Select the radio button next to the new event source and choose Associate with event bus.
   
   
   
   

   Associating event source with event bus.

   
   

    



3. Choose Associate.

Deploying the backend application

After associating the Event source with a new partner event bus, you can deploy backend services to receive events.

To set up the example application, visit the GitHub repo and follow the instructions in the README.md file.

When deploying the application stack, make sure to provide the custom event bus name, and Zendesk API credentials with --parameter-overrides.

sam deploy --parameter-overrides ZendeskEventBusName=aws.partner/zendesk.com/123456789/default ZenDeskDomain=MydendeskDomain ZenDeskPassword=myAPITOken ZenDeskUsername=myZendeskAgentUsername

You can find the name of the new Zendesk custom event bus in the custom event bus section of the EventBridge console.

Routing events with rules

When a support ticket is updated in Zendesk, a number of individual events are streamed to EventBridge, these include an event for each of:

• Agent Assignment Changed


• Comment Created


• Status Changed


• Brand Changed


• Subject Changed

An EventBridge rule is used filter for events. The AWS Serverless Application Model (SAM) template defines the rule with the `AWS::Events::Rule` resource type. This routes the event downstream to an AWS Step Functions Express Workflow.  The EventPattern is shown below:

  ZendeskNewWebQueryClosed: 
    Type: AWS::Events::Rule
    Properties: 
      Description: "New Web Query"
      EventBusName: 
         Ref: ZendeskEventBusName
      EventPattern: 
        account:
        - !Sub '${AWS::AccountId}'
        detail-type: 
        - "Support Ticket: Comment Created"
        detail:
          ticket_event:
            ticket:
              status: 
              - solved
              tags:
              - web_widget
              tags: 
              - guide
      Targets: 
        - RoleArn: !GetAtt [ MyStatesExecutionRole, Arn ]