Zendesk Component

Manage Tickets and users in Zendesk

Component key: zendesk

Description#

Zendesk is a public company headquartered in San Francisco, California. It provides software-as-a-service products related to customer support, sales, and other customer communications. The Zendesk component allows you to manage Users and Tickets inside your Zendesk domain.

Zendesk webhooks#

The Zendesk API supports two types of webhooks - one for when something has changed for a user or an organization, and one when something has changed on a support ticket.

Zendesk user and support webhooks#

If you would like to be alerted when a change to a user or organization has occurred, create a new webhook using the Create Webhook action. Select the events that will cause a the webhook to fire. For example, selecting the zen:event-type:user.deleted event will cause the webhook to fire whenever a user is deleted. A full list of webhook event types are available in the Zendesk developer docs.

Zendesk ticket webhooks#

If you would like to be alerted when a ticket has changed, first create a webhook using the Create Webhook action. When selecting webhook events, choose conditional_ticket_events (and only that value). This will create a webhook, pointed at a Prismatic instance flow, that can be triggered conditionally.

Next, you need to create a trigger that will send data via the webhook you created. Fetch your webhook's id from the step where you created the webhook, and feed it into a Create Trigger action. The default conditional and webhook body values will cause the webhook to be triggered whenever a ticket is changed, and will send all data related to the ticket to the webhook. We recommend keeping the default values. You can change the conditions under which the trigger fires - see the Zendesk conditions reference for details.

Zendesk Connections#

Zendesk Connection#

The Zendesk component authenticates requests with OAuth 2.0. To configure an application inside zendesk follow the directions in this guide Now, you will have to create a new Zendesk connection in Prismatic.

For Client ID enter in the unique identifier of your app inside the Zendesk admin dashboard. For Client Secret enter the generated client secret you received from the Zendesk admin dashboard.
For Scopes refer to the guide that was linked above. There is detailed information on picking the correct scope.

You can find your subdomain inside of your Zendesk URL: https://{YOUR SUBDOMAIN HERE}.zendesk.com/

Input	Default	Notes	Example
Input Authorize URL string / Required authorizeUrl	Default https://YOUR-ZENDESK-DOMAIN.zendesk.com/oauth/authorizations/new	Notes The OAuth 2.0 Authorization URL for Zendesk	Example https://acme-inc.zendesk.com/oauth/authorizations/new
Input Client ID string / Required clientId	Default	Notes	Example
Input Client Secret password / Required clientSecret	Default	Notes	Example
Input Scopes string / Required scopes	Default read write	Notes A space-delimited set of one or more scopes to get the user's permission to access.	Example read write
Input Token URL string / Required tokenUrl	Default https://YOUR-ZENDESK-DOMAIN.zendesk.com/oauth/tokens	Notes The OAuth 2.0 Token URL for Zendesk	Example https://acme-inc.zendesk.com/oauth/tokens

Triggers#

Zendesk Webhook#

Handle and validate webhook requests from Zendesk | key: webhook

Input	Notes
Input Connection connection / Required connection	Notes

Actions#

Create Ticket#

Create a new ticket | key: createTicket

Input	Default	Notes	Example
Input Assignee Id string assigneeId	Default	Notes Provide a valid user id for the assignee of the ticket.	Example 403598029853443232
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input External ID string externalId	Default	Notes The ID of this issue from an external system	Example
Input Followers string Value List followers	Default	Notes For each item provide a unique identifier of the follower you want to add to the issue.	Example 488042375842
Input Recipient Email string recipientEmail	Default	Notes Provide a string value for the name of the recipient.	Example Jane.Doe@example-prismatic.io
Input Requester Email string / Required requesterEmail	Default	Notes Provide a string value for the email of the requester.	Example John.Doe@example-email.com
Input Requester Name string / Required requesterName	Default	Notes provide a string value for the name of the requester.	Example John Doe
Input Requester Organization Id string requesterOrganization	Default	Notes Provide an integer value to specify the Organization of the requester.	Example 488042375842
Input Tags string Value List tags	Default	Notes For each item, provide a string value for the tag.	Example Engineering
Input Ticket Comment Body string ticketComment	Default	Notes When creating a ticket, this field can be used to give a ticket description. It will also leave a comment on the ticket from the assignee.	Example This is an example Comment.
Input Ticket Comment HTML Body string ticketCommentHTML	Default	Notes When creating a ticket, this field can be used to give a ticket description using HTML. It will also leave a comment on the ticket from the assignee.	Example <p>This is an example Comment.</p>
Input Ticket Priority string ticketPriority	Default	Notes Provide a string value for the priority of the ticket.	Example
Input Ticket Status string ticketStatus	Default	Notes Provide a string value for the status of the ticket.	Example
Input Ticket Subject string ticketSubject	Default	Notes Provide a string value for the subject of the ticket	Example This is an example ticket subject.
Input Ticket Type string ticketType	Default	Notes Provide a string value for the type of the ticket.	Example
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Create User#

