AI security & operations for MSPs

Zendesk

What Hal reads

Zendesk is your helpdesk, and Hal reads it as a log source. Every update to a ticket your team is still working, new, open, pending or on hold, arrives as an event: the ticket’s number, status, priority, type and subject; the requester, their organization and their email domain; the assignee; the channel the ticket came in by; the tags; and the newest comment, whether a public reply or an agent’s internal note. A solved or closed ticket is passed over. The first read reaches back a week.

Each ticket is attributed to one of your clients through its Zendesk organization: one that carries the client’s UID in a custom organization field named halclient, or one whose domains match a client’s domains in Hal. If the ticket has no organization, the requester’s own organization is tried, then the requester’s email domain. A ticket that matches no client is kept and marked unattributed, and a lookalike domain never matches.

Tickets are retained and searchable like every other source. Each update to a ticket that belongs to a client is reviewed on its own, never in a batch with the client’s other activity: Hal reads the whole ticket and decides whether it is a security matter. Most are not, and nothing happens. A user reporting a suspicious email, a password prompt they did not ask for, or a vendor asking to change bank details gets a second opinion and then an investigation, which reads that user’s sign-ins, mail, mailbox rules and app consents to decide whether the report is a false alarm or a real event. How your own agents handle a ticket is never the finding.

What Hal writes

Two things, both internal notes on your own tickets, visible to your agents and never to the requester or your client.

  • A note when a ticket leads to a report. When Hal raises a report from a ticket, he posts one internal note on that ticket: what he found, his verdict, and where the full report is.
  • An answer when an agent asks. When one of your agents writes an internal note that names Hal, Hal, is this phishing?, @Hal can you check this user’s sign-ins, he answers on the same ticket with an internal note, from the ticket and from the evidence about the requester. The whole word “Hal” in an agent’s internal note is the trigger; a public comment or a requester never triggers it, and a note that names him without asking anything gets one line back. Hal keeps a thread per ticket, so a follow-up question continues the conversation. He never repeats a credential or a one-time code that appears in a ticket.

Hal’s Zendesk user is a Contributor, a role Zendesk itself limits to viewing the tickets in its groups and writing private comments. He cannot create tickets, reply publicly, change a field or be assigned. His internal notes are written on your own helpdesk, which is your system, not a client’s. Read-only by architecture →

Start in chat

As a Hal admin, open the portal chat and say Connect Zendesk. Hal relays the steps on this page in order, with each client’s UID beside them. When you have pasted the credential and say so, he hands you a link to open in a browser signed in to Zendesk as Hal’s user; approving it completes the connection. He then tells you who authorized and asks you to confirm it is Hal’s user, reads your organizations, and says which are mapped to clients, which are not, and which conflict. Say you’re ready and he enables the integration. The rest of this page is the same steps written out.

Before you start

  • You need a Zendesk administrator who can create team members and OAuth clients.
  • Note your Zendesk subdomain, the part before .zendesk.com in your address.
  • Hal’s user needs an email address your team can read. An alias on your helpdesk mailbox works.
  • If your team signs in with SSO, Hal’s user needs a Zendesk password: in Admin Center go to Account → Security → Team member authentication, and under How team members sign in choose Let them choose. Otherwise you would have to create an identity for Hal in your identity provider.

Create Hal’s user

  1. In Admin Center, open People → Team → Team members and add a team member named Hal with the Contributor role. On every Suite and Support plan a Contributor takes no agent seat in Support, provided its roles in Zendesk’s other products (Chat, Guide, Explore) are left at their defaults; an Agent, Admin or Editor role there would use a seat.
  2. Add the user to every group whose tickets Hal should read. A Contributor sees only the tickets in its groups.
  3. Sign in once as that user to set its password. The OAuth approval in the next steps has to run as Hal’s user, not as you.

Create the OAuth client

In Admin Center open Apps and integrations → APIs → OAuth clients and click Add OAuth client.

  1. Name: Hal. Description: Hal reads tickets and posts internal notes. Company: your MSP’s name, or Hal AI. Zendesk shows these on its approval screen, which only Hal’s user will ever see.
  2. Identifier: hal.
  3. Client kind: Confidential.
  4. Redirect URLs: one line, https://portal.<code>.runhal.com/oauth/zendesk/callback, where <code> is the same code as your portal address. Hal gives you the exact address in chat.
  5. Scopes: tickets:read, tickets:write, users:read, organizations:read, and nothing else. Hal asks for exactly these four.
  6. Save, then copy the Secret. It is shown once. The client identifier is the one you chose.

