0
# Engagement Streams
1
2
Activity and interaction data streams including calls, emails, meetings, notes, and tasks with associations to CRM entities for comprehensive activity tracking.
3
4
## Capabilities
5
6
### Engagements Calls
7
8
Call engagement records with call details and participant information.
9
10
```yaml { .api }
11
engagements_calls:
12
primary_key: ["id"]
13
cursor_field: "updatedAt"
14
sync_mode: incremental
15
schema:
16
type: object
17
properties:
18
id:
19
type: string
20
description: "Unique call engagement identifier"
21
createdAt:
22
type: string
23
format: date-time
24
description: "Call creation timestamp"
25
updatedAt:
26
type: string
27
format: date-time
28
description: "Last update timestamp"
29
timestamp:
30
type: string
31
format: date-time
32
description: "When the call occurred"
33
type:
34
type: string
35
const: "CALL"
36
description: "Engagement type"
37
ownerId:
38
type: string
39
description: "Owner/creator of the call record"
40
41
# Call-specific metadata
42
metadata:
43
type: object
44
properties:
45
toNumber:
46
type: string
47
description: "Phone number called"
48
fromNumber:
49
type: string
50
description: "Phone number called from"
51
status:
52
type: string
53
description: "Call status (COMPLETED, BUSY, NO_ANSWER, etc.)"
54
duration:
55
type: integer
56
description: "Call duration in milliseconds"
57
disposition:
58
type: string
59
description: "Call outcome/disposition"
60
recordingUrl:
61
type: string
62
description: "URL to call recording if available"
63
64
# Associated entities
65
associations:
66
type: object
67
properties:
68
contactIds:
69
type: array
70
items:
71
type: string
72
description: "Associated contact IDs"
73
companyIds:
74
type: array
75
items:
76
type: string
77
description: "Associated company IDs"
78
dealIds:
79
type: array
80
items:
81
type: string
82
description: "Associated deal IDs"
83
```
84
85
### Engagements Emails
86
87
Email engagement records with email metadata and participant information.
88
89
```yaml { .api }
90
engagements_emails:
91
primary_key: ["id"]
92
cursor_field: "updatedAt"
93
sync_mode: incremental
94
schema:
95
type: object
96
properties:
97
id:
98
type: string
99
description: "Unique email engagement identifier"
100
createdAt:
101
type: string
102
format: date-time
103
description: "Email creation timestamp"
104
updatedAt:
105
type: string
106
format: date-time
107
description: "Last update timestamp"
108
timestamp:
109
type: string
110
format: date-time
111
description: "When the email was sent"
112
type:
113
type: string
114
const: "EMAIL"
115
description: "Engagement type"
116
ownerId:
117
type: string
118
description: "Owner/sender of the email"
119
120
# Email-specific metadata
121
metadata:
122
type: object
123
properties:
124
subject:
125
type: string
126
description: "Email subject line"
127
html:
128
type: string
129
description: "Email HTML content"
130
text:
131
type: string
132
description: "Email plain text content"
133
from:
134
type: object
135
properties:
136
email:
137
type: string
138
format: email
139
firstName:
140
type: string
141
lastName:
142
type: string
143
to:
144
type: array
145
items:
146
type: object
147
properties:
148
email:
149
type: string
150
format: email
151
firstName:
152
type: string
153
lastName:
154
type: string
155
cc:
156
type: array
157
items:
158
type: object
159
properties:
160
email:
161
type: string
162
format: email
163
bcc:
164
type: array
165
items:
166
type: object
167
properties:
168
email:
169
type: string
170
format: email
171
172
# Associated entities
173
associations:
174
type: object
175
properties:
176
contactIds:
177
type: array
178
items:
179
type: string
180
description: "Associated contact IDs"
181
companyIds:
182
type: array
183
items:
184
type: string
185
description: "Associated company IDs"
186
dealIds:
187
type: array
188
items:
189
type: string
190
description: "Associated deal IDs"
191
```
192
193
### Engagements Meetings
194
195
Meeting engagement records with meeting details and attendee information.
196
197
```yaml { .api }
198
engagements_meetings:
199
primary_key: ["id"]
200
cursor_field: "updatedAt"
201
sync_mode: incremental
202
schema:
203
type: object
204
properties:
205
id:
206
type: string
207
description: "Unique meeting engagement identifier"
208
createdAt:
209
type: string
210
format: date-time
211
description: "Meeting creation timestamp"
212
updatedAt:
213
type: string
214
format: date-time
215
description: "Last update timestamp"
216
timestamp:
217
type: string
218
format: date-time
219
description: "Meeting start time"
220
type:
221
type: string
222
const: "MEETING"
223
description: "Engagement type"
224
ownerId:
225
type: string
226
description: "Owner/organizer of the meeting"
227
228
# Meeting-specific metadata
229
metadata:
230
type: object
231
properties:
232
title:
233
type: string
234
description: "Meeting title/subject"
235
body:
236
type: string
237
description: "Meeting description/agenda"
238
startTime:
239
type: string
240
format: date-time
241
description: "Meeting start time"
242
endTime:
243
type: string
244
format: date-time
245
description: "Meeting end time"
246
location:
247
type: string
248
description: "Meeting location"
249
meetingUrl:
250
type: string
251
description: "Meeting URL for virtual meetings"
252
source:
253
type: string
254
description: "Meeting source (INTEGRATION, CRM_UI, etc.)"
255
256
# Associated entities
257
associations:
258
type: object
259
properties:
260
contactIds:
261
type: array
262
items:
263
type: string
264
description: "Associated contact IDs"
265
companyIds:
266
type: array
267
items:
268
type: string
269
description: "Associated company IDs"
270
dealIds:
271
type: array
272
items:
273
type: string
274
description: "Associated deal IDs"
275
```
276
277
### Engagements Notes
278
279
Note engagement records with note content and entity associations.
280
281
```yaml { .api }
282
engagements_notes:
283
primary_key: ["id"]
284
cursor_field: "updatedAt"
285
sync_mode: incremental
286
schema:
287
type: object
288
properties:
289
id:
290
type: string
291
description: "Unique note engagement identifier"
292
createdAt:
293
type: string
294
format: date-time
295
description: "Note creation timestamp"
296
updatedAt:
297
type: string
298
format: date-time
299
description: "Last update timestamp"
300
timestamp:
301
type: string
302
format: date-time
303
description: "When the note was created"
304
type:
305
type: string
306
const: "NOTE"
307
description: "Engagement type"
308
ownerId:
309
type: string
310
description: "Owner/author of the note"
311
312
# Note-specific metadata
313
metadata:
314
type: object
315
properties:
316
body:
317
type: string
318
description: "Note content/text"
319
320
# Associated entities
321
associations:
322
type: object
323
properties:
324
contactIds:
325
type: array
326
items:
327
type: string
328
description: "Associated contact IDs"
329
companyIds:
330
type: array
331
items:
332
type: string
333
description: "Associated company IDs"
334
dealIds:
335
type: array
336
items:
337
type: string
338
description: "Associated deal IDs"
339
```
340
341
### Engagements Tasks
342
343
Task engagement records with task details and completion status.
344
345
```yaml { .api }
346
engagements_tasks:
347
primary_key: ["id"]
348
cursor_field: "updatedAt"
349
sync_mode: incremental
350
schema:
351
type: object
352
properties:
353
id:
354
type: string
355
description: "Unique task engagement identifier"
356
createdAt:
357
type: string
358
format: date-time
359
description: "Task creation timestamp"
360
updatedAt:
361
type: string
362
format: date-time
363
description: "Last update timestamp"
364
timestamp:
365
type: string
366
format: date-time
367
description: "Task due date/timestamp"
368
type:
369
type: string
370
const: "TASK"
371
description: "Engagement type"
372
ownerId:
373
type: string
374
description: "Owner/assignee of the task"
375
376
# Task-specific metadata
377
metadata:
378
type: object
379
properties:
380
subject:
381
type: string
382
description: "Task title/subject"
383
body:
384
type: string
385
description: "Task description"
386
status:
387
type: string
388
description: "Task status (NOT_STARTED, IN_PROGRESS, COMPLETED, etc.)"
389
forObjectType:
390
type: string
391
description: "Object type task is for (CONTACT, COMPANY, DEAL)"
392
priority:
393
type: string
394
description: "Task priority level"
395
taskType:
396
type: string
397
description: "Type of task (TODO, CALL, EMAIL, etc.)"
398
reminders:
399
type: array
400
items:
401
type: object
402
properties:
403
reminderTime:
404
type: string
405
format: date-time
406
407
# Associated entities
408
associations:
409
type: object
410
properties:
411
contactIds:
412
type: array
413
items:
414
type: string
415
description: "Associated contact IDs"
416
companyIds:
417
type: array
418
items:
419
type: string
420
description: "Associated company IDs"
421
dealIds:
422
type: array
423
items:
424
type: string
425
description: "Associated deal IDs"
426
```
427
428
### Legacy Engagements Stream
429
430
Unified engagement stream containing all engagement types (legacy stream for backward compatibility).
431
432
```yaml { .api }
433
engagements:
434
primary_key: ["id"]
435
cursor_field: "updatedAt"
436
sync_mode: incremental
437
schema:
438
type: object
439
properties:
440
id:
441
type: string
442
description: "Unique engagement identifier"
443
createdAt:
444
type: string
445
format: date-time
446
description: "Engagement creation timestamp"
447
updatedAt:
448
type: string
449
format: date-time
450
description: "Last update timestamp"
451
timestamp:
452
type: string
453
format: date-time
454
description: "When the engagement occurred"
455
type:
456
type: string
457
enum: ["CALL", "EMAIL", "MEETING", "NOTE", "TASK"]
458
description: "Type of engagement"
459
ownerId:
460
type: string
461
description: "Owner of the engagement"
462
metadata:
463
type: object
464
description: "Type-specific engagement metadata"
465
additionalProperties: true
466
associations:
467
type: object
468
properties:
469
contactIds:
470
type: array
471
items:
472
type: string
473
companyIds:
474
type: array
475
items:
476
type: string
477
dealIds:
478
type: array
479
items:
480
type: string
481
```
482
483
## Engagement API Strategy
484
485
The connector uses an intelligent API selection strategy for the engagements stream:
486
487
### Recent vs All Engagements API
488
489
```yaml { .api }
490
EngagementsHttpRequester:
491
type: HttpRequester
492
493
# API Selection Logic:
494
recent_api:
495
path: "/engagements/v1/engagements/recent/modified"
496
conditions:
497
- start_time within last 29 days
498
- total records <= 10,000
499
benefits:
500
- Faster response times
501
- More recent data
502
503
all_api:
504
path: "/engagements/v1/engagements/paged"
505
conditions:
506
- start_time older than 29 days
507
- total records > 10,000
508
benefits:
509
- Complete historical data
510
- No record limits
511
- Client-side filtering support
512
```
513
514
### API Selection Process
515
516
1. **Check Date Range**: If `start_time` is within last 29 days, consider Recent API
517
2. **Check Record Count**: Make test request to Recent API to check total count
518
3. **Select API**: Use Recent API if ≤10k records, otherwise use All API
519
4. **Apply Filtering**: All API uses client-side incremental filtering
520
521
## Association Processing
522
523
Engagement streams automatically populate association arrays by:
524
525
1. **Extract Associations**: Parse engagement associations from API response
526
2. **Flatten Structure**: Convert nested association objects to ID arrays
527
3. **Include Entity Types**: Separate arrays for contacts, companies, deals
528
529
**Example Association Structure:**
530
```json
531
{
532
"id": "12345",
533
"type": "CALL",
534
"associations": {
535
"contactIds": ["101", "102"],
536
"companyIds": ["201"],
537
"dealIds": ["301", "302", "303"]
538
}
539
}
540
```
541
542
## Usage Patterns
543
544
**Activity Timeline Analysis:**
545
```sql
546
SELECT type, COUNT(*) as count, DATE(timestamp) as date
547
FROM engagements_calls
548
WHERE timestamp >= '2024-01-01'
549
GROUP BY type, DATE(timestamp)
550
ORDER BY date DESC;
551
```
552
553
**Owner Activity Tracking:**
554
```sql
555
SELECT
556
ownerId,
557
COUNT(*) as total_activities,
558
COUNT(CASE WHEN type = 'CALL' THEN 1 END) as calls,
559
COUNT(CASE WHEN type = 'EMAIL' THEN 1 END) as emails,
560
COUNT(CASE WHEN type = 'MEETING' THEN 1 END) as meetings
561
FROM engagements
562
WHERE createdAt >= '2024-01-01'
563
GROUP BY ownerId;
564
```