Create a new user | key: createUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input External Id string externalId	Default	Notes A unique identifier from another system. The API treats the id as case sensitive. Example: "ian1" and "Ian1" are different users	Example
Input Moderator boolean isModerator	Default false	Notes This flag specifies whether or not the user will have moderator permissions.	Example
Input Verified boolean isVerified	Default false	Notes Flip this flag to true if any of the user's identities is verified.	Example
Input Organization Id string organizationId	Default	Notes Provide the unique identifier of the organization.	Example
Input Alias string userAlias	Default	Notes Provide a string value that represents an alias to give to a user.	Example Example Alias
Input Details string userDetails	Default	Notes Provide a string value that represents details to be attached to the user.	Example These are some example user details
Input Email Address string / Required userEmail	Default	Notes Provide a valid email address for the user. Make sure this value does not conflict with any other users in your Zendesk Domain	Example someone@example-prismatic.io
Input Name string / Required userName	Default	Notes Provide a string value for the name of the user.	Example John Doe
Input Notes string userNotes	Default	Notes Provide a string value that represents notes to be attached to the user.	Example These are some example notes.
Input Phone Number string userPhone	Default	Notes Provide a valid phone number for the user.	Example 15554008989
Input User Role string userRole	Default	Notes Provide which level of permissions the user is granted.	Example
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Create Webhook#

Create a webhook in Zendesk to notify you of changes to your users, organization, or tickets | key: createWebhook

Input	Default	Notes
Input Allow Duplicates? boolean / Required allowDuplicates	Default false	Notes
Input Callback URL string / Required callbackUrl	Default	Notes The URL to send data to
Input Events string / Required Value List events	Default	Notes Determines what events trigger a webhook to fire
Input Webhook Name string / Required name	Default	Notes A unique name to assign this webhook
Input Connection connection / Required zendeskConnection	Default	Notes

Output Example Payload#

{  "data": {    "webhook": {      "id": "01GK8E6BKWMJZD2T8Y5AXJQMG5",      "name": "Test from Prismatic",      "status": "active",      "subscriptions": [        "conditional_ticket_events"      ],      "created_at": "2022-12-02T03:31:00Z",      "created_by": "7272236579355",      "endpoint": "https://hooks.prismatic.io/trigger/EXAMPLE",      "http_method": "POST",      "request_format": "json"    }  }}

Create Webhook Trigger#

Create a trigger to cause a webhook to fire | key: createWebhookTrigger