Hand it to Hal

In the Hal portal, open Settings → Zendesk, enter the Subdomain, the Client identifier and the Client secret, and Save. The credential goes into this page, never into chat.

The Zendesk section of Hal's Settings page: fields for Subdomain with .zendesk.com after it, Client identifier reading hal, and Client secret, Test Connection and Save buttons; below them a Connection line reading Connected as Hal, an Organizations paragraph, a line reading 8 organizations synced, and Generate JSON and Download JSON buttons
Hal’s portal, Settings → Zendesk. The three fields and Save above; below, who Hal is connected as, how many organizations he has synced, and the map behind Generate JSON.

Then tell Hal in chat that it’s pasted. He gives you an authorization link. Open it in a browser signed in to Zendesk as Hal’s user, a private window is the easy way; when Zendesk sends you back to your portal, that window asks you to sign in to Hal as an admin first. Zendesk’s approval screen shows the name, description and company you gave the client and lists the four scopes in its own words; at the bottom it names the user you are signed in as, which should be Hal’s user. Click Allow.

Zendesk's OAuth approval screen: the Hal logo, Hal by HAL AI LLC, the question Allow Hal to access your Zendesk account?, the description Hal reads tickets and posts internal notes, a list headed This application would be able to with four lines, Read all ticket data, Write all ticket data, Read all user data and Read all organizations data, Deny and Allow buttons, and a Not Hal? link naming the signed-in user
Zendesk’s approval screen. The four lines are the four scopes in Zendesk’s words. The second is tickets:write; what Hal can actually write is bounded by the Contributor role, private comments only.

Zendesk then returns you to a page on your portal that says Zendesk is authorized and names the user Hal is connected as. Close it and go back to chat, where Hal tells you who authorized and asks you to confirm it is Hal’s Contributor user. Hal connects only as a Contributor: an approval by anyone else, you, another agent or an end user, is refused outright. Sign out of Zendesk, sign in as Hal, and ask again. He then reads your organizations.

Map organizations to clients

Hal maps each Zendesk organization to a client in one of two ways, and the first that applies wins:

  • A custom organization field named halclient holding the client’s UID, the value in the Client UID column of Hal’s Clients page. It is the same value the NinjaOne integration uses.
  • The organization’s domains matching a client’s domains in Hal, exactly.

Settings → Zendesk counts the organizations Hal has synced; Generate JSON shows every one with its domains, the client it maps to, and its state: mapped, no client, two clients (its domains match two of yours), or an unknown value in the field, and Download JSON saves the same map as a file. Under it is the count of ticket updates in the last 7 days that matched no client. To fix an organization, add the domain to the client in Hal, which you can ask him to do in chat, or set the halclient field in Zendesk. Tickets that match no client are still kept and searchable, and Hal answers on them when an agent asks; they are never reviewed, because there is no client’s evidence to read them against.

Keeping the connection

Zendesk’s OAuth clients issue short-lived access tokens and a refresh token that lasts 30 days, rotated on every refresh. Hal refreshes it himself as he runs, many times a day, so the authorization lapses only if Hal has not run with Zendesk enabled for 30 days. If it does, or if Zendesk rejects the authorization (the client’s tokens revoked, Hal’s user suspended), Settings → Zendesk says the authorization has expired, and Connect Zendesk in chat runs the approval again.

Cost

Each review of a ticket update shows on the Costs page as Ticket review. A ticket that escalates adds its second opinion and its investigation to those lines on the same page. Hal’s answers on tickets are chat turns on the interactive model, one per question, and show on the Costs page as chat.

See what Hal surfaces on your own clients.

No deck. Ask us anything first. When you want to see Hal on your own tenants, we sign a short evaluation agreement and stand up your instance; you connect one tenant, Hal watches it for 14 days, and we walk you through what he found.

  1. 01You ask us your questions. No deck, no demo dataset.
  2. 02You sign a short evaluation agreement, and we stand up your own instance.
  3. 03You connect one tenant from your own admin console. Hal watches it for 14 days.
  4. 04We walk through what he found. Keep going month to month, or revoke the scopes yourself and stop.