Connect Zendesk to WhatsApp

Zendesk is removing API token authentication in phases. Unused tokens deactivate automatically from July 28, 2026. All tokens stop working permanently on April 30, 2027. This guide teaches OAuth 2.0 as the primary method. If you already have a token-based integration, it will continue to work as long as the token is used at least once every 30 days, but migrate to OAuth before the April 2027 deadline.

This guide covers OAuth 2.0 as the primary path. The API token method is shown in the troubleshooting section for reference.

Your subdomain is the unique part of your Zendesk URL. If your URL is acme.zendesk.com, your subdomain is 'acme'. All API requests go to https://YOUR_SUBDOMAIN.zendesk.com/api/v2/.

Zendesk OAuth guide: developer.zendesk.com

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "Bearer",
  "scope": "read"
}

Map: access_token -> {{zendesk_token}}
Tokens are long-lived (no expiry by default on client_credentials).
Store in a persistent variable or re-request at the start of each conversation.

The ticket search requires the customer's email. Before this step, your chatbot flow must ask the customer to type their email, or collect it from a previous interaction stored in the Mini-CRM. Store it as {{customer_email}} to use in the search query.

Zendesk search queries use space-separated conditions. Use + for URL encoding of spaces in GET parameters. All conditions are AND by default.

{
  "results": [
    {
      "id": 1001,
      "url": "https://acme.zendesk.com/api/v2/tickets/1001.json",
      "subject": "Order #5521 not delivered",
      "description": "My order was placed on June 18 but has not arrived.",
      "status": "open",
      "priority": "normal",
      "requester_id": 447,
      "assignee_id": 12,
      "created_at": "2026-06-20T10:30:00Z",
      "updated_at": "2026-06-22T14:00:00Z",
      "result_type": "ticket"
    }
  ],
  "count": 1,
  "next_page": null
}

Map: results[0].id, results[0].subject, results[0].status, results[0].priority

Zendesk search results come under a 'results' key, not 'tickets' or 'data'. Map as results[0].subject, results[0].status. If count is 0 or results is empty, the customer has no matching open tickets. Add a conditions branch for that case.

ticket_count tells you how many open tickets this customer has. If count is 0, reply that no open tickets were found. If count is more than 1, mention the total and show the most recent.

If the customer messaged you first within the last 24 hours, your reply is a free service conversation. For proactive outbound ticket updates triggered from Zendesk, use an approved Utility template.

POST https://YOUR_SUBDOMAIN.zendesk.com/api/v2/tickets.json
Authorization: Bearer {{zendesk_token}}
Content-Type: application/json

Body:
{
  "ticket": {
    "subject": "WhatsApp: {{customer_message_summary}}",
    "comment": {
      "body": "Customer WhatsApp message: {{customer_message}}"
    },
    "requester": {
      "name": "{{customer_name}}",
      "email": "{{customer_email}}"
    },
    "priority": "normal",
    "tags": ["whatsapp", "bot-created"]
  }
}

Response:
{ "ticket": { "id": 1002, "status": "new", ... } }

Map: ticket.id -> new_ticket_id
Bot replies: "Ticket #{{new_ticket_id}} created. Our team will respond within 24 hours."

Customer messages: "What is the status of my support request?"

Bot asks: "Please share the email address used to raise the ticket."
Customer replies: priya@example.com
Stored as {{customer_email}}.

Step 1 — Get token (if not already stored):
POST https://acme.zendesk.com/oauth/tokens
Body: {{"grant_type":"client_credentials","client_id":"...","client_secret":"...","scope":"read"}}
Store: zendesk_token

Step 2 — Search tickets:
GET https://acme.zendesk.com/api/v2/search.json
  ?query=type:ticket+requester:priya@example.com+status:open
Authorization: Bearer {{zendesk_token}}

Response: count=1
ticket_id      = 1001
ticket_subject = "Order #5521 not delivered"
ticket_status  = "open"
ticket_updated = "2026-06-22T14:00:00Z"

Conditions: if count = 0 → "No open tickets found for this email."

Bot replies (if found):
"Hi Priya, here is your ticket update:

Ticket #1001: Order #5521 not delivered
Status: Open
Last updated: 22 June 2026

Our team is working on it. Reply AGENT to request a callback,
or CLOSE to mark this as resolved."

1. Enable token access:
   Admin Center > Apps and Integrations > APIs > API Tokens > Enable

2. Create a token and copy it.

3. Auth header format:
   Username: your_email@company.com/token
   Password: your_api_token

   In the Authorization header (Basic Auth):
   Authorization: Basic BASE64(email/token:your_token)

   Example (not encoded):
   admin@acme.com/token:6wIJBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

4. The GET request is the same — just swap the Authorization header.
   GET https://acme.zendesk.com/api/v2/search.json?query=type:ticket+requester:email

IMPORTANT: This stops working April 30, 2027.
Migrate to OAuth 2.0 (Step 1-2 above) before that date.