Input	Default	Notes	Example
Input Allow Duplicates? boolean / Required allowDuplicates	Default false	Notes Allow a duplicate trigger with the same title to be created?	Example
Input Trigger Conditions code / Required conditions	Default `{ "all": [], "any": [ { "field": "status", "operator": "changed" }, { "field": "status", "operator": "not_changed" } ]}`	Notes The conditions under which this trigger will fire. Leave the default to fire under any change.	Example
Input Connection connection / Required connection	Default	Notes	Example
Input Webhook Message Body code / Required messageBody	Default { "current_user": { "details": "{{current_user.details}}", "email": "{{current_user.email}}", "external_id": "{{current_user.external_id}}", "first_name": "{{current_user.first_name}}", "language": "{{current_user.language}}", "name": "{{current_user.name}}", "notes": "{{current_user.notes}}", "organization.details": "{{current_user.organization.details}}", "organization.name": "{{current_user.organization.name}}", "organization.notes": "{{current_user.organization.notes}}", "phone": "{{current_user.phone}}", "tags": "{{current_user.tags}}" }, "ticket": { "account": "{{ticket.account}}", "assignee": { "first_name": "{{ticket.assignee.first_name}}", "last_name": "{{ticket.assignee.last_name}}", "name": "{{ticket.assignee.name}}" }, "brand": { "name": "{{ticket.brand.name}}" }, "cc_names": "{{ticket.cc_names}}", "ccs": "{{ticket.ccs}}", "comments_formatted": "{{ticket.comments_formatted}}", "description": "{{ticket.description}}", "due_date": "{{ticket.due_date}}", "email_cc_names": "{{ticket.email_cc_names}}", "email_ccs": "{{ticket.email_ccs}}", "external_id": "{{ticket.external_id}}", "follower_names": "{{ticket.follower_names}}", "follower_reply_type_message": "{{ticket.follower_reply_type_message}}", "followers": "{{ticket.followers}}", "group": { "name": "{{ticket.group.name}}" }, "id": "{{ticket.id}}", "in_business_hours": "{{ticket.in_business_hours}}", "latest_comment_formatted": "{{ticket.latest_comment_formatted}}", "latest_public_comment_formatted": "{{ticket.latest_public_comment_formatted}}", "link": "{{ticket.link}}", "organization": { "external_id": "{{ticket.organization.external_id}}", "name": "{{ticket.organization.name}}" }, "priority": "{{ticket.priority}}", "public_comments_formatted": "{{ticket.public_comments_formatted}}", "requester": { "email": "{{ticket.requester.email}}", "external_id": "{{ticket.requester.external_id}}", "first_name": "{{ticket.requester.first_name}}", "language": "{{ticket.requester.language}}", "last_name": "{{ticket.requester.last_name}}", "name": "{{ticket.requester.name}}", "phone": "{{ticket.requester.phone}}" }, "status": "{{ticket.status}}", "tags": "{{ticket.tags}}", "ticket_field_ID": "{{ticket.ticket_field_ID}}", "ticket_field_option_title_ID": "{{ticket.ticket_field_option_title_ID}}", "ticket_form": "{{ticket.ticket_form}}", "ticket_type": "{{ticket.ticket_type}}", "title": "{{ticket.title}}", "via": "{{ticket.via}}" }}	Notes The body to send to the webhook. See https://support.zendesk.com/hc/en-us/articles/4408886858138-Zendesk-Support-placeholders-reference	Example
Input Trigger Name string / Required title	Default	Notes	Example
Input Webhook ID string / Required webhookId	Default	Notes	Example 01GK7R2DBS16XB76SPDEXAMPLE

Output Example Payload#

{  "data": {    "trigger": {      "url": "https://example.zendesk.com/api/v2/triggers/10849292971419.json",      "id": 10849292971419,      "title": "Trigger for 01GK8E6BKWMJZD2TEXAMPLE",      "active": true,      "updated_at": "2022-12-02T03:36:44Z",      "created_at": "2022-12-02T03:36:44Z",      "default": false,      "actions": [        {          "field": "notification_webhook",          "value": [            "01GK8E6BKWMJZD2TEXAMPLE",            "{\"current_user\": \"{{current_user.details}}\"}"          ]        }      ],      "conditions": {        "all": [],        "any": [          {            "field": "status",            "operator": "changed",            "value": null          },          {            "field": "status",            "operator": "not_changed",            "value": null          }        ]      },      "description": null,      "position": 10,      "raw_title": "01GK8E6BKWMJZD2TEXAMPLE",      "category_id": "4558610559259"    }  }}

Delete Instance Webhooks#

Delete all webhooks pointed at this instance | key: deleteInstanceWebhooks

Input	Notes
Input Connection connection / Required zendeskConnection	Notes

Delete Ticket#

Delete the information and metadata of a ticket by Id | key: deleteTicket

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input Ticket Id string / Required ticketId	Default	Notes Provide the unique identifier for the ticket you would like to show.	Example ExampleTicketId
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Delete User#

Delete the information and metadata of a user by Id | key: deleteUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input UserId string userId	Default	Notes Provide an integer value for the unique identifier of the user.	Example 488042375842
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Delete Webhook#

Delete a webhook by ID | key: deleteWebhook

Input	Notes	Example
Input Webhook ID string / Required webhookId	Notes	Example 01GK59HW1XMB8WVZ43RPVAPXRM
Input Connection connection / Required zendeskConnection	Notes	Example

