Connect Zoho Desk to WhatsApp

All Zoho products use a custom Authorization header prefix. The format is: Authorization: Zoho-oauthtoken YOUR_TOKEN. Not 'Bearer'. This applies to Zoho Desk, Zoho CRM, Zoho Books and all other Zoho APIs. Using 'Bearer' returns a 401 error.

If your Zoho account was created in India, your API and OAuth URLs must use the India data centre domain. For API calls: desk.zoho.in/api/v1/. For OAuth token requests: accounts.zoho.in/oauth/v2/token. Using .zoho.com from an Indian account causes data centre mismatch errors.

POST https://accounts.zoho.in/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

Body (form fields):
  grant_type    = authorization_code
  client_id     = YOUR_CLIENT_ID
  client_secret = YOUR_CLIENT_SECRET
  code          = YOUR_GRANT_CODE

Response:
{
  "access_token": "1000.abc123...",
  "refresh_token": "1000.xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store BOTH access_token and refresh_token.
The access token expires after 1 hour.
Use the refresh token to get a new access token (see Step 2).

GET https://desk.zoho.in/api/v1/organizations
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN

Response:
{
  "data": [
    {
      "id": "728000000123456",
      "companyName": "Sharma Textiles",
      "portalName": "sharmatextiles",
      "edition": "PROFESSIONAL",
      "isAdminInOrg": true
    }
  ]
}

Copy the id value: 728000000123456
This is your orgId — add it to every subsequent API request header.

Zoho Desk uses string status values (not numeric codes like Freshdesk). You can use the status string directly in a WhatsApp reply without conversion.

{
  "data": [
    {
      "id": "728000000456789",
      "ticketNumber": "1001",
      "subject": "Order #5521 not delivered",
      "description": "My order placed on June 18 has not arrived.",
      "status": "open",
      "priority": "High",
      "contactId": "728000000234567",
      "departmentId": "728000000006907",
      "channel": "WhatsApp",
      "createdTime": "2026-06-20T10:30:00.000Z",
      "modifiedTime": "2026-06-22T14:00:00.000Z",
      "dueDate": "2026-06-24T10:30:00.000Z"
    }
  ],
  "count": 1
}

Map: data[0].ticketNumber, data[0].subject, data[0].status, data[0].priority

Zoho Desk wraps results in a 'data' array with a 'count' field. Map as data[0].subject, data[0].status. If count is 0 or data is empty, no open ticket was found for that email. Add a conditions branch for that case.

ticketNumber is the human-readable ticket number (#1001). id is the internal Zoho ID used in API calls. Use ticketNumber in customer-facing WhatsApp replies.

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

POST https://desk.zoho.in/api/v1/tickets
Authorization: Zoho-oauthtoken {{zoho_desk_token}}
orgId: 728000000123456
Content-Type: application/json

Body:
{
  "subject": "WhatsApp: {{customer_issue_summary}}",
  "description": "Customer message via WhatsApp:\n{{customer_message}}",
  "contactId": "{{contact_id}}",
  "departmentId": "YOUR_DEPARTMENT_ID",
  "priority": "Medium",
  "status": "open",
  "channel": "WhatsApp"
}

Response:
{ "id": "728000000456790", "ticketNumber": "1002", "status": "open" }

Bot replies:
"Ticket #{{ticket_number}} created. Our support team will
respond within 24 hours."

Find your departmentId: GET /api/v1/departments (same headers)
Returns: {{"data": [{{"id": "728000000006907", "name": "Support"}}]}}

Customer: "What is the status of my support ticket?"

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

Step 1 — Refresh token:
POST https://accounts.zoho.in/oauth/v2/token
  ?grant_type=refresh_token
  &refresh_token=1000.xyz789...
  &client_id=...&client_secret=...
Store: zoho_desk_token = "1000.abc123..."

Step 2 — Search tickets:
GET https://desk.zoho.in/api/v1/tickets
  ?email=priya@example.com&status=open&limit=1
Authorization: Zoho-oauthtoken {{zoho_desk_token}}
orgId: 728000000123456

Response: count=1
ticket_number  = "1001"
ticket_subject = "Order #5521 not delivered"
ticket_status  = "open"
ticket_priority = "High"

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 | Priority: High

Reply AGENT to request a callback, or CLOSE if resolved."