@rawdash/connector-zendesk 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +145 -0
- package/dist/index.d.ts +609 -0
- package/dist/index.js +696 -0
- package/dist/index.js.map +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
<!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
|
|
2
|
+
|
|
3
|
+
# @rawdash/connector-zendesk
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@rawdash/connector-zendesk)
|
|
6
|
+
[](https://github.com/rawdash/rawdash/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Sync tickets, ticket state-change events, satisfaction ratings, users, and groups from Zendesk Support for queue depth, response time, and CSAT analytics.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @rawdash/connector-zendesk
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Authentication
|
|
17
|
+
|
|
18
|
+
HTTP Basic auth using an agent (or admin) email address paired with a Zendesk API token. The token must belong to an account with read access to tickets, users, and groups.
|
|
19
|
+
|
|
20
|
+
1. Open Admin Center -> Apps and integrations -> Zendesk API.
|
|
21
|
+
2. On the Settings tab, enable Token access if it is not already on.
|
|
22
|
+
3. Click Add API token, give it a label, and copy the generated token value (you cannot view it again).
|
|
23
|
+
4. Store the token as a secret and reference it from config as `apiToken: secret("ZENDESK_API_TOKEN")`, alongside the agent email and your account subdomain (the "acme" in acme.zendesk.com).
|
|
24
|
+
|
|
25
|
+
## Configuration
|
|
26
|
+
|
|
27
|
+
| Field | Type | Required | Description |
|
|
28
|
+
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
29
|
+
| `subdomain` | string | Yes | Your Zendesk account subdomain, the "acme" in acme.zendesk.com. |
|
|
30
|
+
| `email` | string | Yes | Email address of an agent (or admin) on the Zendesk account; paired with the API token for Basic auth. |
|
|
31
|
+
| `apiToken` | secret | Yes | Zendesk API token. Create one in Admin Center -> Apps and integrations -> Zendesk API -> Settings -> Add API token. |
|
|
32
|
+
| `resources` | array | No | Which Zendesk resources to sync. Omit to sync all of them. The API token only needs read scopes for the resources listed here. |
|
|
33
|
+
|
|
34
|
+
## Resources
|
|
35
|
+
|
|
36
|
+
- **`zendesk_user`** _(entity)_ - Zendesk users (agents, admins, and end-users) with role and activity flags.
|
|
37
|
+
- Endpoint: `GET /api/v2/users.json`
|
|
38
|
+
- `name`: User display name.
|
|
39
|
+
- `email`: User email address.
|
|
40
|
+
- `role`: User role (end-user, agent, or admin).
|
|
41
|
+
- `active`: Whether the user is active.
|
|
42
|
+
- `suspended`: Whether the user is suspended.
|
|
43
|
+
- `defaultGroupId`: Default group the user belongs to (agents only).
|
|
44
|
+
- `createdAt`: When the user was created (Unix ms).
|
|
45
|
+
- **`zendesk_group`** _(entity)_ - Agent groups used to route tickets.
|
|
46
|
+
- Endpoint: `GET /api/v2/groups.json`
|
|
47
|
+
- `name`: Group name.
|
|
48
|
+
- `isDefault`: Whether this is the account default group.
|
|
49
|
+
- `deleted`: Whether the group is soft-deleted.
|
|
50
|
+
- `createdAt`: When the group was created (Unix ms).
|
|
51
|
+
- **`zendesk_ticket`** _(entity)_ - Tickets with status, priority, assignment, channel, and tags.
|
|
52
|
+
- Endpoint: `GET /api/v2/incremental/tickets/cursor.json`
|
|
53
|
+
- `subject`: Ticket subject line.
|
|
54
|
+
- `status`: Ticket status (new, open, pending, hold, solved, closed).
|
|
55
|
+
- `priority`: Ticket priority (low, normal, high, urgent).
|
|
56
|
+
- `type`: Ticket type (question, incident, etc.).
|
|
57
|
+
- `channel`: Channel the ticket was created from (email, web, etc.).
|
|
58
|
+
- `assigneeId`: Assigned agent id (null if unassigned).
|
|
59
|
+
- `requesterId`: Requester (end-user) id.
|
|
60
|
+
- `groupId`: Group the ticket is routed to (null if unrouted).
|
|
61
|
+
- `organizationId`: Organization id (null if none).
|
|
62
|
+
- `tags`: Flat list of tags applied to the ticket.
|
|
63
|
+
- `satisfactionScore`: Per-ticket CSAT score from the satisfaction_rating block (offered, good, bad, unoffered).
|
|
64
|
+
- `createdAt`: When the ticket was created (Unix ms).
|
|
65
|
+
- **`zendesk_ticket_state_change`** _(event)_ - Ticket state-change events (created / solved) derived from each ticket.
|
|
66
|
+
- Endpoint: `GET /api/v2/incremental/tickets/cursor.json`
|
|
67
|
+
- Derived from each ticket’s timestamps; the scope is cleared and rewritten on every sync.
|
|
68
|
+
- `ticketId`: The ticket the event belongs to.
|
|
69
|
+
- `transition`: created or solved.
|
|
70
|
+
- `status`: Ticket status at sync time.
|
|
71
|
+
- `priority`: Ticket priority at sync time.
|
|
72
|
+
- `assigneeId`: Assigned agent id at sync time (null if unassigned).
|
|
73
|
+
- `groupId`: Group id at sync time (null if unrouted).
|
|
74
|
+
- `channel`: Channel the ticket was created from.
|
|
75
|
+
- **`zendesk_satisfaction_rating`** _(entity)_ - Per-ticket customer satisfaction (CSAT) ratings with score and free-text comment.
|
|
76
|
+
- Endpoint: `GET /api/v2/satisfaction_ratings.json`
|
|
77
|
+
- `score`: Rating score (good, bad, offered).
|
|
78
|
+
- `ticketId`: The ticket the rating is for.
|
|
79
|
+
- `assigneeId`: Agent assigned at the time of rating.
|
|
80
|
+
- `requesterId`: Requester (end-user) id.
|
|
81
|
+
- `groupId`: Group id at the time of rating.
|
|
82
|
+
- `hasComment`: Whether a free-text comment is set.
|
|
83
|
+
- `createdAt`: When the rating was submitted (Unix ms).
|
|
84
|
+
|
|
85
|
+
## Example
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
import {
|
|
89
|
+
defineConfig,
|
|
90
|
+
defineDashboard,
|
|
91
|
+
defineMetric,
|
|
92
|
+
secret,
|
|
93
|
+
} from '@rawdash/core';
|
|
94
|
+
|
|
95
|
+
const zendesk = {
|
|
96
|
+
name: 'zendesk',
|
|
97
|
+
connectorId: 'zendesk',
|
|
98
|
+
config: {
|
|
99
|
+
subdomain: 'acme',
|
|
100
|
+
email: 'agent@acme.com',
|
|
101
|
+
apiToken: secret('ZENDESK_API_TOKEN'),
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
export default defineConfig({
|
|
106
|
+
connectors: [zendesk],
|
|
107
|
+
dashboards: {
|
|
108
|
+
support: defineDashboard({
|
|
109
|
+
widgets: {
|
|
110
|
+
open_tickets: {
|
|
111
|
+
kind: 'stat',
|
|
112
|
+
title: 'Open tickets',
|
|
113
|
+
metric: defineMetric({
|
|
114
|
+
connector: zendesk,
|
|
115
|
+
shape: 'entity',
|
|
116
|
+
entityType: 'zendesk_ticket',
|
|
117
|
+
fn: 'count',
|
|
118
|
+
filter: [{ field: 'status', op: 'eq', value: 'open' }],
|
|
119
|
+
}),
|
|
120
|
+
},
|
|
121
|
+
},
|
|
122
|
+
}),
|
|
123
|
+
},
|
|
124
|
+
});
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Rate limits
|
|
128
|
+
|
|
129
|
+
Zendesk Support API enforces per-account quotas (default ~700 requests/minute on Professional plans, higher on Enterprise) and signals throttling via 429 with a Retry-After header; the shared HTTP client honors Retry-After on backoff.
|
|
130
|
+
|
|
131
|
+
## Limitations
|
|
132
|
+
|
|
133
|
+
- Ticket comment bodies and per-event audit transcripts are not synced.
|
|
134
|
+
- Zendesk Chat, Talk (voice), and Sell are separate product lines and are out of scope.
|
|
135
|
+
- Ticket state-change events are derived from each ticket’s timestamps (created, updated, solved); full audit-event history is not synced.
|
|
136
|
+
|
|
137
|
+
## Links
|
|
138
|
+
|
|
139
|
+
- [Rawdash docs](https://rawdash.dev/docs/connectors/)
|
|
140
|
+
- [Zendesk API docs](https://developer.zendesk.com/api-reference/ticketing/introduction/)
|
|
141
|
+
- [GitHub](https://github.com/rawdash/rawdash)
|
|
142
|
+
|
|
143
|
+
## License
|
|
144
|
+
|
|
145
|
+
Apache-2.0
|