Get Ticket By External ID#

Get a ticket by external ID | key: getByExternalId

Input	Default	Notes
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.
Input External ID string externalId	Default	Notes The ID of this issue from an external system
Input Connection connection / Required zendeskConnection	Default	Notes

List Tickets#

List all Tickets | key: listTickets

Input	Default	Notes
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.
Input Connection connection / Required zendeskConnection	Default	Notes

List Tickets Assigned To User#

List all of the tickets that have been assigned to a particular user | key: listTicketsToUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input UserId string userId	Default	Notes Provide an integer value for the unique identifier of the user.	Example 488042375842
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Output Example Payload#

{  "data": {    "tickets": [],    "count": 5,    "next_page": 5,    "previous_page": 5  }}

List Tickets Requested By User#

List all of the tickets that a particular user has requested | key: listTicketsByUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input UserId string userId	Default	Notes Provide an integer value for the unique identifier of the user.	Example 488042375842
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Output Example Payload#

{  "data": {    "tickets": [],    "count": 5,    "next_page": 5,    "previous_page": 5  }}

List Triggers#

List workflow triggers | key: listTriggers

Input	Notes
Input Connection connection / Required connection	Notes

List Users#

List all Users | key: listUsers

Input	Default	Notes
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.
Input Connection connection / Required zendeskConnection	Default	Notes

Output Example Payload#

{  "data": {    "users": [],    "count": 5,    "next_page": 5,    "previous_page": 5  }}

List Webhooks#

List webhooks configured in Zendesk | key: listWebhooks

Input	Default	Notes
Input Show only instance webhooks boolean showOnlyInstanceWebhooks	Default true	Notes Show only webhooks that point to this instance
Input Connection connection / Required zendeskConnection	Default	Notes

Raw Request#

Issue a raw HTTP request | key: rawRequest

Input	Default	Notes	Example
Input Connection connection / Required connection	Default	Notes	Example
Input Data string data	Default	Notes The HTTP body payload to send to the URL.	Example {"exampleKey": "Example Data"}
Input Debug Request boolean debugRequest	Default false	Notes Enabling this flag will log out the current request.	Example
Input File Data string Key Value List fileData	Default	Notes File Data to be sent as a multipart form upload.	Example [{key: "example.txt", value: "My File Contents"}]
Input Form Data string Key Value List formData	Default	Notes The Form Data to be sent as a multipart form upload.	Example [{"key": "Example Key", "value": new Buffer("Hello World")}]
Input Header string Key Value List headers	Default	Notes A list of headers to send with the request.	Example User-Agent: curl/7.64.1
Input Max Retry Count string maxRetries	Default 0	Notes The maximum number of retries to attempt.	Example
Input Method string / Required method	Default	Notes The HTTP method to use.	Example
Input Query Parameter string Key Value List queryParams	Default	Notes A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.	Example
Input Response Type string / Required responseType	Default json	Notes The type of data you expect in the response. You can request json, text, or binary data.	Example
Input Retry On All Errors boolean retryAllErrors	Default false	Notes If true, retries on all erroneous responses regardless of type.	Example
Input Retry Delay (ms) string retryDelayMS	Default 0	Notes The delay in milliseconds between retries.	Example
Input Timeout string timeout	Default	Notes The maximum time that a client will await a response to its request	Example 2000
Input URL string / Required url	Default	Notes This is the URL to call.	Example /sobjects/Account
Input Use Exponential Backoff boolean useExponentialBackoff	Default false	Notes Specifies whether to use a pre-defined exponential backoff strategy for retries.	Example

The Raw Request action allows you to interact with API endpoints that are not covered by other actions. For example, if you want to list groups, which as an endpoint of /api/v2/groups, you can enter /groups as the endpoint and select the GET verb.

Search Users#

Returns an array of users who meet the search criteria. | key: searchUsers

Input	Default	Notes
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.
Input External Id string externalId	Default	Notes The external_id parameter does not support the search syntax. It only accepts ids.
Input Query string query	Default	Notes The query parameter supports the Zendesk search syntax for more advanced user searches. It can specify a partial or full value of any user property, including name, email address, notes, or phone. Example: query="jdoe".
Input Connection connection / Required zendeskConnection	Default	Notes

Output Example Payload#

