This template repo contains a NextJS app as well as bash scripts that will help you configure your Zendesk workspace to use Inkeep to auto-respond to new tickets using your Inkeep project.
Important
This is a only template repo. Given your integration requirements, you will want to make additional changes to this template.
The integration works by connecting three systems:
graph LR
A[Zendesk Ticket Activity] --> B[Zendesk Trigger]
B --> C[Zendesk Webhook]
C --> D[Vercel App]
D --> E[Inkeep API]
E --> D
D --> F[Update Ticket]
F --> A
How it works:
- Zendesk detects new ticket activity and fires a trigger
- Zendesk webhook sends ticket data to your Vercel App
- Vercel app calls the Inkeep API to generate an AI response
- Inkeep API returns the AI response to Vercel
- Vercel App posts the response back to Zendesk as a ticket comment
Follow these steps in order to set up the Zendesk AI Auto Responder:
Note: Zendesk is removing API tokens as an authentication method. Starting July 28, 2026, tokens unused for 30 days will be automatically deleted. By April 30, 2027, all API tokens will stop working. You must migrate your integrations to OAuth access tokens before the final deadline. This change only affects APIs that currently use API tokens including the Ticketing, Help Center, and Voice APIs. It does not apply to other Zendesk products. See Managing API token access to the Zendesk API.
In Zendesk Admin Center, go to Apps and integrations > APIs > OAuth clients and create a confidential OAuth client.
The deployed application requests these least-privilege scopes:
tickets:read tickets:write users:read organizations:read
The local setup scripts manage account configuration and request these scopes:
webhooks:read webhooks:write triggers:read triggers:write
For least privilege, use separate OAuth clients for the deployed runtime and local provisioning scripts. They use the same environment variable names in their respective Vercel and local environments. Store each client secret securely; Zendesk shows it only when the client is created.
- Deploy to Vercel using the button below:
Important: During Vercel deployment, you'll be prompted for environment variables. However, these are only used by the deployed app - you'll still need to configure them locally for the setup script.
- Create an environment file by copying the sample:
cp .env.sample .env- Edit the
.envfile with your actual values:
Required variables:
ZENDESK_SUBDOMAIN: Your Zendesk subdomain (e.g., if your Zendesk URL is mycompany.zendesk.com, enter 'mycompany')ZENDESK_OAUTH_CLIENT_ID: Identifier of your confidential Zendesk OAuth clientZENDESK_OAUTH_CLIENT_SECRET: Secret of your confidential Zendesk OAuth clientZENDESK_WEBHOOK_SECRET: A secret key for webhook security docsAI_PROCESSING_ENDPOINT: Your Vercel deployment URL +/api/webhook(e.g.,https://your-app-name.vercel.app/api/webhook)AUTO_RESPONDER_INKEEP_API_KEY: Your Inkeep API key (you must have an account at https://portal.inkeep.com)
Optional variables:
DISABLE_ANALYTICS: Set totrueto skip all Inkeep analytics logging (defaults tofalse)ZENDESK_API_USER: Deprecated API-token user email, accepted temporarily as an OAuth migration fallbackZENDESK_API_TOKEN: Deprecated API token; must be provided together withZENDESK_API_USERAI_AGENT_USER_ID: The User ID you'd like the AI bot to have if leaving internal commentsENABLE_PUBLIC_RESPONSES: Set totrueto make AI responses visible to customers (defaults tofalsewhere all responses are internal comments)
At the start of each webhook request, the Vercel application gets an OAuth token and uses it for that request's Zendesk API calls. Zendesk OAuth tokens expire after 30 minutes by default, which is longer than the application's 60-second maximum request duration, so the application does not need to store or refresh them. If Zendesk returns a server error while issuing a token, the application retries three times and logs each retry. If token creation still fails and the old API credentials are configured, the application uses them and logs a warning.
The existing webhook and trigger do not need to change.
- Create the OAuth client. Add
ZENDESK_OAUTH_CLIENT_IDandZENDESK_OAUTH_CLIENT_SECRETto Vercel. Keep the old API credentials in Vercel for now, then deploy. - Create a test ticket. Make sure the application adds the expected reply or internal note. Check the Vercel logs. If the old API token was used, you will see
Zendesk OAuth token acquisition failed; using deprecated API-token fallback. - Remove
ZENDESK_API_USERandZENDESK_API_TOKENfrom Vercel and deploy again. Do not revoke the API token in Zendesk yet. This makes it easy to add the old credentials back if something goes wrong. - Create another test ticket. If it works, let the application run normally for a few days and make sure tickets keep getting replies.
- Revoke the old API token in Zendesk.
Install jq (required for the setup script):
- macOS:
brew install jq - Windows: Download from jq website
Run the setup script to create the Zendesk webhook and trigger:
chmod +x ./webhook_setup/setup.sh
./webhook_setup/setup.shProblem: The setup script runs but no webhook appears in Zendesk.
Possible causes:
- Missing environment variables - Ensure all required variables are set in your
.envfile - Invalid OAuth credentials - Verify your OAuth client is confidential and its identifier and secret are correct
- Insufficient OAuth scopes - Verify the local client can request
webhooks:read webhooks:write triggers:read triggers:write - Wrong subdomain - Double-check your
ZENDESK_SUBDOMAINvalue - Incorrect endpoint URL - Ensure
AI_PROCESSING_ENDPOINTis your Vercel URL +/api/webhook
Solution: Check the setup script output for error messages and verify your .env configuration.
If you experience problems with the webhook or trigger:
-
Manually deactivate them in Zendesk:
- Visit
https://YOUR-SUBDOMAIN.zendesk.com/admin/objects-rules/rules/triggers - Replace YOUR-SUBDOMAIN with your Zendesk subdomain
- Visit
-
Or run the cleanup script to remove the trigger/webhook pair:
chmod +x ./webhook_setup/cleanup.sh
./webhook_setup/cleanup.shBy default, the AI Autoresponder runs in debug mode (internal notes only). In this mode, responses will only be visible to your support team as internal notes and not to the end-users.
To enable customer-facing responses:
- Set the environment variable:
ENABLE_PUBLIC_RESPONSES=true - Redeploy the application
When ENABLE_PUBLIC_RESPONSES is not set or is set to any value other than true, the AI Auto Responder will only create internal notes (not visible to end-users) when responding to tickets.