TicketFu

TicketFu is an AI-powered support ticket analysis system that integrates with Zendesk to provide enhanced ticket management capabilities.

Built on Temporal for reliable, durable workflow execution, it uses modern LLMs (OpenAI, Google Gemini, or Anthropic) to generate ticket summaries and organization-level insights, making it easier for support teams to manage customer issues efficiently.

Features

• AI-Powered Ticket Analysis: Automatically generates concise summaries of support tickets
• Organization-Level Insights: Synthesizes organization-wide patterns and trends based on all ticket activity
• Reliable Workflow Processing: Uses Temporal for durable, reliable background processing
• Multiple LLM Support: Compatible with OpenAI, Google Gemini, and Anthropic models

Why Temporal?

Temporal's durable execution is helpful for:

• Storing entity state (tickets, organizations) without a database
• Idempotent provisioning of Zendesk webhooks and triggers
• Caching expensive API call results (like LLM summaries)
• Resilience against transient service disruptions
• Built-in visibility into workflow status and history
• Code reads like synchronous execution but is fully durable

Cloud Deployment

One-Click Deployment on Render

The easiest way to get started in production is with Render's one-click deploy:

Expand to see the prerequisites and setup steps

Prerequisites

1. Zendesk Account
   TicketFu integrates with Zendesk to fetch and analyze support tickets. If you don't have a Zendesk account, you can sign up for a free trial.

2. Render Account
   For easy cloud deployment, create a Render account.

3. Temporal Cloud Account
   For production deployments, we recommend using Temporal Cloud. You can sign up for Temporal Cloud here.

4. LLM API Access
   You'll need an API key from one of the supported LLM providers:

   • OpenAI API
   • Google AI (Gemini) API
   • Anthropic API

Render Environment Variables

After deploying with the one-click button, you'll need to configure these environment variables in your Render dashboard:

• TEMPORAL_NAMESPACE: Namespace for Temporal workflows. If using Temporal Cloud, this will be in the format <namespace>.<account_id> (default: default)

• TEMPORAL_ADDRESS: Address of your Temporal server. If using Temporal Cloud, the format will be <region>.<cloud_provider>.api.temporal.io:7233 (you can copy this from your Temporal Cloud namespace settings page). For local development, use localhost:7233

• TEMPORAL_API_KEY: API key for Temporal Cloud (if using Temporal Cloud)

• ZENDESK_SUBDOMAIN: Your Zendesk subdomain

• ZENDESK_EMAIL: Your Zendesk admin email

• ZENDESK_TOKEN: Your Zendesk API token (how to generate)

• LLM_PROVIDER: Your preferred provider (openai, googleai, or anthropic)

• LLM_MODEL: The model to use (e.g., gpt-4o-mini for OpenAI)

• LLM_API_KEY: Your LLM provider's API key

Additional env vars:

• LOG_LEVEL: Set to debug for development or info for production (default: debug)
• SERVER_API_TOKEN: API token for authenticating requests from Zendesk to your TicketFu server (auto-generated by default)

All these variables are defined in the render.yaml file and will be prompted during deployment. Once deployed, note the service URL as you'll need it when configuring your Zendesk app.

Installing the Zendesk App After Deployment

After deploying TicketFu on Render, follow these steps to install the Zendesk app:

1. Copy Your API Token

   • Go to your Render dashboard
   • Navigate to your TicketFu service
   • Click on "Environment" in the left menu
   • Find and copy the auto-generated SERVER_API_TOKEN value

2. Download the Zendesk app from here

3. Or Package the App locally

   cd zendesk_app
   npm run build
   cd dist && zip -r ticketfu.zip *

4. Upload to Zendesk

   • In Zendesk, go to Admin Center > Apps and integrations > Zendesk Support apps
   • Click Upload private app
   • Give the app a name, e.g. TicketFu
   • Upload the ticketfu.zip file

