🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Zoho Desk Premium Add-on Setup Guide

Updated 8 min read Gravity Forms Integrations A–Z
On this page
  1. Video walkthrough
  2. What you need
  3. Install and activate
  4. Connect your Zoho account
  5. Option 1: Self Client (the quickest)
  6. Option 2: Server-based client (sign in with Zoho)
  7. How the secrets are kept
  8. Create a feed
  9. Ticket
  10. Contact
  11. Attachments
  12. Condition
  13. What happens on a submission
  14. For developers and administrators
  15. Troubleshooting
  16. Questions
  17. Do I need a Zoho developer account?
  18. Does it work with every Zoho data centre?
  19. Does it send my tickets to GravityExtra?
  20. Can one form create tickets in two departments?
  21. What if the same person writes again?

Video walkthrough

Gravity Forms Zoho Desk Add-On Setup Guide: Zoho OAuth Client and Ticket Feed (WordPress Side)
Video setup guide: Gravity Forms Zoho Desk Watch on YouTube

The Gravity Forms Zoho Desk Premium Add-on turns a Gravity Forms submission into a support ticket in Zoho Desk. When a visitor sends the form, the add-on finds or creates the contact in Zoho Desk by email address, creates the ticket in the department you choose with the subject, description, priority, status and custom fields you map, and attaches the files the visitor uploaded.

You connect your own Zoho account with your own OAuth client from the Zoho API Console, either a Self Client or a Server-based client. The add-on talks to Zoho Desk directly from your server, in the data centre where your Zoho account lives: United States, Europe, India, Australia, Japan or Canada. No GravityExtra server sees your tickets, your contacts or your Zoho keys.

What you need

  • WordPress 6.5 or newer and PHP 7.4 or newer, with the OpenSSL extension (every normal host has it).
  • Gravity Forms 2.9 or newer. The add-on is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.
  • A Zoho Desk account with permission to create an API client, and an active license key for this add-on.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else. The add-on uses the Zoho Desk REST API version 1.

Install and activate

  1. Install and activate the add-on like any plugin, after Gravity Forms.
  2. Open Forms → Settings → Zoho Desk and enter your license key.
  3. The Zoho Desk connection section appears. Connect your Zoho account as described next.

Connect your Zoho account

The Zoho Desk connection settings in Gravity Forms: data centre, client type, client ID, client secret, Self Client code and organisation ID
Forms, Settings, Zoho Desk: your own Zoho client, the data centre and the organisation.

Choose the data centre first. It is the one your Zoho Desk address ends with: desk.zoho.com is the United States, desk.zoho.eu Europe, desk.zoho.in India, desk.zoho.com.au Australia, desk.zoho.jp Japan and desk.zohocloud.ca Canada. A client made in one data centre does not work in another, so choose the same one you used in the API Console.

Option 1: Self Client (the quickest)

  1. Open the Zoho API Console for your data centre and choose Add Client → Self Client.
  2. Copy the Client ID and the Client Secret into the add-on settings.
  3. In the Self Client, open Generate Code. As the scope, enter Desk.tickets.ALL, Desk.contacts.ALL, Desk.basic.READ, Desk.settings.READ, Desk.search.READ. Choose a time duration of 10 minutes, give a short description and choose your Zoho Desk portal. Press Create and copy the code.
  4. Paste the code into the field Self Client code and press Save Settings.

The add-on exchanges the code for a long-lived refresh token, stores it encrypted, finds your Zoho Desk organisation and tells you so at the top of the settings. The code is used once and is not stored. If you have more than one Zoho Desk organisation, the message lists them with their IDs; copy the right ID into the Organisation ID field and save again.

Option 2: Server-based client (sign in with Zoho)

  1. In the API Console choose Add Client → Server-based Applications.
  2. Add the Authorized Redirect URI that the settings screen shows (it ends with page=gf_settings and subview=gfzohodesk).
  3. Copy the Client ID and the Client Secret into the settings, choose Server-based as the client type and save.
  4. Press Sign in with Zoho, accept the access, and you come back to the settings, connected.

Both types end the same way: a refresh token that the add-on uses to get short-lived access tokens. Access tokens are cached for a little under their lifetime, stored encrypted, and renewed by themselves. If Zoho answers that a token has expired, the add-on renews it and repeats the call once.

How the secrets are kept

The client secret, the refresh token and the cached access tokens are encrypted with AES-256-GCM before they are saved in the database, with a key made from your site’s WordPress salts. The client secret is never sent back to the browser: the settings screen shows a mask, and saving with the mask keeps the stored secret. If you change the salts in wp-config.php, the stored secrets can no longer be read, and you simply enter the secret again and reconnect. Uninstalling the add-on from the Plugins screen removes everything it stored.

Create a feed

