Integrate with Zendesk

These integrations can be used in several scenarios. For example, you can start a Next Matter workflow when a Zendesk ticket is created, or at any point in your workflow, you might push data from Zendesk into Next Matter form fields. It might also happen, that you need to follow up with a customer using Zendesk, and whenever the customer responds, this data is pushed into a Next Matter step, and this step gets completed.

🚧

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. Interested? Contact our Customer support team.

Before you begin

• Understand how data references work. See Use data references. This will help you use the captured data in the workflow steps.

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

Start a Next Matter 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.

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

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

4. Save your changes.
5. Click Add Field again and select Text as the text type.
6. 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.

{ 
"ticket": { 
   "custom_fields": [
       { "id": ZENDESK_CUSTOM_FIELD_ID, "value": "{Instance URL}"
 }   //the instance URL is a data reference; to get the custom field ID, go to Zendesk  Admin > Manage/Ticket Fields > edit. The ID will be listed at the top of the Ticket Field Edit page.       
    ] 
  } 
}

Add the field to the ticket form

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

Set up a webhook

The webhook will activate the integration with Next Matter.

1. Navigate to Admin Center > Apps and Integrations > Webhooks.
2. Click Actions > Create Webhook.
3. Give the webhook a meaningful name.
4. In the Endpoint URL, enter the endpoint created for the Webhook trigger.
5. 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.

1. Navigate to Admin Center > Objects and rules > Triggers.
2. 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.
3. Choose a Zendesk category for your trigger. We recommend creating a "Next Matter" category for all your Next Matter-related triggers.
4. 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.

5. Add action and choose Notify webhook in the dropdown. Select the previously configured Next Matter webhook in the second dropdown.
6. 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

1. 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.
2. Copy the form field ID and store it for later.

Set up a webhook to complete step

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

Set up a trigger

1. Go to Admin Center > Objects and rules > Triggers.

2. Choose a Zendesk category for your trigger. We recommend creating a “Next Matter” category for all your Next Matter-related triggers.

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

   

4. Select the following in Actions:Notify by > Active Webhook (left-hand field) and Next Matter Complete Step (right-hand field).

5. Enter the following in the JSON body:

{
"nm_instance_id" : "{{ticket.ticket_field_FIELDID}}",//the FIELDID is the instance form field ID from Next Matter
"complete_step_data": {  
		"step_id": STEP_ID,  
		"actions": [{  
			"action_id": FORM_FIELD_ID,// this is the ID of the form field in Next Matter to which should be filled in with Zendesk data
			"input_object": {  
				"inputValue": "{{ticket.latest_public_comment_html}}"  
			}  
		}]  
	}  
}

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.

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.