5. Configure the App When prompted, enter the following settings:

   • API Token: Your TicketFu server API token. (Copy from SERVER_API_TOKEN when using Render)
   • Server URL: The URL where your TicketFu server is deployed (e.g., https://ticketfu-abc123.onrender.com)
   • Click Install

The app will now appear in your Zendesk Support interface when viewing tickets and organizations.

Configuring Zendesk Webhooks and Triggers

There are two ways to set up Zendesk webhooks and triggers for TicketFu:

Option 1: Use the Auto-Provisioning Workflow (Recommended)

TicketFu includes a built-in workflow that can automatically create the necessary Zendesk webhook and trigger for you:

1. Configure the Webhook Base URL:

   • Set the ZENDESK_WEBHOOK_BASE_URL environment variable to your TicketFu server URL (e.g., https://ticketfu-abc123.onrender.com)
   • If using Render, add this variable in your service's Environment tab

2. Start the Server:

   • Updating env var on Render will trigger a server restart, which invokes the webhook workflow
   • The workflow will:
     • Create a webhook named "TicketFu Webhook" pointing to your /api/v1/ticket endpoint
     • Configure the webhook with the proper API key authentication
     • Create a trigger that fires the webhook when tickets are created or updated
   • This process is idempotent - it will only create resources if they don't already exist

3. Verify Setup:

   • In Zendesk, go to Admin Center > Apps and integrations > Webhooks
   • You should see "TicketFu Webhook" in the list
   • Go to Admin Center > Objects and rules > Triggers
   • You should see "Notify TicketFu" in the list

Option 2: Manual Configuration

If you prefer to set up the webhook and trigger manually:

1. Create a Webhook Target:

   • In Zendesk, go to Admin Center > Apps and integrations > Webhooks
   • Click Create webhook
   • Choose Trigger or automation then click on Next
   • Set the following:
     • Name: TicketFu Ticket Update
     • Endpoint URL: https://<e.g. https://ticketfu-abc123.onrender.com>/api/v1/ticket
     • Request method: POST
     • Request format: JSON
   • Choose None for Authentication
   • Add the following HTTP headers:
     • Header name: X-Ticketfu-Key
     • Value: <SERVER_API_TOKEN> (You can find it from Render's Environment tab)
   • Click Create webhook
   • Follow the Admin Center link from "Select a trigger or automation in Admin Center"

2. Create a Trigger:

   • Go to Admin Center > Objects and rules > Triggers
   • Click Create trigger
   • Configure basic information:
     • Title: TicketFu Analysis
     • Category: Notifications
   • Set the conditions:
     • Meet any of these conditions:
       • Ticket: Is Updated
   • Set the actions:
   • Click Add action
   • Notify by: Select Active webhook, then choose the newly created "TicketFu Ticket Update" webhook.
   • Add below JSON body:

     {
       "ticket_url": "{{ticket.url}}"
     }

   • Click Create trigger
   • Finalize the Webhook creation in the previous tab by clicking Finish setup

Debugging and Monitoring

Accessing Temporal Workflow History

Temporal provides detailed execution history for every workflow, which is invaluable for troubleshooting:

1. Temporal Cloud UI

   • Log in to your Temporal Cloud account at https://cloud.temporal.io
   • Navigate to your namespace (format: <namespace>.<account_id>)
   • Click on "Workflows" in the left sidebar
   • Use the search filters to find workflows by:
     • ID Pattern: Use ticket-workflow- or organization-workflow- prefix
     • Status: Running, Completed, Failed, etc.

2. Viewing Workflow Details in Cloud UI

   • Click on a workflow ID to see its visualization and detailed view
   • The "History" tab shows each event with timestamps and results. For example, Zendesk webhooks are recorded as "Workflow Execution Signaled" events with name: upsert-ticket-signal.
   • Use the "Query" tab to inspect the ticket's summary via the query-ticket-summary query type.

Architecture

TicketFu is built with a modular architecture that consists of two main components:

1. Server Component:

   • Handles HTTP requests via RESTful API endpoints
   • Manages authentication and authorization via API tokens
   • Communicates with Temporal for workflow orchestration
   • Provides health check and monitoring endpoints

2. Worker Component:

   • Processes tickets and organizations in background workflows
   • Fetches ticket data from Zendesk API
   • Generates AI summaries using configured LLM providers
   • Maintains ticket and organization state using Temporal workflows

Architecture Diagram

graph TB
    subgraph "Temporal Worker"
        TicketWorkflow[Ticket Workflow]
        OrgWorkflow[Organization Workflow]
    end

    subgraph "Zendesk"
        ZendeskWebhooks[Zendesk Webhooks]
        ZendeskApp[Zendesk App]
        ZendeskAPI[Zendesk API]
    end
    
    LLM["LLM API: ChatGPT, Gemini or Claude"]
    TemporalCloud[Temporal Cloud]
    
    %% Flow with numbered sequence
    ZendeskWebhooks -->|"(1) Trigger workflow"| TicketWorkflow
    TicketWorkflow -->|"(2) Fetch data"| ZendeskAPI
    TicketWorkflow -->|"(3) Generate summaries"| LLM
    TicketWorkflow -->|"(4) Update org data (Workflow Signal)"| OrgWorkflow
    OrgWorkflow -->|"(5) Generate insights"| LLM
    ZendeskApp -->|"(6) Fetch summary (Workflow Query)"| TicketWorkflow
    ZendeskApp -->|"(7) Fetch summary (Workflow Query)"| OrgWorkflow
    
    %% Temporal orchestration
    TemporalCloud -.->|Orchestrate| TicketWorkflow
    TemporalCloud -.->|Orchestrate| OrgWorkflow

Loading

Workflow Architecture

TicketFu uses Temporal for workflow orchestration, implementing the "Entity Workflow" pattern:

• Each entity (ticket or organization) has its own long-running workflow instance
• The workflow maintains the entity's state and handles all operations for that entity
• External events trigger operations via signals
• Queries allow reading the current state without interrupting workflow execution

API Endpoints

TicketFu exposes the following RESTful API endpoints:

• GET /health: Health check endpoint
• POST /api/v1/ticket: Process a new ticket or update an existing one
• GET /api/v1/ticket/{ticketId}/summary: Get a specific ticket's AI-generated summary
• GET /api/v1/organization/{orgId}/summary: Get organization-level insights and analysis

All API requests require the X-Ticketfu-Key header with your SERVER_API_TOKEN value. When you install the Zendesk app, you'll configure it to use this same token to authenticate requests to your TicketFu server.

Running it locally

Installation

go install github.com/taonic/ticketfu/cmd/ticketfu@latest

Usage

Starting the Server

ticketfu server start \
  --server-api-token YOUR_API_TOKEN \
  --temporal-address localhost:7233

Starting a Worker

ticketfu worker start \
  --zendesk-subdomain your-zendesk \
  --zendesk-email [email protected] \
  --zendesk-token YOUR_ZENDESK_TOKEN \
  --llm-provider openai \
  --llm-model gpt-4o-mini \
  --llm-api-key YOUR_LLM_API_KEY \
  --temporal-address localhost:7233

Expand to see more config options

Server Configuration

Parameter	Environment Variable	Description	Default
--host	HOST	Server host address	"0.0.0.0"
--port	PORT	Server port	8080
--server-api-token	SERVER_API_TOKEN	API token for request authentication	(required)

Worker Configuration

Parameter	Environment Variable	Description	Default
--queue	WORKER_QUEUE	Worker queue name	"default"

Zendesk Configuration

Parameter	Environment Variable	Description	Default
--zendesk-subdomain	ZENDESK_SUBDOMAIN	Zendesk subdomain	(required)
--zendesk-email	ZENDESK_EMAIL	Zendesk email	(required)
--zendesk-token	ZENDESK_TOKEN	Zendesk API token	(required)

LLM Configuration

Parameter	Environment Variable	Description	Default
--llm-provider	LLM_PROVIDER	LLM provider (openai, googleai, anthropic)	"openai"
--llm-model	LLM_MODEL	LLM model name	"gpt-4o-mini"
--llm-api-key	LLM_API_KEY	LLM API key	(required)
--ticket-summary-prompt	TICKET_SUMMARY_PROMPT	Prompt for ticket summary generation	(default prompt)
--org-summary-prompt	ORG_SUMMARY_PROMPT	Prompt for organization summary generation	(default prompt)

Temporal Configuration

Parameter	Environment Variable	Description	Default
--temporal-address	TEMPORAL_ADDRESS	Temporal service address	"127.0.0.1:7233"
--temporal-namespace	TEMPORAL_NAMESPACE	Temporal namespace	"default"
--temporal-api-key	TEMPORAL_API_KEY	Temporal API key	(optional)
--temporal-tls-cert	TEMPORAL_TLS_CERT	Path to Temporal TLS certificate	(optional)
--temporal-tls-key	TEMPORAL_TLS_KEY	Path to Temporal TLS key	(optional)

Local Development

Expand to see local deployment setup

Prerequisites

• Go 1.23 or higher
• Temporal server (for workflow orchestration)
• API key for one of the supported LLM providers

For development or testing, you can run TicketFu locally:

1. Clone the Repository

   git clone https://github.com/taonic/ticketfu.git
   cd ticketfu

2. Set Up Temporal Locally

   # Install Temporal CLI
   curl -sSf https://temporal.download/cli.sh | sh
   
   # Start Temporal Server in dev mode
   temporal server start-dev

3. Build TicketFu

   go build -o ticketfu cmd/ticketfu/main.go

4. Run the Server

   ./ticketfu server start \
     --server-api-token YOUR_API_TOKEN \
     --temporal-address localhost:7233

5. Run the Worker (in a separate terminal)

   ./ticketfu worker start \
     --zendesk-subdomain your-zendesk \
     --zendesk-email [email protected] \
     --zendesk-token YOUR_ZENDESK_TOKEN \
     --llm-provider openai \
     --llm-model gpt-4o-mini \
     --llm-api-key YOUR_LLM_API_KEY \
     --temporal-address localhost:7233

6. Test the API

   curl -H "X-Ticketfu-Key: YOUR_API_TOKEN" http://localhost:8080/health

Running Tests

go test ./...

Local Zendesk App Development

For testing the Zendesk app locally, you can use the Zendesk CLI:

1. Install Zendesk CLI

   npm install -g @zendesk/zcli

2. Login to Zendesk

   zcli login

3. Navigate to the Zendesk App Directory

   cd zendesk_app

4. Start the Local App Server

   zcli apps:server

5. Test the App in Zendesk

   • Go to your Zendesk Support instance in your browser
   • Append ?zcli_apps=true to the URL
   • The locally running app will now appear in the sidebar

This setup allows you to develop and test changes to the Zendesk app without having to constantly repackage and upload it to your Zendesk instance.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT