Schemas

The objects the control API reads and returns, named as the OpenAPI document names them. Fields marked ? may be absent.

AddQueueMemberRequest

Field	Type	Description
skills?	string[]	At most 32 items.
priority?	integer	0–100. Default 0.
pausedUntil?	string (date-time) | null
identity	string	1–200 characters.

Application

Field	Type	Description
id	string (uuid)
slug	string
name	string
status	string	One of active, suspended.
settings	ApplicationSettings	The platform defaults this tenant runs with. Nothing in it is a tenant domain concept.
createdAt	string (date-time)
updatedAt	string (date-time)

ApplicationKey

Field	Type	Description
id	string (uuid)
apiKey	string	Matches ^tlk_(live|test)_.
label	string
status	string	One of active, revoked.
lastUsedAt	string (date-time) | null
createdAt	string (date-time)
revokedAt	string (date-time) | null

ApplicationKeyCreated

Field	Type	Description
id	string (uuid)
apiKey	string	Matches ^tlk_(live|test)_.
apiSecret	string	Shown once. Matches ^tlsk_.
label	string
createdAt	string (date-time)
warning	string

ApplicationKeyPage

Field	Type	Description
data	ApplicationKey[]
nextCursor	string | null	The cursor for the next page; null on the last.

ApplicationSettings

The platform defaults this tenant runs with. Nothing in it is a tenant domain concept.

Field	Type	Description
maxParticipants?	integer
defaultRoomMode?	string	Fixed for the room's life. p2p is two seats. One of p2p, sfu.
ringTimeoutSec?	integer
emptyTimeoutSec?	integer
departureTimeoutSec?	integer
recordingPolicy?	string	Whether and when a room may be recorded; fixed at the room's creation. One of off, on_demand, always.
recordingRequiresConsent?	boolean	What a room takes when it does not say.
recordingRetentionDays?	integer	Days a recording's files are kept; 90 unless set. 1–3650.
duplicateIdentityPolicy?	string	One of reject, evict.
grantCeiling?	object	What any token of this tenant may be granted; it only narrows.
metering?	MeteringSettings	Metering and quotas, validated on write. A quota left out is not enforced. Over a quota is quota_exhausted; reaching a percentage in thresholds sends usage.threshold once per quota, percentage and period (the UTC month for minutes, the UTC day for the concurrency quotas).

Call

Field	Type	Description
sid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
type	string	One of direct, queue, meeting.
from	string	The identity that placed the call.
to	string[]	The identities it rang.
media	string	One of audio, video.
status	string	One of ringing, active, completed, no_answer, rejected, cancelled, failed.
queueId	string (uuid) | null
createdAt	string (date-time)
ringStartedAt	string (date-time) | null
answeredAt	string (date-time) | null
endedAt	string (date-time) | null
durationSec	integer | null	From answer to end; null for a call never answered.
billableSec	integer | null	The participants' billable seconds between answer and end, summed and rounded up to the tenant's increment — about twice durationSec for a 1:1 call, and 0 for one whose media never flowed. Null for a call never answered.
endReason	string | null	Null until the call ends. The call's own record, the same for both sides: hangup when the identity that placed the call hung up, remote_hangup when the other side did. Every reason is described with the call.ended webhook. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
invites?	Invite[]	On a read of one call, and in the answers of POST /v1/calls and …/end.

CallAnsweredData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
by	string	The identity that answered.
answeredAt	string (date-time)

CallDetail

Field	Type	Description
sid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
type	string	One of direct, queue, meeting.
from	string	The identity that placed the call.
to	string[]	The identities it rang.
media	string	One of audio, video.
status	string	One of ringing, active, completed, no_answer, rejected, cancelled, failed.
queueId	string (uuid) | null
createdAt	string (date-time)
ringStartedAt	string (date-time) | null
answeredAt	string (date-time) | null
endedAt	string (date-time) | null
durationSec	integer | null	From answer to end; null for a call never answered.
billableSec	integer | null	The participants' billable seconds between answer and end, summed and rounded up to the tenant's increment — about twice durationSec for a 1:1 call, and 0 for one whose media never flowed. Null for a call never answered.
endReason	string | null	Null until the call ends. The call's own record, the same for both sides: hangup when the identity that placed the call hung up, remote_hangup when the other side did. Every reason is described with the call.ended webhook. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
invites	Invite[]	On a read of one call, and in the answers of POST /v1/calls and …/end.

