Integrate with Zendesk

You can use Next Matter as a Zendesk sidebar widget! That’s a quick way to start workflows, link chats and tickets, and get your tasks done.

Before you begin

You need your Zendesk API Key. For details on how to generate it, see Zendesk documentation.
In your Next Matter portal, go to Company > Integrations, and click Connect next to Zendesk. Enter the subdomain to connect to Zendesk using OAuth. For example, if your domain is: https://d3v-nextmatter.zendesk.com/agent/dashboard, then d3v-nextmatter is the subdomain to enter.
For some tasks, you might need a Zendesk ticket ID. The ticket ID is the number at the end of the URL that shows when you click the ticket.

Image of the ZEndesk ticket ID in the URL

Check the required scopes to learn more about which data is shared between the apps.

I want to start workflow instance from Zendesk and send data to step

Prepare your Next Matter workflow

Make sure that the first step in the workflow contains a form field to receive the Zendesk ticket ID.
Make sure that you have auto-naming enabled for the workflow. The name of the instance should be a data reference to the Zendesk ticket ID. You can enable auto-naming in the Trigger step configuration.
Select Webhook trigger in the Trigger step configuration. Enable the webhook and copy the webhook URL. You’ll need it later on.

Set up a custom field for categorizing the ticket and the Next Matter instance ID

The purpose of the custom field is to provide an ID of the Next Matter instance so that Zendesk can update the workflow instance automatically.

In Zendesk go to Admin Center > Objects and rules > Fields.
Click Add Field and select Dropdown as the text type.

Image of the Add field screen in Zendesk

Create one or more fields for agents to choose from.
You can use fields/categories that you already have. Additionally, you can make the fields end-user editable if you want to allow users to select categories that then trigger Next Matter workflows.
Save your changes.
Click Add Field again and select Text as the text type.
Give the field a meaningful name.

Your agents can either manually fill the workflow ID in each ticket but it’s easier if you send the instance ID from the Next Matter workflow to Zendesk with an integration step.This is how to send instance details to Zendesk

In your Next Matter workflow, create an integration step.
Click Settings and enter the following details:

URL: https://YOUR_ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/{Instance Name} with Instance Name being the data reference
Method: PATCH
Headers: Content-Type: application/json
Headers: Authorization: ZENDESK_API_KEY

In Body, enter the following:

{ 
"ticket": { 
   "custom_fields": [
       { "id": ZENDESK_CUSTOM_FIELD_ID, "value": "{Instance URL}" }      
    ] 
  } 
}

Add the field to the ticket form

Go to Admin Center > Objects and rules > Forms.
Click on the form you’ll use to start the workflow.
Drag and drop the newly created custom field from the right-hand side section to the form.

Image of the forms page under Objects and rules in Zendesk

Set up a webhook

The webhook will activate the integration with Next Matter.

In Zendesk, navigate to Admin Center > Apps and Integrations > Webhooks.
Click Actions > Create Webhook.
Give the webhook a meaningful name.
In the Endpoint URL, enter the endpoint created for the Webhook trigger.
Select POST as the call method and JSON as the response format.

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 workflow you want to communicate with, you will need a separate trigger.

In Zendesk, navigate to Admin Center > Objects and rules > Triggers.
Enter a recognizable name for the trigger. We recommend basing the name on the type of update that you want to do in Next Matter.
Choose a Zendesk 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 contacts Next Matter. The trigger can be based on different events happening in your tickets. Note that there must be one condition to check if the Next Matter Instance ID field that you created before is not empty.
Add action and choose Notify webhook in the dropdown. Select the previously configured Next Matter webhook in the second dropdown.

The contents of the JSON body can contain whatever information you need to transfer from Zendesk. For example, the section might look like the following:

{
"id":"{{ticket.id}}",
"description":"{{ticket.description}}",
"subject":"{{ticket.subject}}",
"type":"{{ticket.type}}",
"comment": "{{ticket.latest_comment_html}}"
}

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

Send data from Zendesk and complete a step

Set up an instance field in the Next Matter form

In the workflow, you’re building in the form to receive Zendesk input, create a form field (short input) that will be filled in with the Next Matter instance ID.
Copy the form field ID and store it for later.

Set up a webhook to complete step

Navigate to Admin Center > Apps and Integrations > Webhooks.
Click Actions > Create Webhook.
Call the webhook: Next Matter Complete Step.
In the Endpoint URL, enter https://integrations.nextmatter.com/g/zendesk/completestep
Select POST as the call method and JSON as the format.
Select the API key and enter the following details: Header name: Authorization Value: Api-key YOUR_NEXTMATTER_API_KEY

Set up a trigger

In Zendesk, go to Admin Center > Objects and rules > Triggers.
Choose a Zendesk category for your trigger. We recommend creating a “Next Matter” category for all your Next Matter-related triggers.
Set the conditions for Ticket & Current user. You can set other conditions that are relevant for the event you need. In the example provided, we’re getting customer answers to Next Matter.

