ChannelEventsService
Esta página aún no está disponible en tu idioma.
Records third-party channel dispatch events (sent, delivered, opened, clicked, bounced, failed, skipped) into the platform’s append-only channel event trail. Each state transition is its own event — a delivery confirmation for a previously sent message is recorded as a new DELIVERED event, not an update.
Methods
Section titled “Methods”| Method | Description |
|---|---|
RecordChannelEvent |
Record a single channel dispatch event |
RecordChannelEventBatch |
Record multiple events in one round-trip |
RecordChannelEvent
Section titled “RecordChannelEvent”Record a single channel event. Duplicate terminal events (SENT, FAILED, SKIPPED) for the same (campaign, recipient, channel, step kind) tuple are rejected with accepted = false and reason = "duplicate" — callers treat this as already-recorded, not as an error.
Authorization: Internal service only
Request: RecordChannelEventRequest
Section titled “Request: RecordChannelEventRequest”| Field | Type | Description |
|---|---|---|
event |
ChannelEvent |
The event to record. |
Response: RecordChannelEventResponse
Section titled “Response: RecordChannelEventResponse”| Field | Type | Description |
|---|---|---|
accepted |
bool |
True if the event was recorded. False if rejected as a duplicate of an existing terminal event. |
reason |
string |
"duplicate" when accepted is false. Empty when accepted. |
RecordChannelEventBatch
Section titled “RecordChannelEventBatch”Record multiple events in one round-trip. Used when a channel provider delivers multiple state transitions in one payload (e.g. a batched delivery report). Best-effort per event — each event succeeds or fails independently.
Authorization: Internal service only
Request: RecordChannelEventBatchRequest
Section titled “Request: RecordChannelEventBatchRequest”| Field | Type | Description |
|---|---|---|
events |
ChannelEvent[] |
The events to record. |
Response: RecordChannelEventBatchResponse
Section titled “Response: RecordChannelEventBatchResponse”| Field | Type | Description |
|---|---|---|
results |
RecordChannelEventBatchResult[] |
Per-event results, in the same order as the request’s events list. Each carries accepted and reason as in RecordChannelEventResponse. |
ChannelEvent Message
Section titled “ChannelEvent Message”A single channel dispatch event in the append-only trail.
| Field | Type | Description |
|---|---|---|
org_id |
string |
Organization ID. |
campaign_id |
string |
Campaign the dispatch belongs to. |
recipient_user_id |
string |
Recipient user ID. |
channel |
ChannelName |
Channel the dispatch used. |
step_kind |
ChannelStepKind |
Workflow step kind that triggered the dispatch. |
status |
ChannelEventStatus |
Status of the dispatch attempt. |
skip_reason |
ChannelSkipReason |
Set only when status is SKIPPED; UNSPECIFIED otherwise. |
provider_message_id |
string |
Provider’s identifier for this dispatch. Empty for skipped events. |
cost_micros |
int64 |
Cost in micros (1/1,000,000 of a USD). Zero for channels with no per-message cost. |
metadata_json |
string |
Free-form provider error payload on FAILED. JSON-encoded; opaque to the platform. |
occurred_at |
Timestamp |
When the event occurred. |
ChannelName
Section titled “ChannelName”Third-party notification channel. Push is intentionally not in this enum — push is the primary channel and always fires alongside any third-party channels. Third-party channels are additive and carry only a deeplink notification; message content stays in the platform. Email is live today; Slack, Telegram, SMS, and generic webhooks are rolling out.
| Value | Number | Description |
|---|---|---|
CHANNEL_NAME_UNSPECIFIED |
0 | Unspecified |
CHANNEL_NAME_EMAIL |
1 | |
CHANNEL_NAME_WEBHOOK |
2 | Generic webhook |
CHANNEL_NAME_TELEGRAM |
3 | Telegram |
CHANNEL_NAME_SLACK |
4 | Slack |
CHANNEL_NAME_SMS |
5 | SMS |
CHANNEL_NAME_WHATSAPP |
6 | |
CHANNEL_NAME_MICROSOFT_TEAMS |
7 | Microsoft Teams |
CHANNEL_NAME_LINE |
8 | LINE |
CHANNEL_NAME_GOOGLE_CHAT |
9 | Google Chat |
ChannelStepKind
Section titled “ChannelStepKind”Workflow step kind that triggered the channel dispatch. Different step kinds for the same (campaign, recipient, channel) tuple are treated as distinct dispatch events.
| Value | Number | Description |
|---|---|---|
CHANNEL_STEP_KIND_UNSPECIFIED |
0 | Unspecified |
CHANNEL_STEP_KIND_REMINDER |
1 | Reminder step |
CHANNEL_STEP_KIND_ESCALATION |
2 | Escalation step |
ChannelEventStatus
Section titled “ChannelEventStatus”Status of a channel dispatch attempt. Events are append-only — each state transition (e.g. SENT → DELIVERED) is its own event.
| Value | Number | Description |
|---|---|---|
CHANNEL_EVENT_STATUS_UNSPECIFIED |
0 | Unspecified |
CHANNEL_EVENT_STATUS_SENT |
1 | Provider accepted the message |
CHANNEL_EVENT_STATUS_DELIVERED |
2 | Provider confirmed delivery |
CHANNEL_EVENT_STATUS_OPENED |
3 | Recipient opened the message |
CHANNEL_EVENT_STATUS_CLICKED |
4 | Recipient clicked the deeplink |
CHANNEL_EVENT_STATUS_BOUNCED |
5 | Message bounced |
CHANNEL_EVENT_STATUS_FAILED |
6 | Dispatch failed |
CHANNEL_EVENT_STATUS_SKIPPED |
7 | Dispatch was skipped; see skip_reason |
ChannelSkipReason
Section titled “ChannelSkipReason”Reason a dispatch was skipped rather than attempted.
| Value | Number | Description |
|---|---|---|
CHANNEL_SKIP_REASON_UNSPECIFIED |
0 | Unspecified |
CHANNEL_SKIP_REASON_OPTED_OUT |
1 | Recipient opted out of the channel |
CHANNEL_SKIP_REASON_REGION_BLOCKED |
2 | Region policy blocked the dispatch |
CHANNEL_SKIP_REASON_COST_CAP_EXCEEDED |
3 | Monthly cost cap exceeded |
CHANNEL_SKIP_REASON_NO_IDENTIFIER |
4 | No reachability identifier configured for the recipient |
CHANNEL_SKIP_REASON_ORG_SUSPENDED |
5 | Organization suspended |
Reachability, region policies, and cost caps are managed via the IntegrationsService.