Zendesk Connector
Ingest Zendesk tickets, comments, and help-center articles into CortexDB.
Tails Zendesk tickets (and their comments) and Help Center articles, and writes them to CortexDB as experiences.
Two ways to run this connector
Self-hosted — pip install 'cortexdb-connectors[zendesk]' then cortexdb-sync sync zendesk.
Managed — CortexDB runs the connector as a worker. See the Connectors overview.
1. Prepare credentials
Zendesk → Admin Center → Apps and integrations → Zendesk API → enable token access and create an API
token. The connector authenticates as HTTP Basic (email/token:<token>). You also need your Zendesk
subdomain (e.g. acme for acme.zendesk.com).
What gets written
Each ticket, ticket comment (as a conversation), and Help Center article (as a document) becomes a
POST /v1/experience on the resolved scope (default org:<org>/source:zendesk), with an entity
reference and metadata (status, priority, a source_url).
Idempotency key
The internal idempotency_key is zd:ticket:<id> for tickets and the raw article:<id> for Help
Center articles (zd:article:<id> is the article's thread id). This connector does not use
context.preceded_by.
The key on the wire is derived
The key format above is this connector's internal record identity: it decides which source record an
event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value
that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on
the same event while any edit lands as a new one, even where the key format itself is not
content-versioned. Every event also carries a source descriptor with the record's fingerprint. See
Source identity and keys.
Run it yourself
pip install 'cortexdb-connectors[zendesk]'
pip install cortexdb-cli && cortexdb init
export ZENDESK_SUBDOMAIN=acme # required
export ZENDESK_EMAIL=you@acme.com # required
export ZENDESK_TOKEN=... # required (API token)
cortexdb-sync --api-url http://localhost:3141 sync zendesk
cortexdb-sync --api-url http://localhost:3141 watch zendesk --interval 300Optional settings
Set these as environment variables (or the matching keys in the cortexdb-sync YAML config). Lists are comma-separated. For on/off settings, 1, true, yes or on turns the setting on and any other value turns it off.
| Setting | What it does | Default |
|---|---|---|
ZENDESK_HELP_CENTER | Also sync Help Center articles | Off |