Select the following in Actions: Notify by > Active Webhook (left-hand field) and Next Matter Complete Step (right-hand field).
Get the following the step ID and the form field ID and enter the JSON body
Where is the step ID?
1. In your left-hand navigation, click the Workflows icon.
2. Hover over the follow-up workflow and click on the menu icon.
3. Click Edit workflow.
4. Click the step to which you’d like to send data.
5. Copy the step ID. It’s the last number in the URL you see in your browser.
Where is the form field ID?
1. In your left-hand navigation, click the Workflows icon.
2. Hover over the follow-up process and click on the menu icon.
3. Click Edit workflow.
4. Click the step to which you’d like to send data.
5. Click the ID icon for the field to which you want to copy data.
6. Copy Form field ID.

{
"nm_instance_id": "{{ticket.ticket_field_FIELDID}}",
"complete_step_data": {  
		"step_id": STEP_ID,  
		"actions": [{  
			"action_id": FORM_FIELD_ID,
			"input_object": {  
				"inputValue": "{{ticket.latest_public_comment_html}}"  
			}  
		}]  
	}  
}

I want to create or update a ticket code-free

I want to use advanced integration: get ticket details, search for a ticket, upload a file to ticket

Get ticket details

You need to write the instance URL in the ticket to transfer the data to the instance automatically. To do so:
1. In your Next Matter workflow, create an integration step.
2. Click Settings and enter the following details:
  - URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/{Instance name} with Instance ID being the data reference
  - Method: PATCH
  - Headers: Content-Type: application/json
  - Headers: Authorization: ZENDESK_API_KEY
  - Body:
    { "ticket": { "custom_fields": [ { "id": 360020270077, "value": "{Instance URL}" } ]} }
Now you can create the next integration steps to pull data.
Get a set of ticket data
1. In your Next Matter workflow, create an integration step.
2. Click Settings and enter the following details:
  - URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/{Instance name} with Instance ID being the data reference
  - Method: GET
  - Headers: Content-Type: application/json
  - Headers: Authorization: ZENDESK_API_KEY
  - Leave Body empty.
  - Create the following variables and save your changes.
    - $.ticket.via.source.from.name (for requester name)
    - $.ticket.via.source.from.address (requester’s address)
    - $.ticket.description
    - $.ticket.id
    - $.ticket.comments
    - $.ticket.requester_id (requester’s id)
    - $.user.email (requester’s email)
You can use these variables to update the ticket with values that were stored in previous workflow steps.

Get comments with images

To do this, you can place a GET call to https://ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/{Instance name}with the following body:

{
"include_inline_images": true
}

and the following variable: $.comments.html_body

Search for a ticket

Click the Settings gear icon to configure your integration step.
In your integration step, you need to authenticate with your Zendesk API key and configure the API Method and URL. Use the following data replacing the placeholder with your own data.
- Method: GET
- URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/search.json?query=type:ticket%20subject:“WORD_TO_SEARCH_BY”
Save your changes.

Upload a file and attach it to ticket

To upload a file and attach it to a Zendesk ticket, upload the file first and then attach it to the ticket.

To upload the file, create a custom integration step with the following integration details:
- Method: POST
- Headers: Content-Type: FILE_TYPE i.e text/plain
- Headers: Authorization: ZENDESK_API_KEY
- URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/uploads/?filename=FILENAME Note that the FILENAME is a placeholder that needs to be replaced by the name of the file you want to upload. If you’re uploading multiple files, this needs to be the name of the first file, you want to upload.
- Ensure the Body type is Form data and has the following details:
```
Key: data-binary
Type: file
Value: FILE_REFERENCE
```
- Create the following variables:
  - an upload variable with the value of $.upload
  - a token variable with the value of $.upload.token
  - a Zendesk file URL variable with the value of $.upload.attachment.content_url
Create another custom integration step to attach the file to the ticket. Use the following details:

Method: PUT
Headers: Content-Type: application/json
Headers: Authorization: ZENDESK_API_KEY
URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/TICKET_ID/ Note that the FILENAME is a placeholder that needs to be replaced by the name of the file you want to upload

Ensure the Body type is Raw and has the following details:

{
    "ticket": {
        "comment": {
            "body": "MESSAGE_CONTENT",
            "uploads": [
                "{1. Upload File - Integration step - token (plain)}"
            ]
        }
    }
}

Pull data from Zendesk into an instance

In your Next Matter workflow create a new integration step.
To update a ticket, use the following:

Method: PUT
Headers: Content-Type: application/json
Headers: Authorization: ZENDESK_API_KEY
URL: https://ZENDESK_DOMAIN.zendesk.com/api/v2/tickets/{{instance_name}}

Overview

API

No-code

Custom integrations

Before you begin

Prepare your Next Matter workflow

Set up a custom field for categorizing the ticket and the Next Matter instance ID

Add the field to the ticket form

Set up a webhook

Set up a trigger

Send data from Zendesk and complete a step

Set up an instance field in the Next Matter form

Set up a webhook to complete step

Set up a trigger

Get ticket details

Get comments with images

Search for a ticket

Upload a file and attach it to ticket

Pull data from Zendesk into an instance

Overview

API

No-code

Custom integrations

​Before you begin

Before you begin