{  "data": {    "users": [      {        "id": 35436,        "name": "Robert Jones",        "notes": "sigil issue"      },      {        "id": 9873843,        "name": "Terry Gilliam"      }    ]  }}

Show Ticket#

Get the information and metadata of a ticket by Id | key: showTicket

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input Ticket Id string / Required ticketId	Default	Notes Provide the unique identifier for the ticket you would like to show.	Example ExampleTicketId
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Show User#

Get the information and metadata of a user by Id | key: showUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input UserId string userId	Default	Notes Provide an integer value for the unique identifier of the user.	Example 488042375842
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Update Ticket#

Update the information and metadata of a ticket by Id | key: updateTicket

Input	Default	Notes	Example
Input Assignee Email string assigneeEmail	Default	Notes Provide a valid email for the assignee of the ticket.	Example Jane.Doe@example-prismatic.io
Input Assignee Id string assigneeId	Default	Notes Provide a valid user id for the assignee of the ticket.	Example 403598029853443232
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input File data file	Default	Notes The file to attach to the comment - either string contents or a binary file	Example
Input File Name string fileName	Default	Notes The name of the file to upload	Example
Input Requester Organization Id string requesterOrganization	Default	Notes Provide an integer value to specify the Organization of the requester.	Example 488042375842
Input Tags string Value List tags	Default	Notes For each item, provide a string value for the tag.	Example Engineering
Input Ticket Comment Body string ticketComment	Default	Notes When creating a ticket, this field can be used to give a ticket description. It will also leave a comment on the ticket from the assignee.	Example This is an example Comment.
Input Ticket Comment HTML Body string ticketCommentHTML	Default	Notes When creating a ticket, this field can be used to give a ticket description using HTML. It will also leave a comment on the ticket from the assignee.	Example <p>This is an example Comment.</p>
Input Ticket Id string / Required ticketId	Default	Notes Provide the unique identifier for the ticket you would like to show.	Example ExampleTicketId
Input Ticket Priority string ticketPriority	Default	Notes Provide a string value for the priority of the ticket.	Example
Input Ticket Status string ticketStatus	Default	Notes Provide a string value for the status of the ticket.	Example
Input Ticket Subject string ticketSubject	Default	Notes Provide a string value for the subject of the ticket	Example This is an example ticket subject.
Input Ticket Type string ticketType	Default	Notes Provide a string value for the type of the ticket.	Example
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Update User#

Update the information and metadata of a user by Id | key: updateUser

Input	Default	Notes	Example
Input Debug boolean debug	Default false	Notes This flag toggles debugging. When true the integration will log any requests and failures.	Example
Input External Id string externalId	Default	Notes A unique identifier from another system. The API treats the id as case sensitive. Example: "ian1" and "Ian1" are different users	Example
Input Moderator boolean isModerator	Default false	Notes This flag specifies whether or not the user will have moderator permissions.	Example
Input Verified boolean isVerified	Default false	Notes Flip this flag to true if any of the user's identities is verified.	Example
Input Organization Id string organizationId	Default	Notes Provide the unique identifier of the organization.	Example
Input Alias string userAlias	Default	Notes Provide a string value that represents an alias to give to a user.	Example Example Alias
Input Details string userDetails	Default	Notes Provide a string value that represents details to be attached to the user.	Example These are some example user details
Input Email Address string userEmail	Default	Notes Provide a valid email address for the user. Make sure this value does not conflict with any other users in your Zendesk Domain	Example someone@example-prismatic.io
Input UserId string / Required userId	Default	Notes Provide an integer value for the unique identifier of the user.	Example 488042375842
Input Name string userName	Default	Notes Provide a string value for the name of the user.	Example John Doe
Input Notes string userNotes	Default	Notes Provide a string value that represents notes to be attached to the user.	Example These are some example notes.
Input Phone Number string userPhone	Default	Notes Provide a valid phone number for the user.	Example 15554008989
Input User Role string userRole	Default	Notes Provide which level of permissions the user is granted.	Example
Input Time Zone string userTimeZone	Default	Notes Provide a valid timezone that the user operates in.	Example Berlin
Input Connection connection / Required zendeskConnection	Default	Notes	Example

Updating a user's 'User Role' from a end-user to administrator may cause a failed execution. For more information refer to the user permissions guide in the Zendesk docs.