Open Forms → Settings of a form, choose Zoho Desk and Add New. A form can have several feeds, for example one that sends sales questions to a Sales department and one that sends support requests to Support, each with its own condition.

The Zoho Desk feed settings: department, ticket subject and description, priority, status, channel, custom fields, contact fields and attachments
The feed: department from your Zoho Desk, the ticket fields, the contact and the attachments.

Ticket

  • Department: the list is read from your Zoho Desk (enabled departments). The list is kept for ten minutes.
  • Ticket subject: text with merge tags, for example the answer of a Subject field. The default is the form title.
  • Ticket description: text with merge tags. The default, all fields, writes every answer in the description, with the line breaks kept.
  • Priority: Low, Medium, High or not set. Priority from a form field lets the visitor decide: an answer of Low, Medium or High (also Normal, Moderate, Urgent, Critical or Minor) sets the priority, anything else falls back to the fixed priority above.
  • Status (Open, On Hold, Escalated, Closed), Channel (Web is the default) and Classification (Question, Problem, Feature, Others).
  • Custom ticket fields: pairs of a Zoho Desk field API name that starts with cf_ and a value with merge tags. A name that does not start with cf_ is ignored.

Contact

Map the form fields to the contact: Email (required), first name, last name and phone. A Name field offers its first and last name parts. If you have only one field for the whole name, map it to the first name only and the add-on splits it at the last space.

With Create the contact in Zoho Desk when the email is not there yet ticked (the default), the add-on first searches for a contact with that email address. If one exists it is used, with no second contact and no change to it. If none exists, it is created, and the ticket is linked to it. If the search or the creation fails, the ticket is still created with the email address and the contact details inside the ticket, so Zoho Desk makes the contact, and a note on the entry says what went wrong. Zoho Desk needs a last name for every contact; when the form has none, the add-on uses the first name, or the part of the email address before the at sign.

Attachments

If the form has file upload fields, the feed lists them. Tick the ones to attach. Each uploaded file is sent to the ticket as an attachment, one request per file. Tick Show the attachments to the customer to make them public; otherwise they are visible to agents only. Zoho Desk accepts files up to 20 MB: a bigger or empty file is skipped, and a note on the entry names it. A file that cannot be uploaded never stops the ticket.

Condition

Use the condition to send only some submissions, for example only when a Topic drop-down is Billing.

What happens on a submission

  1. The visitor sends the form. Gravity Forms saves the entry as always.
  2. The add-on checks the email address. Without a valid one it adds a note and stops.
  3. It finds or creates the contact, then creates the ticket, then attaches the files.
  4. It writes notes on the entry: the ticket number with the link to the ticket in Zoho Desk, and one line for every file. The ticket id is saved as entry meta so that the same feed never makes a second ticket for the same entry.
A Gravity Forms entry screen with the notes the add-on wrote: the Zoho Desk ticket number and link, and the attached files
On every entry: the ticket number, the link to the ticket and the files that were attached.

Everything is done on the server when the form is sent, so the visitor never sees Zoho or waits for anything but the normal confirmation. If Zoho Desk is down or refuses a request, the entry is saved, and the note on it shows the answer from Zoho, for example the error code and message.

For developers and administrators

  • The ticket id of a feed is saved in the entry meta key gfzd_ticket_ followed by the feed id, and the ticket number in gfzd_ticket_number. Use them in exports and in other add-ons.
  • The add-on stores one option, gravityformsaddon_gfzohodesk_settings, and two kinds of transients (access token and department list).
  • All requests use the WordPress HTTP API with SSL verification on, so a site can filter or log them in the usual ways.

Troubleshooting

  • The department list is empty: check the connection message in the settings, the organisation ID and the data centre. The list shows the Zoho error under the field.
  • Zoho refused the request: invalid_code: the Self Client code was already used or older than its time limit. Generate a new one.
  • HTTP 401 or invalid_client: the client ID or secret does not match the data centre, or the refresh token was revoked. Connect again.
  • No ticket and a note about the email: the email field is empty or not a valid address.
  • A custom field is not set: use the field API name that starts with cf_, as shown in Zoho Desk under Setup, Customization, Layouts and fields.
  • I changed my salts: enter the client secret again and reconnect.

Questions

Do I need a Zoho developer account?

You need access to the Zoho API Console of the account that owns the Zoho Desk portal. Creating a Self Client takes about two minutes and costs nothing.

Does it work with every Zoho data centre?

It works with the United States, Europe, India, Australia, Japan and Canada data centres. Pick the one where your Zoho Desk account lives.

Does it send my tickets to GravityExtra?

No. The add-on contacts only Zoho, from your own server, with your own keys. The only call to GravityExtra is the license check and the update check.

Can one form create tickets in two departments?

Yes. Add two feeds, each with its own department and, if you wish, its own condition.

What if the same person writes again?

The contact is found by email address and reused, and a new ticket is created for the new entry.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr