Launch Next Matter processes directly from Zendesk

Next Matter integrates seamlessly with Zendesk in two directions. In this integration tutorial, you can learn how to trigger a Next Matter process directly from the Zendesk agent interface by categorizing the ticket with a custom field and setting up a trigger based on that custom field. You will also receive a reply from Next Matter so that your agents have all context required.

Step 1: Zendesk: Set up a custom field for categorizing the ticket

The purpose of the field is to map your tickets to the right Next Matter process(es).

In Zendesk, navigate to Admin Center --> Objects and rules --> Fields --> Add Field --> Dropdown

Provide a name that you can recognize (e.g. "Trigger Next Matter Process") and add field values that correspond with the Next Matter processes that you want to trigger.

Example: If you want to manage master data change requests and GDPR compliance requests in Next Matter then you can add two fields like shown in the screenshot.

Hit save and note the custom field id for the field that you just created by clicking on the custom field once more.

Note for power users: It is possible to use existing fields / categories that you already have. Additionally, you can make this end user editable if you want to allow users to select categories that then trigger Next Matter processes immediately.

Step 2: Zendesk: Set up a custom field for the Next Matter instance ID

The purpose of the second custom field is to receive the ID to the Next Matter instance, so that your agents can track the request progress in Next Matter and so that Zendesk can update the ticket later if needed.

Add another custom field with the type text (navigate to Admin Center --> Objects and rules --> Fields --> Add Field --> Text)

The field can be called "Next Matter instance ID" or something else that you can recognize. The remaining settings can be left in the default state.

This is not required to make the integration work but is strongly recommended for added transparency.

Step 3: Add the fields to the right ticket forms

Your agents need to see the newly created fields, this can be achieved by adding it to the right forms.

Navigate to Admin Center --> Objects and rules --> Forms --> //Click on the right form

Drag and drop the newly created custom fields from the right-hand side to the form.

Note: If you have more than one form then you need to add it to all of them.

Step 4: Zendesk: Set up a Webhook to activate the integration with Next Matter

Zendesk needs to know how it can communicate with Next Matter. For that, you will configure a Webhook within Zendesk

Navigate to Admin Center --> Apps and Integrations --> Webhooks
click on Actions (top right) --> Create Webhook
Give a recognizable name for the Webhook. For example "Next Matter - Create Instance"
Fill the Endpoint URL field with the Next Matter endpoint
https://integrations.nextmatter.com/g/zendesk/createinstance/
Choose Request Method POST and Request format JSON
Tick the Check Box "Basic Authentication" and fill username and password (You can get an API-Key from Next Matter Support)
```
Username: Api-Key
Password: INSERT YOUR NEXT MATTER API KEY
```

The result will look like this

Step 5: Zendesk: Set up a trigger

Zendesk needs to be configured to send the right data at the right time to Next Matter. For that, you need to configure a Trigger within Zendesk. For each process that you want to start in Next Matter, you will need a separate Trigger.

Navigate to Admin Center --> Objects and rules --> Triggers
Choose a recognizable name for the trigger. We recommend basing the name on the type of process that you want to start in Next Matter. For example, if you start your "Customer Claim" process, you can name the trigger "Next Matter - new Customer Claim"
Choose a category for your Trigger. We recommend creating a "Next Matter" category for all your Next Matter related triggers.
Set up the conditions for your Trigger. This defines when Zendesk will contact Next Matter to start a new process. Common setup (see screenshot)
1. The custom field with the Next Matter categories is set to a certain value
2. The custom URL text field is not set yet, which avoids duplicate entries
Add action and choose "Notify webhook" in the dropdown. Select the previously configured Next Matter webhook in the second dropdown
Copy the following code into the "JSON body" section. Replace the processid placeholder with the id of the Next Matter process that you want to trigger. You can find that ID if you access your process inside Next Matter (see screenshot).

{
"ticket_id": "{{ticket.id}}",
"process_id": INSERT PROCESS ID HERE
}

Test: When configured correctly, a Next Matter process will be launched with the ticket id as the name of the process whenever you set the related category in the custom field and save it.

Step 6: Send information back to Zendesk from Next Matter with the URL

To make sure that your agents can see the launched Next Matter process, take the following steps to send back the instance ID.

In your target Next Matter process create a new Integration step as the first step in the process and click on "Settings" on the newly created step.

Choose Method PUT and as URL enter the API endpoint of Zendesk that you want to use. For example, to update a ticket you would use

https://{{your zendesk subdomain}}.zendesk.com/api/v2/tickets/{{instance_name}}

Add a header with Key "Content-Type" and Value "application/json". Add another header with Key "Authorization" and use this value

Bearer %%YOUR ZENDESK OAUTH TOKEN%%

Copy the following code into the body. Please replace the id placeholder with the Field ID of the Ticket field that you want to update in Zendesk. You can find that ID under Admin Center --> Objects and rules --> Fields in Zendesk (see previous steps)

{ 
"ticket": { 
   "custom_fields": [
       { "id": %%insert Field ID here%%", "value": %%insert value here%% }           
    ] 
  } 
}

FAQ

Is it possible to do more things with the ticket than updating the custom field?

Yes of course. You can find the full API documentation here linked here

Is it possible to call additional data from the ticket?

Yes of course, you can find more information on that topic here in our knowledge base: Create custom user variables that contain parsed responses of integration steps | Next Matter Help Center

One example: If you have configured a previous step to get ticket details from Zendesk, you can automatically take the ticket id from that step by using Next Matters "data-referencing" capability. You can also use this functionality to update the ticket with values that were stored in previous process steps.