CallEndedData

Carried by call.ended, call.missed, call.rejected and call.cancelled. billableSec is the participants' billable seconds in the call, null for a call never answered — the field a tenant's billing reads.

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
endReason	string	Why a call ended: the call's own record, the same whichever side reads it. hangup — the identity that placed the call hung up (a queue call's caller included); remote_hangup — the other side hung up: the callee, or the member who answered a queue call. A participant whose connection was lost and did not come back in time, or who was removed from the room, counts as hanging up. no_answer — nobody answered before the ring timeout, nobody could be reached, or a queue gave up; rejected — the callee declined; cancelled — the caller gave up while it rang; evicted — the room was ended, through this API or by a participant allowed to end it; quota_exhausted — a quota or an identity's credit ran out; node_failure — a server failed and the call could not be carried over; max_duration — the room reached its longest allowed duration. busy, reconnect_timeout and transport_failure are not recorded today. The web SDK's callEnded reports hangup and remote_hangup from the client's own side instead: hangup when that client hung up. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration.
durationSec	integer | null	From answer to end; null for a call never answered.
billableSec	integer | null	Participant seconds in the call, rounded up to the increment; null for a call never answered.
endedAt	string (date-time)

CallEvent

Field	Type	Description
at	string (date-time)
type	string
participantSid	string | null
payload	object

CallEventPage

Field	Type	Description
data	CallEvent[]
nextCursor	string | null	The cursor for the next page; null on the last.

CallPage

Field	Type	Description
data	Call[]
nextCursor	string | null	The cursor for the next page; null on the last.

CallRingingData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
to	string[]
media	string	One of audio, video.
needsPush	boolean	True when no device of the invitee's could be reached — the tenant's cue to push from its own token store.

CreateApplicationKeyRequest

Field	Type	Description
label?	string	At most 60 characters.
env?	string	One of live, test. Default "live".

CreateApplicationRequest

Field	Type	Description
slug	string	2–40 characters. Matches ^[a-z0-9][a-z0-9-]*$.
name	string	1–120 characters.
settings?	ApplicationSettings	The platform defaults this tenant runs with. Nothing in it is a tenant domain concept.

CreateCallRequest

Field	Type	Description
from	string	The identity the call is placed for. 1–200 characters.
to?	string[]	The identities to ring. One today; more is 501 unsupported. 1–16 items.
queue?	string	A queue’s slug or id, instead of to. 1–200 characters.
requiredSkills?	string[]	With queue, the skills a member must hold to be offered the call. At most 16 items.
media?	string	One of audio, video. Default "audio".
ringTimeoutSec?	integer	5–120. Default 30.
roomMetadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.

CreateQueueRequest

Field	Type	Description
strategy?	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec?	integer	5–120. Default 30.
redirectDelayMs?	integer	0–60000. Default 2000.
maxAttempts?	integer	1–100. Default 20.
maxWaitSec?	integer	10–3600. Default 300.
overflowAction?	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings?	QueueSettings
slug	string	Matches ^[a-z0-9][a-z0-9_-]{0,62}$.

CreateRoomRequest

