0
# Airbyte Source Zendesk Chat
1
2
An Airbyte source connector for extracting data from Zendesk Chat API endpoints. This is a manifest-only declarative connector that extracts chat data including agents, conversations, bans, and configuration settings from Zendesk Chat accounts.
3
4
## Package Information
5
6
- **Package Name**: airbyte/source-zendesk-chat
7
- **Package Type**: Docker Container (Airbyte Source Connector)
8
- **Language**: YAML (declarative manifest) + Python (custom components)
9
- **Installation**: `docker pull airbyte/source-zendesk-chat:1.2.16`
10
11
## Core Imports
12
13
This connector is accessed via Docker commands and Airbyte's connector protocol:
14
15
```bash
16
# Pull the Docker image
17
docker pull airbyte/source-zendesk-chat:1.2.16
18
19
# Use with local Docker
20
docker run airbyte/source-zendesk-chat:1.2.16 <command> [options]
21
```
22
23
## Basic Usage
24
25
```bash
26
# 1. Create configuration file
27
cat > config.json << EOF
28
{
29
"start_date": "2021-01-01T00:00:00Z",
30
"subdomain": "mycompany",
31
"credentials": {
32
"credentials": "access_token",
33
"access_token": "your-zendesk-chat-access-token"
34
}
35
}
36
EOF
37
38
# 2. View connector specification
39
docker run airbyte/source-zendesk-chat:1.2.16 spec
40
41
# 3. Test connection
42
docker run -v $(pwd):/config airbyte/source-zendesk-chat:1.2.16 check --config /config/config.json
43
44
# 4. Discover available streams
45
docker run -v $(pwd):/config airbyte/source-zendesk-chat:1.2.16 discover --config /config/config.json
46
47
# 5. Sync data
48
docker run -v $(pwd):/config airbyte/source-zendesk-chat:1.2.16 read \
49
--config /config/config.json \
50
--catalog /config/catalog.json
51
```
52
53
## Architecture
54
55
This connector uses Airbyte's Declarative Manifest framework:
56
57
- **Manifest Configuration** (`manifest.yaml`): Defines API endpoints, authentication, pagination, and data extraction rules
58
- **Custom Python Components** (`components.py`): Handles specialized data processing for complex API responses
59
- **Docker Container**: Runs within `source-declarative-manifest` base image
60
- **Base URL Pattern**: `https://{subdomain}.zendesk.com/api/v2/chat/`
61
62
The connector supports both full refresh and incremental synchronization modes depending on the stream, with automatic retry handling and rate limiting compliance.
63
64
## Capabilities
65
66
### Docker Commands
67
68
The core API for interacting with this connector through standard Airbyte connector protocol commands.
69
70
```bash { .api }
71
# Get connector specification
72
docker run airbyte/source-zendesk-chat:1.2.16 spec
73
74
# Check connection configuration
75
docker run -v /path/to/config:/config airbyte/source-zendesk-chat:1.2.16 check \
76
--config /config/config.json
77
78
# Discover available streams
79
docker run -v /path/to/config:/config airbyte/source-zendesk-chat:1.2.16 discover \
80
--config /config/config.json
81
82
# Read data from streams
83
docker run -v /path/to/config:/config airbyte/source-zendesk-chat:1.2.16 read \
84
--config /config/config.json \
85
--catalog /config/catalog.json \
86
[--state /config/state.json]
87
```
88
89
[Configuration](./configuration.md)
90
91
### Configuration Schema
92
93
The JSON configuration schema supported by the connector, based on the manifest specification.
94
95
```json { .api }
96
{
97
"type": "object",
98
"properties": {
99
"start_date": {
100
"type": "string",
101
"format": "date-time",
102
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
103
"description": "The date from which to replicate data (YYYY-MM-DDTHH:MM:SSZ)",
104
"examples": ["2021-02-01T00:00:00Z"]
105
},
106
"subdomain": {
107
"type": "string",
108
"pattern": "^(?!https://)",
109
"description": "Zendesk account subdomain (without https://)",
110
"examples": ["myzendeskchat"]
111
},
112
"credentials": {
113
"oneOf": [
114
{
115
"type": "object",
116
"properties": {
117
"credentials": {"const": "oauth2.0"},
118
"client_id": {"type": "string"},
119
"client_secret": {"type": "string"},
120
"access_token": {"type": "string"},
121
"refresh_token": {"type": "string"}
122
}
123
},
124
{
125
"type": "object",
126
"properties": {
127
"credentials": {"const": "access_token"},
128
"access_token": {"type": "string"}
129
}
130
}
131
]
132
}
133
},
134
"required": ["start_date", "subdomain"]
135
}
136
```
137
138
### Available Streams
139
140
Twelve data streams available for extraction, each with specific sync modes and API endpoints.
141
142
```yaml { .api }
143
# Stream definitions from manifest.yaml
144
streams:
145
accounts: # /account (full_refresh only)
146
agents: # /agents (full_refresh, incremental)
147
agent_timeline: # /incremental/agent_timeline (full_refresh, incremental)
148
bans: # /bans (full_refresh, incremental) - uses custom extractor
149
chats: # /incremental/chats (full_refresh, incremental)
150
departments: # /departments (full_refresh only)
151
goals: # /goals (full_refresh only)
152
roles: # /roles (full_refresh only)
153
routing_settings: # /routing_settings/account (full_refresh only)
154
shortcuts: # /shortcuts (full_refresh only)
155
skills: # /skills (full_refresh only)
156
triggers: # /triggers (full_refresh only)
157
```
158
159
[Data Streams](./streams.md)
160
161
### Custom Record Processing
162
163
Python components for specialized data extraction and transformation of API responses.
164
165
```python { .api }
166
class ZendeskChatBansRecordExtractor(RecordExtractor):
167
def extract_records(
168
self,
169
response: requests.Response
170
) -> Iterable[Mapping[str, Any]]:
171
# Processes bans data by unnesting visitor and ip_address fields
172
# Combines ip_address and visitor arrays, sorts by created_at
173
...
174
```
175
176
[Custom Components](./components.md)
177
178
## Types
179
180
```json { .api }
181
// Core Airbyte protocol types
182
{
183
"AirbyteMessage": {
184
"type": "object",
185
"properties": {
186
"type": {"enum": ["RECORD", "STATE", "LOG", "SPEC", "CONNECTION_STATUS", "CATALOG"]},
187
"record": {"$ref": "#/AirbyteRecordMessage"},
188
"state": {"$ref": "#/AirbyteStateMessage"},
189
"log": {"$ref": "#/AirbyteLogMessage"}
190
}
191
},
192
"ConfiguredCatalog": {
193
"type": "object",
194
"properties": {
195
"streams": {
196
"type": "array",
197
"items": {"$ref": "#/ConfiguredAirbyteStream"}
198
}
199
}
200
},
201
"SyncMode": {"enum": ["full_refresh", "incremental"]},
202
"DestinationSyncMode": {"enum": ["overwrite", "append", "append_dedup"]}
203
}
204
```