Channel Gateway API: schemas
The request and response bodies of the operations in this API.
ChannelAccountDto
| Property | Type | Required | Description |
|---|---|---|---|
activatorUserId | string | yes | The person who created or last activated the account; the delegation the account holds was originated from their context. |
agentRef | string | yes | |
connectionId | string | yes | The connector connection (OrgConnection.id) every send of this account goes through. |
createdAt | string (date-time) | yes | |
dispatchMode | DispatchMode | yes | |
displayName | string | yes | |
externalAccountId | string | no | The provider-side account id (for a personal account, the owner's own phone or email). Left out for a caller whose only path is the org-admin configure (list and revoke). |
id | string | yes | |
orgId | string | yes | |
ownerId | string | yes | Owner subject id (the org id for an org-owned account). |
ownerKind | ChannelOwnerKind | yes | |
provider | string | yes | Connector provider key this account belongs to (UPPER_SNAKE, e.g. TELEGRAM). Open key space — the installed connector biomes decide the valid set. |
sessionScope | SessionScope | yes | |
status | ChannelAccountStatus | yes | |
statusDetail | string or null | yes | The delegation boundary's code behind statusReason, when it gave one. |
statusReason | ChannelAccountStatusReason or null | yes | Why the account is not ACTIVE (null when ACTIVE). DELEGATION_* reasons need an org admin to re-activate the account. |
updatedAt | string (date-time) | yes |
ChannelAccountDtoDataArrayEnvelope
| Property | Type | Required | Description |
|---|---|---|---|
data | array of ChannelAccountDto | yes |
ChannelAccountDtoDataEnvelope
| Property | Type | Required | Description |
|---|---|---|---|
data | ChannelAccountDto | yes |
ChannelAccountStatus
Type: one of "PENDING", "ACTIVE", "DISABLED", "ERRORED"
ChannelAccountStatusReason
Why the account is not ACTIVE (null when ACTIVE). DELEGATION_* reasons need an org admin to re-activate the account.
Type: one of "DEACTIVATED", "DELEGATION_ABSENT", "DELEGATION_RENEWAL_REFUSED", "DELEGATION_REFUSED_AT_USE", "DELEGATION_REFUSED", "DELEGATION_ENDED"
ChannelOwnerKind
Type: one of "ORG", "TEAM", "USER"
ChannelReplyDeliveryState
Type: one of "PENDING", "SENDING", "SENT", "UNCERTAIN", "EMPTY", "FAILED"
ChannelTurnDeliveryDto
| Property | Type | Required | Description |
|---|---|---|---|
bindingId | string | yes | The conversation (session binding) the turn belongs to. |
createdAt | string (date-time) | yes | |
state | ChannelReplyDeliveryState | yes | |
turnId | string | yes | The turn the reply answers (the Idempotency-Key it was relayed under). |
updatedAt | string (date-time) | yes |
ChannelTurnDeliveryDtoDataEnvelope
| Property | Type | Required | Description |
|---|---|---|---|
data | ChannelTurnDeliveryDto | yes |
ChannelTurnDeliveryDtoPaginatedEnvelope
| Property | Type | Required | Description |
|---|---|---|---|
data | array of ChannelTurnDeliveryDto | yes | |
pagination | PaginationMeta | yes |
CreateChannelAccountDto
| Property | Type | Required | Description |
|---|---|---|---|
agentRef | string | yes | Agent ref every routed session is created with: slug (the latest published revision) or slug@<revisionNumber>, where the revision is the agent registry's generated positive integer — NOT a semantic version. Prefer the bare slug so the channel tracks the current agent. |
connectionId | string | yes | The connector connection this account sends through. Must be an org-tier connection of the account's provider. |
dispatchMode | DispatchMode | no | Default dispatch behavior for inbound turns. Defaults to COLLECT. |
displayName | string | yes | Human label for this account. |
externalAccountId | string | yes | Provider-native account identifier (bot username, Slack team id, …). Unique per provider within an org. |
ownerId | string | no | The owner's id: the team id or the user id. Omitted for ORG; when given for ORG it must be the request organization. |
ownerKind | ChannelOwnerKind | no | Whose conversations these are: the owner SUBJECT that may READ their transcripts. Defaults to ORG (the organization, read by its administrators). A TEAM is read by its members, a USER by that user. The activating admin must pass the PDP may_delegate_for check on the owner. |
ownerSenderId | string | yes | Provider-native sender id of the bot owner. Auto-paired as OWNER so the owner has full access immediately. |
provider | string | yes | Connector provider key of the conversation channel (UPPER_SNAKE, e.g. TELEGRAM, SLACK). Must name a connector registered with connector-gateway-api that declares the outbound send action — an unregistered key is refused with 400 UNKNOWN_CHANNEL_PROVIDER. |
sessionScope | SessionScope | no | Session granularity for inbound targets. Defaults to USER. |
DispatchMode
Type: one of "COLLECT", "STEER", "FOLLOWUP"
PaginationMeta
| Property | Type | Required | Description |
|---|---|---|---|
hasMore | boolean | no | |
limit | number | no | |
nextCursor | string or null | no | |
page | number | no | |
previousCursor | string or null | no | |
total | number | no | |
totalPages | number | no |
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|---|---|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|---|---|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
PutResourceShareDto
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) | no | When the share lapses. |
level | string | yes | The level to grant — one of the type's share relations. |
subjectId | string | yes | |
subjectKind | ShareGranteeKind | yes | A user grantee is bound to that user's current membership of the org (422 when not a member). |
ResourceShareDto
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt | string (date-time) or null | yes | |
grantedBy | string | yes | <kind>:<id> of the principal who granted it. |
level | string | yes | The relation the share grants (a level of the type). |
membershipActive | boolean or null | yes | For a membership share, whether it is still the user's current membership of the org; false means the user left and the share grants nothing (it can still be removed). Null for every other kind. |
refusalCode | string or null | yes | The typed refusal code (tenant_mismatch, subject_unresolvable, ...) when state is refused, else null. |
state | ShareState | yes | Whether the share is in force. refused: the authorization plane refused its facts for good, so it grants nothing; re-put it with a valid subject, or remove it. |
subjectId | string | yes | For a membership share, the membership id (one stay of the user in the org). |
subjectKind | ShareSubjectKind | yes | |
userId | string or null | yes | The user of a membership share; null for every other kind. |
ResourceSharesDto
| Property | Type | Required | Description |
|---|---|---|---|
canManage | boolean | yes | Whether the caller may share or unshare this resource. |
expirable | boolean | yes | Whether a share of this type may carry an expiry; when false an expiry is refused. |
levels | array of string | yes | The levels a share of this type may grant, lowest first. A sharer may grant only a level it holds. |
shares | array of ResourceShareDto | yes |
ResourceSharesDtoDataEnvelope
| Property | Type | Required | Description |
|---|---|---|---|
data | ResourceSharesDto | yes |
SessionScope
Type: one of "USER", "THREAD", "SINGLE"
ShareGranteeKind
A user grantee is bound to that user's current membership of the org (422 when not a member).
Type: one of "user", "agent", "external-subject", "team", "role"
ShareState
Whether the share is in force. refused: the authorization plane refused its facts for good, so it grants nothing; re-put it with a valid subject, or remove it.
Type: one of "active", "refused"
ShareSubjectKind
Type: one of "membership", "agent", "external-subject", "team", "role"