Zendesk

Integrate your bot with Zendesk using the official integration.

The official Zendesk integration allows you to create and manage support tickets directly from your bot. You can also assign a Zendesk agent to communicate directly with the user, all within the same conversation initially handled by the bot.

Your Zendesk agent can continue the conversation on any messaging channel supported by Botpress. For example:

• Webchat
• WhatsApp
• Messenger

Setup

You will need:

• A published bot
• A Zendesk account

1. Add the Zendesk Integration

   First, install the official Zendesk integration. Use the search bar to find and select the Zendesk Integration. Once found, install this onto your bot.

2. Setup the Zendesk Integration

   Switch to the Zendesk admin center, and find the Zendesk API menu. Ensure you have both password and token access enabled.

   You will then need to create a distinct API token. Copy this for later use.

   Return to your bot’s dashboard. Here you will need to input your organizational subdomain, your consistent Zendesk account email, and the copied API token. Ensure to save this configuration and activate the newly installed integration.

3. Install the HITL plugin

   Next, install the official HITL plugin. This will allow you to start HITL from any point in your Workflow.

   1. Navigate back to Botpress Hub and search for the HITL plugin.
   2. Select it, then select Install Plugin:

   3. In the Configuration menu, open the dropdown under HITL integration.
   4. Select Zendesk.
   5. Scroll down and select Save.

   The Configuration section contains many optional fields. You can use these to customize your HITL experience.

4. Add the Start HITL Card

   Now, you can bring a live agent into the conversation anywhere in your Workflow:

   1. Open a Workflow in Studio and create (or select) a Node.
   2. Add the Start HITL Card:

   3. Fill in the required fields:

   Fields	Description
   Ticket Title	The name of the ticket created for the live agent.
   User ID	The user ID associated with the ticket. Enter the {{event.userId}} variable to use the current user’s ID.
   Conversation ID	The conversation ID associated with the ticket. Enter the {{event.conversationId}} variable to use the current conversation’s ID.

Done! You can now create and manage support tickets directly from your bot.

Cards

You can use the following Cards to interact with Zendesk in your Workflow:

Get Ticket

Retrieves details about a specific support ticket in Zendesk.

• Input:
  • Ticket ID: The ID of the ticket from the ticket URL.
    (e.g., https://companyname.zendesk.com/agent/tickets/1 for Ticket ID 1).
• Returns: Real-time updates on the status and details of the ticket.

// Return object example
{
  "ticket": {
    "id": 4,
    "subject": "Ticket Subject",
    "description": "Ticket Description",
    "priority": null,
    "status": "open",
    "tags": [],
    "requesterId": 11183521570160,
    "assigneeId": 11183526440284,
    "createdAt": "2023-11-08T18:27:49Z",
    "updatedAt": "2023-11-10T18:03:13Z"
  }
}

Create Ticket

Creates a new support ticket in Zendesk.

• Inputs:
  • Ticket subject: Title of the ticket.
  • Ticket comment: Initial message for the support agent.
  • Requester name: Name of the user needing support.
  • Requester email: Email of the user needing support.
• Returns: Confirmation of ticket creation with details.

// Return object example
{
  "ticket": {
    "id": 4,
    "subject": "Ticket Subject",
    "description": "Ticket Description",
    "priority": null,
    "status": "open",
    "tags": [],
    "requesterId": 11183511570160,
    "assigneeId": 11183521440284,
    "createdAt": "2023-11-08T18:27:49Z",
    "updatedAt": "2023-11-10T18:03:13Z"
  }
}

Close Ticket

Closes the ticket of the provided Ticket ID in Zendesk.

• Input:
  • Ticket ID: The ID of the ticket from the ticket URL.
    (e.g., https://companyname.zendesk.com/agent/tickets/1 for Ticket ID 1).
• Optional: Closing Comment for resolution summary or thanks.
• Returns: Confirmation that the ticket is closed with optional comment.

// Return object example
{
  "ticket": {
    "id": 4,
    "subject": "Ticket Subject",
    "description": "Ticket Description",
    "priority": null,
    "status": "closed",
    "tags": [],
    "requesterId": 11183511570160,
    "assigneeId": 11183521440284,
    "createdAt": "2023-11-08T18:27:49Z",
    "updatedAt": "2023-11-10T18:03:13Z"
  }
}

Get Ticket Conversation

Fetches the conversation ID of the provided Ticket ID in Zendesk.

• Input:
  • Ticket ID: The ID of the ticket from the ticket URL.
    (e.g., https://companyname.zendesk.com/agent/tickets/1 for Ticket ID 1).
• Returns: Latest updates or responses from support agents on the ticket.

// Return object example
{
  "conversationId": "5c9ea21d-3ce3-43fa-bd33-3fb7312f88b5",
  "tags": {"zendesk:id": "4", "zendesk:requesterId": "11232621609372"}
}

Find Customer

Finds a customer in Zendesk based on the provided search query.

• Input:
  • Search Query: You can search by name, email, or phone number of the customer.
• Returns: A list of matching customers and their details.

// Return object example
{
  "customers": [
    {
      "id": 11183521570160,
      "name": "Customer Name",
      "email": "Customer Email",
      "phone": "Customer Phone",
      "createdAt": "2023-11-08T18:27:49Z",
      "updatedAt": "2023-11-10T18:03:13Z"
    }
  ]
}

List Agents

Provides a list of available support agents in Zendesk.

• Input:
  • Is Online: Select this option to filter the list of agents by online status.
• Returns: List of agents, optionally filtered by online status.

// Return object example
{
  "agents": [
    {
      "id": 11183521570160,
      "name": "Agent Name",
      "email": "Agent Email",
      "phone": "Agent Phone",
      "createdAt": "2023-11-08T18:27:49Z",
      "updatedAt": "2023-11-10T18:03:13Z"
    }
  ]
}

Triggers

The Zendesk integration comes with a few built-in triggers:

HITL Assigned

The HITL Assigned trigger fires when a ticket is assigned to an agent. You can use it to notify the agent that they have a new ticket to work on.

HITL Stopped

The HITL Stopped trigger fires when a ticket is marked as solved. You can use it to notify the user that their issue has been resolved.