Zendesk

Obtain the API Key in Zendesk:
  1. Log in to Zendesk Admin Center:
    • Go to: https://<your_subdomain>.zendesk.com/admin.
    • Replace <your_subdomain> with the subdomain of your Zendesk account.
  2. Navigate to API Settings:
    • In the Admin Center, go to: Apps and Integrations → APIs → Zendesk API.
  3. Enable API Access:
    • Locate the Settings section.
    • Enable the toggle for Token Access (this allows the generation of API tokens).
  4. Generate an API Token:
    • Click the Add API Token button.
    • Give the token a meaningful name (e.g., "Smart Assistant").
    • Click Create to generate the token.
    • Important: Copy the token immediately. It will only be displayed once.
Obtain the User email in Zendesk:
  1. Go to the User Profile
    • In the Admin Center, navigate to People → Agents.
    • Locate the user account you want to associate with the API token.
  2. Note the User Email:
    • Open the agent's profile and copy the email address listed.
Configure a Webhook in Zendesk:
  1. Log in to Zendesk Admin Center:
    • Go to: https://<your_subdomain>.zendesk.com/admin.
    • Replace <your_subdomain> with the subdomain of your Zendesk account.
  2. Navigate to Webhooks:
    • In the Admin Center, go to: Apps and Integrations → Webhooks → Create Webhook.
  3. Create a New Webhook:
    • Click the Create Webhook button.
  4. Enter Webhook Details:
    • Name: Provide a meaningful name for the webhook, such as "Zendesk Assistant Webhook".
    • Endpoint URL: Enter the URL https://smart-assistant.usizy.com/zendesk_webhook/<ecommerce_slug>.
    • Ecommerce slug: Ecommerce slug is provided by usizy.
    • Request Method: Choose POST.
    • Request Format: Choose JSON.
    • If your endpoint requires authentication, configure it under Authentication (And share the needed credentials with the Usizy team).
  5. Test the Webhook:
    • Click the Test Webhook button to send a sample payload to your endpoint.
    • Ensure your endpoint responds correctly.
  6. Save the Webhook:
    • If the test is successful, click Save to activate the webhook.
Share webhook secret:

A webhook secret is needed for security reasons.

  1. Go to the webhook you just created
    • In the Admin Center, navigate to Apps and Integrations → Webhooks → Your webhook
    • In the bottom, click reveal secret.
    • Share the secret with the Usizy team.

    2. Zendesk webhook_secret
Set up custom fields:
    A custom field is needed for technical purposes. Since Zendesk does not give the option to set read only fields, a text field is created storing internal data that we use to manage conversations an users.
    Important: This data must not be managed in any way by a human being, and is only modified and used by our system
  1. Create a new custom field
    • In the Admin Center, go to: Objects and Rules → Tickets → Fields → Add field
    • Create a new Text type custom field, with the name you want (Something similar to sa_user_info)
    • In the Permissions section, check the "Agents can edit" option
  2. Save the id of the created user field, since you will need it for the next step. You can get it in the Objects and Rules → Tickets → Fields section:
    3. Zendesk custom field
  3. Share this id with the Usizy team. We need to adjust our system with this id before continuing with the integration.
Set up Webhook triggers:

There are 2 triggers needed to ensure correct functionality, one to notify new comments and one to notify ticket closing.

  1. Navigate to Triggers:
    • In the Admin Center, go to: Objects and Rules → Business Rules → Triggers.
  2. Create the first trigger:
    • Click the Add Trigger button.
  3. Define Trigger Conditions:
    • Name: Provide a name like "Notify Assistant on new comment".
    • Conditions: Specify when the webhook should be triggered. In this case, the webhook must notify when there's a new comment on a ticket. These 2 rules should be added to ensure correct behaviour:

      • Zendesk triggers
  4. Trigger Actions:
    • Select Notify Active Webhook and choose the webhook you just created.
    • Set the following action on webhook trigger (Remember to set the id of the custom field you created in the field above):

      • Zendesk action
      Here is the JSON data that should be placed for the action (Please remember to set the correct ids):

            
{
"id": "{{ticket.id}}",
"comment": "{{ticket.latest_public_comment}}",
"support_name": "{{ticket.assignee.first_name}}",
"agent_id": "{{ticket.latest_comment.author.id}}",
"latest_public_comment_author_id": "{{ticket.latest_public_comment.author.id}}",
"user_info": "{{ticket.ticket_field_<custom_field_id>}}",
"attachments": [
    {% for attachment in ticket.latest_public_comment.attachments %}
    {
      "file_name": "{{attachment}}",
      "url": "{{attachment.url}}"
    }{% unless forloop.last %},{% endunless -%}
    {% endfor %}
  ]
}
  5. Add the second trigger:
    • Click the Add Trigger button.
  6. Define Trigger Conditions:
    • Name: Provide a name like "Notify closed ticket".
    • Conditions: Specify when the webhook should be triggered. In this case, the webhook must notify when a ticket is closed/resolved:

      • Zendesk triggers
  7. Trigger Actions:
    • Select Notify Active Webhook and choose the webhook you just created.
    • Create the action with the same logic as the first trigger.
      • The JSON data is the same you used for the first trigger, but it has an additional "ticket_status" value:

            
{
"id": "{{ticket.id}}",
"comment": "{{ticket.latest_comment}}",
"support_name": "{{ticket.assignee.first_name}}",
"agent_id": "{{ticket.latest_comment.author.id}}",
"user_info": "{{ticket.ticket_field_<custom_field_id>}}",
"ticket_status": "closed"
}

    8. By the end of the integration you should have 2 ids (Custom field and webhook secret) to share with the Usizy team.

← Salesforce
Stripe →