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.
   • Select the "Trigger or Automation" one
   
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. 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.

Set up Webhook triggers: #

There are 3 triggers needed to ensure correct functionality:

• to notify new comments
• to notify new tickets
• 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:
   
   
4. Trigger Actions:
   • Select Notify Active Webhook and choose the webhook you just created.
   • Set the following action on webhook trigger:
   
   
   Here is the JSON data that should be placed for the action:
   
   

         
   {
   "id": "{{ticket.id}}",
   "comment": "{{ticket.latest_public_comment}}",
   "support_name": "{{ticket.assignee.first_name}}",
   "agent_id": "{{ticket.latest_public_comment.author.id}}",
   "latest_public_comment_author_id": "{{ticket.latest_public_comment.author.id}}",
   "requester_external_id": "{{ticket.requester.external_id}}",
   "requester_email": "{{ticket.requester.email}}",
   "requester_language": "{{ticket.requester.language}}",
   "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 new ticket".
   • Conditions: Specify when the webhook should be triggered. In this case, the webhook must notify when a ticket is created:
   
   
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.
   Here is the JSON data that should be placed for the action
   
   

         
   {
   "id": "{{ticket.id}}",
   "ticket_status": "{{ticket.status}}",
   "via": "{{ticket.via}}",
   "requester_external_id": "{{ticket.requester.external_id}}",
   "requester_email": "{{ticket.requester.email}}",
   "requester_language": "{{ticket.requester.language}}"
   }
         
       

8. Add the third trigger:
• Click the Add Trigger button.
9. 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:
   
   
10. Trigger Actions:
    • Select Notify Active Webhook and choose the webhook you just created.
    • Create the action with the same logic as the first trigger.
    Here is the JSON data that should be placed for the action
    
    

          
    {
    "id": "{{ticket.id}}",
    "comment": "{{ticket.latest_public_comment}}",
    "support_name": "{{ticket.assignee.first_name}}",
    "agent_id": "{{ticket.latest_public_comment.author.id}}",
    "ticket_status": "closed",
    "via": "{{ticket.via}}",
    "requester_external_id": "{{ticket.requester.external_id}}",
    "requester_email": "{{ticket.requester.email}}",
    "requester_language": "{{ticket.requester.language}}"
    }
          
        

By the end of the integration you should have the webhook secret, to share with the Usizy team.

Conversations API #

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 Conversations API:
   • In the Admin Center, go to: Apps and Integrations → APIs → Conversations API
3. Create API key:
   • Click "Create API Key" button.
   • Provide a name like "Smart Assistant".
   • Copy the values for App ID, Key ID and Secret key.
   • Important: Copy the Secret key immediately. It will only be displayed once.

Conversations WebHook #

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 → Integrations → Conversations integrations.
3. Create integration:
   • Click "Create integration" button.
   • Provide a name like "Smart Assistant".
   • Enter the webhook URL https://smart-assistant.usizy.com/zendesk_messaging_webhook/<ecommerce_slug>
   • Mark "Include full user" and "Include full source" checkboxes.
   • On Webhook subscriptions check "Conversation message".
   • Copy Webhook ID and Shared Secret.