Field	Type	Description
name?	string	Unique among live rooms; the sid when absent. 1–200 characters.
mode?	string	Fixed for the room's life. p2p is two seats. One of p2p, sfu. Default "sfu".
maxParticipants?	integer	50 unless given; a p2p room is 2. 2–100.
emptyTimeoutSec?	integer	How long the room lives empty, before anyone joins and after the last leaves. 1–86400. Default 60.
departureTimeoutSec?	integer	How long a dropped participant keeps its seat; 20 s in sfu, 60 s in p2p, unless given. 1–600.
metadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
recordingPolicy?	string	on_demand: recorded when POST /v1/rooms/{sid}/recordings asks. always: recorded from the first join, and again on a new media server if the room moves. The application's setting when absent, else off; a p2p room cannot be recorded, so anything but off is refused there. One of off, on_demand, always.
recordingRequiresConsent?	boolean	Record a participant only once its client acknowledged the recording, which its user chooses to. The application's setting when absent, else false.

CreateWebhookRequest

Field	Type	Description
url	string	https, on the public internet. 1–2048 characters.
events?	string[]	Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. 1–19 items. Default ["*"].

CreditAccount

Field	Type	Description
identity	string
balance	integer	Credits.
updatedAt	string (date-time)

CreditEntryRequest

Field	Type	Description
delta	integer	Whole credits, signed. -1000000000000–1000000000000.
reason	string	One of grant, refund, expiry, adjust.
idempotencyKey	string	1–200 characters.
refType?	string	1–60 characters.
refId?	string	1–200 characters.

CreditEntryResult

Field	Type	Description
identity	string
balance	integer | null	The balance after the entry.
entry	LedgerEntry
replayed	boolean	True when the key had already written this entry.

Delivery

Field	Type	Description
id	string	The delivery's X-Talkline-Delivery.
event	string	One of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold.
status	string	One of pending, delivered, failed, abandoned.
attempts	integer	0–7.
lastStatusCode	integer | null
lastError	string | null
nextAttemptAt	string (date-time) | null	Set while pending.
deliveredAt	string (date-time) | null
createdAt	string (date-time)
payload	WebhookEnvelope	Every delivery's body. Deliveries are at least once: the receiver is idempotent on id, which is the X-Talkline-Delivery header and stable across retries.

DeliveryPage

Field	Type	Description
data	Delivery[]
nextCursor	string | null	The cursor for the next page; null on the last.

Device

Field	Type	Description
identity	string
deviceId	string	The tenant's own handle for the install.
platform	string	One of web, android, ios.
pushProvider	string	One of fcm, apns_voip, web_push, none.
pushToken	string | null
voipToken	string | null	iOS PushKit; not the APNs alert token.
sdkVersion	string | null
appVersion	string | null
osVersion	string | null
model	string | null
lastSeenAt	string (date-time)
createdAt	string (date-time)
updatedAt	string (date-time)

DevicePage

Field	Type	Description
data	Device[]
nextCursor	string | null	The cursor for the next page; null on the last.

Grants

What a participant may do. Every name is one the model has; any other is refused rather than ignored.

Field	Type	Description
roomJoin?	boolean
room?	string	A room sid or name. At most 200 characters.
roomCreate?	boolean
roomAdmin?	boolean	Mute and evict others, end the room.
roomList?	boolean
canPublish?	boolean
canSubscribe?	boolean
canPublishData?	boolean
canPublishSources?	string[]	Each one of microphone, camera, screen, screen_audio.
hidden?	boolean	In the room and invisible to the others — a supervisor.
recorder?	boolean
canUpdateOwnMetadata?	boolean	Default false.

Health

Field	Type	Description
status	string	One of ok, degraded.
database	string	ok, or the error.
redis	string	ok, or the error.

IceServers

Field	Type	Description
iceServers	object[]
iceServers[].urls	string[]
iceServers[].username?	string
iceServers[].credential?	string
ttlSec	integer

IdentitySettings

Field	Type	Description
identity	string
displayName	string | null
availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
updatedAt	string (date-time)

Introspection

Field	Type	Description
identity	string
name?	string
ref?	string
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
expiresAt	string (date-time)
requestedGrants	object	The token's grants claim as it was minted.
grants	object	What the server grants — never wider than asked.
grants.roomJoin?	boolean
grants.room?	string	A room sid or name. At most 200 characters.
grants.roomCreate?	boolean
grants.roomAdmin?	boolean	Mute and evict others, end the room.
grants.roomList?	boolean
grants.canPublish?	boolean
grants.canSubscribe?	boolean
grants.canPublishData?	boolean
grants.canPublishSources?	string[]	Each one of microphone, camera, screen, screen_audio.
grants.hidden?	boolean	In the room and invisible to the others — a supervisor.
grants.recorder?	boolean
grants.canUpdateOwnMetadata?	boolean	Default false.

IntrospectRequest

Field	Type	Description
token	string	1–8192 characters.

Invite

Field	Type	Description
identity	string
state	string	One of ringing, accepted, rejected, cancelled, timeout, unreachable.
attempt	integer
devicesNotified	any[]	Which of the invitee's installs were told, and how.
createdAt	string (date-time)
respondedAt	string (date-time) | null
rejectReason	string | null	The invitee's own words, unread by the platform.

LedgerEntry

Field	Type	Description
id	string	Matches ^[0-9]+$.
delta	integer
reason	string	One of grant, consume, refund, expiry, adjust.
refType	string | null
refId	string | null
idempotencyKey	string
createdAt	string (date-time)

LedgerPage

Field	Type	Description
data	LedgerEntry[]
nextCursor	string | null	The cursor for the next page; null on the last.

MeteringSettings

Metering and quotas, validated on write. A quota left out is not enforced. Over a quota is quota_exhausted; reaching a percentage in thresholds sends usage.threshold once per quota, percentage and period (the UTC month for minutes, the UTC day for the concurrency quotas).

Field	Type	Description
billingIncrementSec?	integer	A call's billableSec is rounded up to this; 60 bills by the started minute. 1–3600. Default 1.
quotas?	object
quotas.maxConcurrentRooms?	integer	Live rooms, at room creation. At least 1.
quotas.maxParticipantsPerRoom?	integer	Seats in one room, at join. At least 1.
quotas.maxConcurrentParticipants?	integer	Seats across the application, at join. At least 1.
quotas.maxMonthlyMinutes?	integer	Billable minutes of seats started this UTC month, at join. At least 1.
quotas.maxRecordingGb?	integer	Gigabytes of recordings held — not yet deleted by retention — checked when a recording starts. At least 1.
thresholds?	integer[]	Default [80,100].

MintedToken

Field	Type	Description
token	string
grants	Grants	What a participant may do. Every name is one the model has; any other is refused rather than ignored.
note	string

MintTokenRequest

Field	Type	Description
identity	string	Becomes the token's sub. 1–200 characters.
name?	string	At most 120 characters.
ref?	string	At most 120 characters.
metadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
grants?	object	{ roomJoin: true, canSubscribe: true } unless given.
grants.roomJoin?	boolean
grants.room?	string	A room sid or name. At most 200 characters.
grants.roomCreate?	boolean
grants.roomAdmin?	boolean	Mute and evict others, end the room.
grants.roomList?	boolean
grants.canPublish?	boolean
grants.canSubscribe?	boolean
grants.canPublishData?	boolean
grants.canPublishSources?	string[]	Each one of microphone, camera, screen, screen_audio.
grants.hidden?	boolean	In the room and invisible to the others — a supervisor.
grants.recorder?	boolean
grants.canUpdateOwnMetadata?	boolean	Default false.
ttlSec?	integer	1–600. Default 300.

Participant

Field	Type	Description
sid	string	Matches ^PT_[0-9a-f]{20}$.
identity	string
ref	string | null	The token's ref.
name	string | null
kind	string	One of standard, agent, egress, bridge.
state	string	One of joining, active, disconnected, left.
hidden	boolean
grants	Grants	What a participant may do. Every name is one the model has; any other is refused rather than ignored.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
joinedAt	string (date-time)
leftAt	string (date-time) | null
disconnectReason	string | null	One of client_leave, server_evict, timeout, transport_failure, duplicate_identity, quota.
tracks	Track[]

ParticipantPage

Field	Type	Description
data	Participant[]
nextCursor	string | null	The cursor for the next page; null on the last.

PresenceEntry

Field	Type	Description
identity	string
state	string	One of offline, online, in_call.
availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
lastSeenAt	string (date-time) | null	The last heartbeat; null for an identity never seen.

PresenceList

Field	Type	Description
data	PresenceEntry[]

PresencePage

Field	Type	Description
data	PresenceEntry[]
nextCursor	string | null	The cursor for the next page; null on the last.

Problem

RFC 9457. Branch on code; detail is for a log, never for a user.

Field	Type	Description
type	string (uri)
title	string
status	integer
code	string	The machine-readable error. x-talkline-status gives the HTTP status each one travels with. Codes shared with the protocol are the same string over either transport. One of validation_failed, token_ttl_too_long, unauthenticated, token_expired, token_replayed, token_not_yet_valid, permission_denied, app_suspended, not_found, room_not_found, identity_not_found, conflict, room_full, room_closed, duplicate_identity, already_answered, payload_too_large, rate_limited, internal, unsupported, sfu_unavailable, signaling_unavailable, recording_unavailable, quota_exhausted.
detail	string
instance?	string	The request's path and query.

Queue

Field	Type	Description
id	string (uuid)
slug	string
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec	integer
redirectDelayMs	integer
maxAttempts	integer
maxWaitSec	integer
overflowAction	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings	QueueSettings
createdAt	string (date-time)
updatedAt	string (date-time)

QueueAbandonedData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
queueId	string (uuid)
queueSlug	string | null	Null when the queue was deleted under the entry.
caller	string
requiredSkills	string[]
enqueuedAt	string (date-time)
attempts	integer	Members offered the call before the caller left. At least 0.
abandonedAt	string (date-time)

QueueAssignedData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
queueId	string (uuid)
queueSlug	string | null	Null when the queue was deleted under the entry.
caller	string
requiredSkills	string[]
enqueuedAt	string (date-time)
attempts	integer	Members offered the call, the one who answered included. At least 1.
assignedIdentity	string
assignedAt	string (date-time)

QueueEnteredData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
queueId	string (uuid)
queueSlug	string | null	Null when the queue was deleted under the entry.
caller	string
requiredSkills	string[]
enqueuedAt	string (date-time)

QueueEntry

Field	Type	Description
callSid	string	Matches ^CS_.
caller	string
state	string	One of waiting, assigned, abandoned, overflowed, no_agents.
requiredSkills	string[]
attempts	integer
enqueuedAt	string (date-time)
assignedAt	string (date-time) | null
abandonedAt	string (date-time) | null
assignedIdentity	string | null

QueueEntryPage

Field	Type	Description
data	QueueEntry[]
nextCursor	string | null	The cursor for the next page; null on the last.

QueueExplanation

Field	Type	Description
queueId	string (uuid)
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
caller	string
agent	string
at	string (date-time)
eligible	boolean
excludedBy	string | null	One of self, paused, offline, unavailable, busy, tried, skill_mismatch, not_pinned.
position	integer | null
of	integer	How many members are eligible.
score	number | null
factors	object | null
inputs	object
inputs.online	boolean
inputs.availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
inputs.activeCalls	integer
inputs.pausedUntil	string (date-time) | null
inputs.skills	string[]
inputs.priority	integer
inputs.lastAssignedAt	string (date-time) | null
inputs.completedToday	integer
inputs.rejectedCallerToday	boolean

QueueMember

Field	Type	Description
identity	string
skills	string[]
priority	integer	Lower is preferred.
pausedUntil	string (date-time) | null
createdAt	string (date-time)
updatedAt	string (date-time)

QueueMemberPage

Field	Type	Description
data	QueueMember[]
nextCursor	string | null	The cursor for the next page; null on the last.

QueueOverflowedData

Field	Type	Description
callSid	string	Matches ^CS_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
queueId	string (uuid)
queueSlug	string | null	Null when the queue was deleted under the entry.
caller	string
requiredSkills	string[]
enqueuedAt	string (date-time)
attempts	integer	Members offered the call before nobody was left. At least 0.
overflowedAt	string (date-time)

QueuePage

Field	Type	Description
data	Queue[]
nextCursor	string | null	The cursor for the next page; null on the last.

QueueSettings

Field	Type	Description
weights?	object	fair_share factor weights. Unset factors keep their defaults.
weights.completed_today?	number
weights.rejected_this_caller_today?	number
weights.active_calls?	number
weights.idle_seconds?	number
weights.tier?	number
completed_call_weight?	number	Read as weights.completed_today.
rejection_penalty?	number	Read as weights.rejected_this_caller_today.
allow_concurrent?	boolean	Also offer calls to members already in a call. Off by default: a member in a call is skipped as busy.
pinned_identity?	string	The one identity a pinned queue offers to. 1–200 characters.

QueueSimulation

Field	Type	Description
queueId	string (uuid)
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
caller	string
requiredSkills	string[]
at	string (date-time)
decision	object
decision.kind	string	One of offer, overflow, exhausted.
decision.agent?	string
decision.action?	string
decision.reason?	string
ranked	object[]
ranked[].position	integer
ranked[].identity	string
ranked[].score	number	Lowest wins.
ranked[].factors	object
excluded	object[]
excluded[].identity	string
excluded[].reason	string	One of self, paused, offline, unavailable, busy, tried, skill_mismatch, not_pinned.

QueueStats

Field	Type	Description
waiting	integer
oldestWaitingSince	string (date-time) | null
members	integer
online	integer
eligibleNow	integer	Members a call could be offered to now.
today	object
today.assigned	integer
today.abandoned	integer
today.unanswered	integer	Ended with nobody eligible, or the loop spent.
today.averageWaitSec	number | null

Recording

Field	Type	Description
sid	string	Matches ^RC_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
status	string	starting and active while it records; stopping and processing while its files are finished and uploaded; then complete, or failed — stopped by something other than a request, or never started — with whatever it captured (partial). One of starting, active, stopping, processing, complete, failed.
layout	string	Every recording is per_track today. One of per_track, composite, audio_only.
consentRequired	boolean	Participants were recorded only once they acknowledged it.
partial	boolean	Stopped by something other than a request; its files are what it captured before.
error	string | null	Why a failed recording stopped — node_failed, egress_restarted, start_failed: … — for a log.
startedAt	string (date-time)
endedAt	string (date-time) | null
durationSec	integer | null
sizeBytes	integer | null	Written so far while it runs; stored once finished.
storageKey	string | null	The prefix every file and the timeline are under, once uploaded.
expiresAt	string (date-time) | null	When retention deletes its files.
deletedAt	string (date-time) | null	When retention deleted them; the record stays.
files	RecordingFile[]

RecordingFile

One track's file, Opus and VP8 or VP9 in WebM, H.264 in Matroska, copied as the publisher sent it. Placed in time by offsetMs from the recording's start; the timeline says when each participant joined and left, muted and spoke.

Field	Type	Description
trackSid	string	Matches ^TR_[0-9a-f]{20}$.
identity	string
participantSid	string	Matches ^PT_[0-9a-f]{20}$.
kind	string	One of audio, video.
source	string	One of microphone, camera, screen, screen_audio.
file	string	TR_….webm; TR_…-2.webm for a track whose stream was replaced mid-recording.
key	string	The object's key in the store.
mime	string
sizeBytes	integer
offsetMs	integer	Milliseconds from the recording's start to the file's first media.
durationMs	integer
sha256	string	Of the bytes stored, hex.

RecordingFinishedData

Carried by recording.finished and recording.failed: the recording as GET /v1/recordings/{sid} shows it, its sid named recordingSid.

Field	Type	Description
recordingSid	string	Matches ^RC_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
status	string	starting and active while it records; stopping and processing while its files are finished and uploaded; then complete, or failed — stopped by something other than a request, or never started — with whatever it captured (partial). One of starting, active, stopping, processing, complete, failed.
layout	string	One of per_track, composite, audio_only.
consentRequired	boolean
partial	boolean
error	string | null
startedAt	string (date-time)
endedAt	string (date-time) | null
durationSec	integer | null
sizeBytes	integer | null
storageKey	string | null
expiresAt	string (date-time) | null
deletedAt	string (date-time) | null
files	RecordingFile[]

