> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk plugin

# Zendesk Plugin for Savant

A standalone A2A agent that bridges Zendesk ticket events into the Savant mesh and exposes Zendesk operations as tools for other agents.

## What It Does

* **Listens** to Zendesk webhooks (`ticket.created`, `ticket.updated`, `ticket.status_changed`, `ticket.escalated`) and polls the Zendesk Incremental API as a fallback
* **Transforms** ticket events into structured Savant cues routed to the mesh
* **Exposes** 8 Zendesk tools (get ticket, create ticket, update ticket, add comment, search, list, get user, apply macro) callable by any agent on the mesh

## Architecture

```mermaid theme={null}
flowchart LR
	Z["Zendesk<br/>(external)"] -->|webhook POST| P["Zendesk Plugin<br/>(A2A Agent)"] --> M["Svantic Mesh"]
```

The plugin is built with `@svantic/sdk` and connects via `MeshConnector`. It registers as a remote agent on the mesh, visible in the dashboard Agents page.

## Deployment

```bash theme={null}
ZENDESK_SUBDOMAIN=acme \
ZENDESK_EMAIL=bot@acme.com \
ZENDESK_API_TOKEN=xxxxxxxx \
ZENDESK_WEBHOOK_SECRET=whsec_xxxxxxxx \
SAVANT_MESH_URL=http://savant-mesh:3000 \
SAVANT_CLIENT_ID=your-client-id \
SAVANT_CLIENT_SECRET=your-client-secret \
node dist/index.js
```

## settings.json

```json theme={null}
{
    "plugin": "savant-zendesk-plugin",
    "version": "1.0.0",
    "agent": {
        "name": "savant-zendesk-plugin",
        "description": "Bridges Zendesk ticket events into the Savant mesh.",
        "port": 4100,
        "agent_type": "zendesk-plugin"
    },
    "mesh": {
        "url": "http://localhost:3000",
        "tenant_id": "acme",
        "tenant_secret": "${SAVANT_TENANT_SECRET}"
    },
    "zendesk": {
        "subdomain": "${ZENDESK_SUBDOMAIN}",
        "email": "${ZENDESK_EMAIL}",
        "api_token": "${ZENDESK_API_TOKEN}",
        "webhook_secret": "${ZENDESK_WEBHOOK_SECRET}"
    },
    "event_ingestion": {
        "webhook_path": "/webhooks/zendesk",
        "polling_enabled": true,
        "polling_interval_seconds": 60
    },
    "routing_rules": [
        {
            "match": { "priority": ["urgent", "high"] },
            "action": { "auto_execute": true, "cue_priority": "high" }
        },
        {
            "match": { "tags_include": ["escalated"] },
            "action": { "requires_human": true, "cue_priority": "high" }
        },
        {
            "match": { "event_type": "ticket.status_changed", "status": ["solved", "closed"] },
            "action": { "log_only": true }
        }
    ],
    "tools": {
        "enabled": [
            "zendesk_get_ticket",
            "zendesk_list_tickets",
            "zendesk_create_ticket",
            "zendesk_update_ticket",
            "zendesk_add_comment",
            "zendesk_search",
            "zendesk_get_user",
            "zendesk_macro_apply"
        ]
    }
}
```

## Tools

| Tool                    | Description                             |
| ----------------------- | --------------------------------------- |
| `zendesk_get_ticket`    | Fetch full ticket details with comments |
| `zendesk_list_tickets`  | Search/list tickets with filters        |
| `zendesk_create_ticket` | Create a new ticket                     |
| `zendesk_update_ticket` | Update ticket fields                    |
| `zendesk_add_comment`   | Add a public or internal note           |
| `zendesk_search`        | Full-text search across tickets         |
| `zendesk_get_user`      | Look up a Zendesk user                  |
| `zendesk_macro_apply`   | Apply a predefined macro                |

## End-to-End Example

1. Customer creates high-priority ticket: "Can't log in"
2. Zendesk fires webhook to plugin
3. Plugin transforms to cue, routes to mesh (auto\_execute due to high priority)
4. Planner generates plan: fetch ticket → query KB → draft response → post comment
5. Executor runs plan, calling `zendesk_get_ticket` and `zendesk_add_comment` on the plugin
6. Customer sees the response on their ticket within seconds