Calls
A call is the live voice session of a direct message or a group direct message. Channels defines the channel itself, its recipient set, and the region list a caller can select.
Joining and leaving a call is a main Gateway operation. A client joins or leaves a call by sending Voice State Update, and Call Create, Call Update, and Call Delete publish the resulting call state.
Every route on this page is user-only. Bot and OAuth2 credentials are rejected.
Access rules
Section titled “Access rules”Get call eligibility, Modify call region, Ring call recipients, and Stop ringing call recipients require a direct message or group direct message whose recipients include the caller.
An absent private channel or a caller who is not a recipient returns 404 UNKNOWN_CHANNEL. An existing channel of another type returns 400 INVALID_CHANNEL_TYPE_FOR_CALL.
End call session applies none of these checks.
Voice moderation in a private call
Section titled “Voice moderation in a private call”A private call has no moderator and no permission overwrites. No account other than the participant itself can change that participant’s voice state, and the owner of a group direct message is no exception. The mute, deaf, and suppress fields of a voice state that belongs to a call are therefore always false. Only the participant’s own Voice State Update changes self_mute, self_deaf, self_video, or self_stream.
Modify guild member cannot moderate private calls. A participant leaves at their own request or when their connection ends. No route on this page or Gateway command can disconnect another participant.
Silencing another participant happens in the client. A client MAY mute a participant or change per-participant volume. The client MUST keep each setting local to the listening device, so neither reaches the Gateway or any other participant.
The operations below name another recipient. Ring call recipients adds named recipients to the ringing set of a call, and Stop ringing call recipients removes them from it. Any current recipient MAY call either one. Neither changes anything for a recipient who has already connected, and neither writes a voice state.
Call eligibility object
Section titled “Call eligibility object”Fluxer computes eligibility for one caller against one private channel at the moment of the read. No Gateway event has the result, and neither field reports whether a call is already running in the channel.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| ringable1 | boolean | Whether the authenticated user can initiate an audible ring in this channel |
| silent2 | boolean | Whether a newly started call notifies the other recipient without audible ringing |
1 False when the caller is already connected to the channel’s call, when a direct message caller has never claimed its credentials, and when the other recipient’s incoming call policy excludes the caller
2 The field is only meaningful for a direct message, and it is false for a group direct message and whenever ringable is false
Example
Section titled “Example”{ "ringable": true, "silent": false}Get call eligibility
Section titled “Get call eligibility”GET/v1/channels/{channel_id}/callReturns the call eligibility object for a direct message or group direct message. The caller must satisfy the access rules.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| channel_id1 | snowflake | The ID of the direct message or group direct message channel |
1 A guild channel ID is rejected with 400 INVALID_CHANNEL_TYPE_FOR_CALL
A direct message reports ringable as false when the other recipient’s incoming call policy excludes the caller. That policy is the incoming_call_flags bitfield of the recipient’s user settings. Fluxer checks the policy in this order. The nobody flag rejects every caller. The friends-only flag admits only a friend. Under any other policy a friend is always admitted. A caller who shares a friend with the recipient is admitted when the friends-of-friends flag is set. A caller who shares a guild with the recipient is admitted when the guild-members flag is set. The everyone flag admits every remaining caller. Any other caller is rejected. The silent-everyone flag reports silent as true for a caller admitted by the mutual friend, mutual guild, or everyone branch.
For a recipient who has never stored settings, ringable is true and silent is false. A direct message that has lost its other recipient reports the same pair. In a group direct message ringable is true unless the caller is already connected to its call, and silent is always false.
Fluxer evaluates the same policy again on a later Ring call recipients request.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | call eligibility object | Eligibility was returned |
| 400 | error response | Channel is not a direct message or group direct message and the request returns INVALID_CHANNEL_TYPE_FOR_CALL |
| 404 | error response | Channel does not exist or the caller is not a recipient, each returning UNKNOWN_CHANNEL |
Rate limit
Section titled “Rate limit”60 requests per 10 seconds for each authenticated user and channel ID, on the channel:call:get::channel_id bucket.
Modify call region
Section titled “Modify call region”PATCH/v1/channels/{channel_id}/callChanges the RTC region of an active direct message or group direct message call. Returns 204 with an empty body. Emits a Call Update Gateway event.
Limitations
Section titled “Limitations”- The caller must satisfy the access rules.
- An active call must exist in the channel.
- A named region must be accessible to the caller.
The caller does not have to be connected to the call.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| channel_id | snowflake | The ID of the direct message or group direct message channel |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| region?1 | ?string | The ID of the RTC region to select (1 through 64 characters) |
| latitude?2 | string | The latitude the client reports (1 through 32 characters) |
| longitude?2 | string | The longitude the client reports (1 through 32 characters) |
1 An omitted field requests no change, and an explicit null and the exact value automatic both select automatic routing and skip the accessibility check
2 Validated for length and then discarded, so it never affects the selected region
Any other unknown or inaccessible region returns 400 INVALID_FORM_BODY with the validation code INVALID_OR_RESTRICTED_RTC_REGION on the region field.
The body can be omitted. Fluxer treats a missing, empty, or whitespace-only body as an empty object, which requests no change. A body that is not valid JSON returns 400 INVALID_FORM_BODY with the validation code INVALID_FORMAT at the body path.
A region identifier is the id of an RTC region object. No route returns the regions a call accepts, and List RTC regions answers only for a guild voice channel.
A region or voice server is unselectable for a call on any of these grounds:
- It is restricted to named guilds, to a guild feature, or to VIP voice.
- Its user allowlist excludes the caller.
A region whose servers are all inactive or all closed to the caller is unselectable as well. An instance with voice disabled accepts any region string.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Region was updated, or no change was requested |
| 400 | error response | Channel is not a direct message or group direct message and the request returns INVALID_CHANNEL_TYPE_FOR_CALL, or the region is unknown or restricted and the request returns INVALID_FORM_BODY with the validation code INVALID_OR_RESTRICTED_RTC_REGION |
| 404 | error response | Channel does not exist or the caller is not a recipient, each returning UNKNOWN_CHANNEL, or no active call exists and the request returns NO_ACTIVE_CALL |
Side effects
Section titled “Side effects”Supplying region records the new region. When the published call state changes, Fluxer emits Call Update to every recipient the call was created with, then issues each connected participant a fresh Voice Server Update for the newly selected region. Selecting the region the call already holds emits neither. Omitting region changes nothing and emits no Dispatch.
Rate limit
Section titled “Rate limit”10 requests per 10 seconds for each authenticated user and channel ID, on the channel:call:update::channel_id bucket.
Ring call recipients
Section titled “Ring call recipients”POST/v1/channels/{channel_id}/call/ringStarts a direct message or group direct message call, or adds ringing recipients to an existing call. Returns 204 with an empty body. Emits Message Create, Call Create, Channel Create, and Call Update Gateway events.
Limitations
Section titled “Limitations”- The caller must satisfy the access rules.
- Every explicitly named recipient must be a current recipient other than the caller.
- A direct message also requires that the caller is allowed to send the other recipient a direct message.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| channel_id | snowflake | The ID of the direct message or group direct message channel |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| recipients?1 | array[snowflake] | The IDs of the recipients to ring |
| latitude?2 | string | The latitude the client reports (1 through 32 characters) |
| longitude?2 | string | The longitude the client reports (1 through 32 characters) |
1 Omitting the field targets every other current recipient, and an explicit empty array creates the call and reopens the channel for every other recipient while ringing nobody
2 Validated for length and then discarded, so a new call is always created with automatic routing
The body can be omitted. Fluxer treats a missing, empty, or whitespace-only body as an empty object, which is the same as omitting recipients. A body that is not valid JSON returns 400 INVALID_FORM_BODY with the validation code INVALID_FORMAT at the body path.
An identifier that names a non-recipient or the caller itself returns 400 INVALID_FORM_BODY with the validation code USER_NOT_IN_CHANNEL. A repeated identifier is accepted and rings that recipient once.
A named recipient is only rung when the incoming call policy described by Get call eligibility admits the caller audibly. A recipient admitted only under the silent-everyone flag is notified without being rung. In a direct message Fluxer ignores the named set when choosing whom to ring and always evaluates the policy against the other recipient.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Ring operation completed |
| 400 | error response | Channel is not a direct message or group direct message and the request returns INVALID_CHANNEL_TYPE_FOR_CALL |
| 400 | error response | A named identifier is not a current recipient and the request returns INVALID_FORM_BODY with the validation code USER_NOT_IN_CHANNEL |
| 400 | error response | The direct message send policy rejects the caller and the request returns CANNOT_SEND_MESSAGES_TO_USER |
| 400 | error response | That same policy rejects a caller who has never claimed its credentials with UNCLAIMED_ACCOUNT_CANNOT_SEND_DIRECT_MESSAGES |
| 400 | error response | A concurrent request already created the call and the request returns CALL_ALREADY_EXISTS |
| 404 | error response | Channel does not exist or the caller is not a recipient, each returning UNKNOWN_CHANNEL |
Side effects
Section titled “Side effects”The private channel reopens for the caller and notified recipients. An account whose channel was closed receives Channel Create.
A new call emits Call Create with its ringing set and automatic region, followed by a call system message through Message Create. The message is read for the caller and increments the unread mention count for other non-bot recipients who have not blocked the caller.
When a call already exists, Fluxer instead extends the ringing set and emits Call Update when the set grows. A recipient who is already connected to the call is never added to the ringing set.
Ringing lasts 30 seconds. Its expiry emits Call Update. If nobody has joined and no recipient remains ringing, the call ends with Call Delete.
A call created with an empty ringing set has no ring timer, so it ends on the 120 second idle timer instead. An explicit empty recipients array produces such a call, and so does a ring that admits no candidate audibly.
When a call ends, every private-channel recipient receives Message Update with the call’s end time and participants.
The call’s recipient list is fixed when the call is created. Changing the recipient set of a group direct message afterwards neither ends the call nor updates that list. Add group direct message recipient, Remove group direct message recipient, and Delete or leave channel leave a running call in place. A recipient added later receives no Dispatch for it.
Rate limit
Section titled “Rate limit”5 requests per 10 seconds for each authenticated user and channel ID, on the channel:call:ring::channel_id bucket.
Stop ringing call recipients
Section titled “Stop ringing call recipients”POST/v1/channels/{channel_id}/call/stop-ringingRemoves recipients from the ringing set of an active direct message or group direct message call. Returns 204 with an empty body. Emits a Call Update Gateway event.
Limitations
Section titled “Limitations”- The caller must satisfy the access rules.
- An active call must exist in the channel.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| channel_id | snowflake | The ID of the direct message or group direct message channel |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| recipients?1 | array[snowflake] | The IDs of the recipients to stop ringing |
| latitude?2 | string | The latitude the client reports (1 through 32 characters) |
| longitude?2 | string | The longitude the client reports (1 through 32 characters) |
1 Omitting the field targets the caller alone, which is how a client declines its own incoming call, and an explicit empty array removes nobody
2 Validated for length and then discarded by this operation
The body can be omitted. Fluxer treats a missing, empty, or whitespace-only body as an empty object, which stops ringing the caller alone. A body that is not valid JSON returns 400 INVALID_FORM_BODY with the validation code INVALID_FORMAT at the body path. An identifier that is not currently ringing is accepted and changes nothing.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Stop-ringing operation completed |
| 400 | error response | Channel is not a direct message or group direct message and the request returns INVALID_CHANNEL_TYPE_FOR_CALL |
| 404 | error response | Channel does not exist or the caller is not a recipient, each returning UNKNOWN_CHANNEL, or no active call exists and the request returns NO_ACTIVE_CALL |
Side effects
Section titled “Side effects”When the ringing set changes, every call recipient receives Call Update. This operation does not end the call immediately. A call with no participants or ringing recipients ends within the existing 120 second idle window and emits Call Delete.
Rate limit
Section titled “Rate limit”20 requests per 10 seconds for each authenticated user and channel ID, on the channel:call:stop_ringing::channel_id bucket.
End call session
Section titled “End call session”POST/v1/channels/{channel_id}/call/endAnswers 204 for any well-formed channel ID and takes no body. The route resolves no channel, performs no call operation, and emits no Gateway Dispatch.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| channel_id1 | snowflake | The ID of the direct message or group direct message channel |
1 The value is only checked for snowflake form, so any well-formed ID is accepted whether or not it names a channel the caller can reach
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Request was accepted |
A call ends the moment its last connected participant leaves, whether or not a recipient is still ringing. Fluxer publishes Call Delete at that moment. A call that no participant ever joined ends instead when its last ringing entry expires. A call whose ringing set was emptied by Stop ringing call recipients ends on the Gateway’s 120 second idle timer.
Rate limit
Section titled “Rate limit”10 requests per 10 seconds for each authenticated user and channel ID, on the channel:call:update::channel_id bucket, shared with Modify call region.