Channels

Channels are named streams of events that clients subscribe to. When you connect with a valid token, you are automatically subscribed to your personal channels.

Personal Channels

These channels are scoped to your user account. The {uuid} is your user UUID (included in the JWT token).

exports:{uuid}

The primary channel for tracking export jobs. Receives all job lifecycle events.

Events delivered:

Event	When
`job.created`	A new export job is created
`job.progress`	Export progress update (throttled to every 5 seconds)
`job.finished`	Export completed successfully
`job.failed`	Export failed
`job.requeued`	Export requeued for retry
`job.convert.done`	File format conversion completed
`job.convert.failed`	File format conversion failed
`bulk_download.ready`	Bulk download ZIP is ready
`bulk_download.failed`	Bulk download ZIP assembly failed

webhooks:{uuid}

Receives events when webhook deliveries are attempted.

Events delivered:

Event	When
`webhook.event.created`	A webhook delivery was attempted

user:{uuid}

Account-level notifications not tied to specific exports.

Events delivered:

Event	When
`subscription.updated`	Your subscription plan was created, expired, or canceled

user_notifications_channel:{uuid}

Human-readable notification messages suitable for displaying as toasts or alerts in a UI.

Message types:

Type	Description
`export_started`	An export began processing
`export_completed`	An export finished successfully
`export_failed`	An export failed
`export_progress`	Progress milestone reached (25%, 50%, 75%)
`subscription_updated`	Subscription plan changed
`usage_limit_warning`	Approaching monthly usage limit (90%+)

user_dashboard_channel:{uuid}

Structured dashboard data updates. Useful for building real-time dashboards that mirror the ExportComments UI.

Message types:

Type	Description
`new_activity`	A new export appeared in the activity list
`activity_update`	An existing export's status/progress changed
`complete_update`	Full dashboard data snapshot (sent on significant state changes)
`usage_stats`	Updated usage statistics (exports count, data processed)
`subscription_status`	Current subscription details

Job-Specific Channel

You can also subscribe to a channel for a single export job:

export.{guid}.job

Receives events only for the specific export job identified by {guid}. This is useful when you want to track a single job without receiving events for all your exports.

💡

Automatic subscription

Your personal channels (exports:{uuid}, webhooks:{uuid}, etc.) are included in the JWT token and subscribed automatically on connect. The job-specific channel export.{guid}.job is also available if the token includes it.

Message Format

All messages on the exports:{uuid} and webhooks:{uuid} channels follow the standard event format:

json

{
  "version": "v3-beta",
  "event": "job.finished",
  "guid": "b4219d47-3138-5efd-9762-2ef9f9495084",
  "status": "done",
  "url": "https://example.com/download/export.xlsx",
  "details": {
    "id": 12345,
    "guid": "b4219d47-3138-5efd-9762-2ef9f9495084",
    "status": "done",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "totalExported": 1500
  }
}

Messages on dashboard and notification channels use a different structure:

json

{
  "type": "activity_update",
  "payload": {
    "guid": "b4219d47-3138-5efd-9762-2ef9f9495084",
    "updates": {
      "id": "b4219d47-3138-5efd-9762-2ef9f9495084",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "status": "progress",
      "progress": 45.2,
      "totalItems": 1500,
      "exportedItems": 678,
      "platform": "YouTube",
      "duration": "2 minutes"
    }
  },
  "timestamp": "2025-01-15T10:30:00+00:00"
}