RecordingPage

Field	Type	Description
data	Recording[]
nextCursor	string | null	The cursor for the next page; null on the last.

RecordingStartedData

Field	Type	Description
recordingSid	string	Matches ^RC_[0-9a-f]{20}$.
roomSid	string	Matches ^RM_[0-9a-f]{20}$.
consentRequired	boolean
startedAt	string (date-time)

RecordingUrls

Field	Type	Description
expiresAt	string (date-time)
urls	object[]
urls[].file	string
urls[].url	string (uri)

RevokedApplicationKey

Field	Type	Description
id	string (uuid)
apiKey	string
status	"revoked"	One of revoked.
revokedAt	string (date-time)

Room

Field	Type	Description
sid	string	Matches ^RM_[0-9a-f]{20}$.
name	string	Unique among the tenant's live rooms; the sid when none was given.
mode	string	Fixed for the room's life. p2p is two seats. One of p2p, sfu.
maxParticipants	integer
emptyTimeoutSec	integer
departureTimeoutSec	integer
recordingPolicy	string	Whether and when a room may be recorded; fixed at the room's creation. One of off, on_demand, always.
recordingRequiresConsent	boolean	A participant is recorded only once it acknowledged the recording.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
numParticipants	integer	Seats not yet left.
createdAt	string (date-time)
startedAt	string (date-time) | null
endedAt	string (date-time) | null
endReason	string | null	One of empty, api, max_duration, node_failure, quota.
participants?	Participant[]	On a read of one room only.

RoomDetail

Field	Type	Description
sid	string	Matches ^RM_[0-9a-f]{20}$.
name	string	Unique among the tenant's live rooms; the sid when none was given.
mode	string	Fixed for the room's life. p2p is two seats. One of p2p, sfu.
maxParticipants	integer
emptyTimeoutSec	integer
departureTimeoutSec	integer
recordingPolicy	string	Whether and when a room may be recorded; fixed at the room's creation. One of off, on_demand, always.
recordingRequiresConsent	boolean	A participant is recorded only once it acknowledged the recording.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
numParticipants	integer	Seats not yet left.
createdAt	string (date-time)
startedAt	string (date-time) | null
endedAt	string (date-time) | null
endReason	string | null	One of empty, api, max_duration, node_failure, quota.
participants	Participant[]	On a read of one room only.

RoomFinishedData

Field	Type	Description
roomSid	string	Matches ^RM_[0-9a-f]{20}$.

RoomPage

Field	Type	Description
data	Room[]
nextCursor	string | null	The cursor for the next page; null on the last.

SendDataRequest

Field	Type	Description
payload	string	At most 15 360 bytes once decoded.
topic?	string	At most 100 characters.
to?	string[]	Identities. Absent or empty — everyone in the room. At most 200 items.
reliable?	boolean	Default true.

SendDataResult

Field	Type	Description
recipients	integer	How many seats it was sent to.

Track

Field	Type	Description
sid	string	Matches ^TR_[0-9a-f]{20}$.
kind	string	One of audio, video.
source	string	One of microphone, camera, screen, screen_audio.
mime	string
simulcastLayers	integer
muted	boolean
name	string | null
startedAt	string (date-time)
endedAt	string (date-time) | null

UpdateApplicationRequest

Field	Type	Description
name?	string	1–120 characters.
status?	string	One of active, suspended.
settings?	ApplicationSettings	The platform defaults this tenant runs with. Nothing in it is a tenant domain concept.

UpdateParticipantRequest

Field	Type	Description
grants?	Grants	What a participant may do. Every name is one the model has; any other is refused rather than ignored.
metadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
mutedTracks?	string[]	Track sids to mute, in sfu rooms. A muted track stays muted until its publisher unmutes it. At most 16 items.

