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.

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:

1. Zendesk detects new ticket activity and fires a trigger
2. Zendesk webhook sends ticket data to your Vercel App
3. Vercel app calls the Inkeep API to generate an AI response
4. Inkeep API returns the AI response to Vercel
5. 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:

1. 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.

1. Create an environment file by copying the sample:

cp .env.sample .env

2. Edit the .env file with your actual values:

Required variables:

• ZENDESK_SUBDOMAIN: Your Zendesk subdomain (e.g., if your Zendesk URL is mycompany.zendesk.com, enter 'mycompany')
• ZENDESK_API_TOKEN: Generate at Zendesk API token docs
• ZENDESK_API_USER: Email address of your Zendesk user
• ZENDESK_WEBHOOK_SECRET: A secret key for webhook security docs
• AI_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:

• AI_AGENT_USER_ID: The User ID you'd like the AI bot to have if leaving internal comments
• ENABLE_PUBLIC_RESPONSES: Set to true to make AI responses visible to customers (defaults to false where all responses are internal comments)

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.sh

Problem: The setup script runs but no webhook appears in Zendesk.

Possible causes:

1. Missing environment variables - Ensure all required variables are set in your .env file
2. Invalid API credentials - Verify your ZENDESK_API_USER and ZENDESK_API_TOKEN are correct
3. Wrong subdomain - Double-check your ZENDESK_SUBDOMAIN value
4. Incorrect endpoint URL - Ensure AI_PROCESSING_ENDPOINT is 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:

1. Manually deactivate them in Zendesk:

   • Visit https://YOUR-SUBDOMAIN.zendesk.com/admin/objects-rules/rules/triggers
   • Replace YOUR-SUBDOMAIN with your Zendesk subdomain

2. Or run the cleanup script to remove the trigger/webhook pair:

chmod +x ./webhook_setup/cleanup.sh
./webhook_setup/cleanup.sh

By 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:

1. Set the environment variable: ENABLE_PUBLIC_RESPONSES=true
2. 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.