Core Concepts and Domain Model

Project / Channel / Participant / Task / Callback fields and invariants, plus the two credential families.

Version v1.1.0 · Updated 2026-10-26 · revision 1

This page explains, once, the terms, fields and invariants that recur throughout the documentation. Field names follow the frozen domain interface definition: the platform API (/v1/*) uses camelCase wire fields, while the Agora-compatible endpoints use snake_case aliases.

The two credential families#

Project#

Channel and Participant#

• Channel name: 1–128 characters from [A-Za-z0-9_-], case-sensitive, and unique within a project.
• Media-plane room names are namespaced by App ID: <appId>:<channelName>, so tenants cannot collide.
• profile is communication or live and decides whether the Agora-compatible endpoints return users or broadcasters / audience.
• A Participant is "one online presence of one user inside one channel": uid (1..2147483647), optional userId (IM identity), role, platform, joinedAt / leftAt, leaveReason, audioMuted / videoMuted, publishing.{audio,video,screen}.

Platform codes (platform) match Agora: 0 other, 1 Android, 2 iOS, 5 Windows, 6 Linux, 7 Web, 8 macOS.

Leave reasons (leaveReason / callback reason) map as follows: 1 normal/other, 2 timeout, 3 kicked or banned, 5 duplicate login/switch, 10 network disconnected.

Task#

Recording and media push are both task-shaped resources with their own state machine:

starting → running → stopping → stopped
                 ↘ failed
                 ↘ expired (media push only: triggered by idleTimeout)

• Every state change is persisted first, then written to the Outbox, and only then delivered as a callback (transactional outbox), so a lost callback never rolls back state — it only causes a redelivery.
• RecordingTask additionally carries layout, storage, subscribeAudioUids / subscribeVideoUids, files[], usageSeconds, queueWaitMs, idempotencyKey.
• StreamingTask additionally carries entryPoint, streamName, rtmpUrl, hlsUrl, idleTimeoutSeconds, lastActiveAt.

UsageEvent and QualitySample#

• Usage is billed per minute; types are audio / video / recording / streaming / transcoding. Every event carries an idempotencyKey, so duplicate observations over the webhook and reconciliation channels are never billed twice.
• A quality sample is a per-user, per-minute aggregate: videoFreezeMs / audioFreezeMs / networkDelayMs are the raw freeze and delay durations; thresholds are applied on the server (see Analytics).
• Six analysis dimensions: region, networkType, osType, sdkVersion, deviceType, channelSize.

CallbackEnvelope#

Platform API vs. Agora-compatible API#

The same business facts, in two envelopes:

Key invariants#

• rtcUid ∈ [1, 2147483647] and is never 0 (in Agora semantics 0 means "assigned randomly by the server"); the same (appId, userId) is stable for the duration of a session.
• Channel names are unique within a project; the SFU room name is <appId>:<channelName>.
• A token is bound to (appId, channelName, uid, role, privilegeExpireAt, tokenExpireAt); a wildcard token uses * as its channel.
• Every task state change is persisted first, then enters the Outbox, and is delivered as a callback last.
• A join_channel ban applies in two places at once: token issuance (403 banned) and live sessions (the user is disconnected, with leave reason 3).
• Usage events are idempotent on (projectId, idempotencyKey); the webhook and reconciliation channels write through the same idempotent path.
• Callbacks carry both a SHA1 (Agora-Signature) and a SHA256 (Agora-Signature-V2) signature, computed over the raw request body bytes.