UpdateQueueMemberRequest

Field	Type	Description
skills?	string[]	At most 32 items.
priority?	integer	0–100. Default 0.
pausedUntil?	string (date-time) | null

UpdateQueueRequest

Field	Type	Description
strategy?	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec?	integer	5–120. Default 30.
redirectDelayMs?	integer	0–60000. Default 2000.
maxAttempts?	integer	1–100. Default 20.
maxWaitSec?	integer	10–3600. Default 300.
overflowAction?	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings?	QueueSettings

UpdateWebhookRequest

Field	Type	Description
url?	string	1–2048 characters.
events?	string[]	Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *. 1–19 items.
status?	string	active resumes a paused or failing endpoint. One of active, paused.

UpsertDeviceRequest

Field	Type	Description
platform	string	One of web, android, ios.
pushProvider?	string	One of fcm, apns_voip, web_push, none. Default "none".
pushToken?	string	1–4096 characters.
voipToken?	string	iOS PushKit; not the APNs alert token. 1–4096 characters.
sdkVersion?	string	At most 40 characters.
appVersion?	string	At most 40 characters.
osVersion?	string	At most 60 characters.
model?	string	At most 80 characters.

UpsertIdentityRequest

Field	Type	Description
displayName?	string	At most 120 characters.
availability?	string	What the person chose. Presence is what the platform sees. One of available, away, dnd. Default "available".
metadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.

UsageGroup

Field	Type	Description
key	string	The day (YYYY-MM-DD, UTC), the identity, or the room sid.
seats	integer	Seats counted: one per participant per joining.
connectedSec	integer	Join to departure, the departure grace included.
billableSec	integer	Connected, less the time before media first flowed and the time lost past the grace.
publishedAudioSec	integer	Unmuted audio track lifetimes; sfu rooms only.
publishedVideoSec	integer	Unmuted video track lifetimes; sfu rooms only.
sfuSec	integer	Connected seconds in sfu rooms; 0 in p2p.
recordedSec	integer
sfuEgressBytes	integer
turnBytesRelayed	integer	Reconciled from TURN hourly; see turnBytesFinal.
final	boolean	False while a seat in the group is live (counted to the last flush).
turnBytesFinal	boolean	False until every seat in the group has been reconciled.

UsagePage

Field	Type	Description
from	string (date-time)
to	string (date-time)
groupBy	string	One of day, identity, room.
data	UsageGroup[]
nextCursor	string | null	The cursor for the next page; null on the last.

UsageRates

Field	Type	Description
rates	object	Credits per unit — a second, or a byte — by dimension.

WebhookEndpoint

Field	Type	Description
id	string (uuid)
url	string (uri)
events	string[]	* is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *.
status	string	failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing.
createdAt	string (date-time)
updatedAt	string (date-time)
secret?	string	The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_.

WebhookEndpointPage

Field	Type	Description
data	WebhookEndpoint[]
nextCursor	string | null	The cursor for the next page; null on the last.

WebhookEndpointWithSecret

Field	Type	Description
id	string (uuid)
url	string (uri)
events	string[]	* is every event, including those added later. Each one of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold, *.
status	string	failing is the platform's to set, after twenty consecutive failed attempts. One of active, paused, failing.
createdAt	string (date-time)
updatedAt	string (date-time)
secret	string	The signing secret — in the answers to registration and rotation, and nowhere else. Matches ^whsec_.

WebhookEnvelope

Every delivery's body. Deliveries are at least once: the receiver is idempotent on id, which is the X-Talkline-Delivery header and stable across retries.

Field	Type	Description
id	string
event	string	One of room.started, room.finished, participant.joined, participant.left, call.ringing, call.answered, call.ended, call.missed, call.rejected, call.cancelled, queue.entered, queue.assigned, queue.abandoned, queue.overflowed, recording.started, recording.finished, recording.failed, usage.threshold.
createdAt	string (date-time)
data	object	The event's fields, times as ISO 8601.