Calls
A call is the live voice session of a direct message or group direct message. You join and leave one by sending Voice State Update, and Call Create, Call Update and Call Delete publish its state.
Every route here is user-only and needs a direct message or group direct message that includes you as a recipient. A channel you can't see returns 404 UNKNOWN_CHANNEL, and a channel of another type returns 400 INVALID_CHANNEL_TYPE_FOR_CALL.
Call eligibility object
Section titled “Call eligibility object”Says whether you can ring the other recipients of a channel.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| ringable1 | boolean | Whether you can start an audible ring in this channel |
| silent2 | boolean | Whether a new call notifies the other recipient without ringing |
1 False when you're already connected to the call, when your account tier can't make this kind of call, or when the other recipient's incoming call flags exclude you.
2 Always false in 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 a call eligibility object. In a direct message, the result follows the other recipient's incoming call flags.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | call eligibility object | Eligibility was returned |
The rate limit is 60 requests per 10 seconds, 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 call, even if you aren't connected to it. Setting region on a peer-to-peer call moves it to a voice server for the rest of the call. Sends Call Update when the region changes, and a new Voice Server Update to each connected participant.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| region?1 | ?string | The ID of the RTC region to select (1-64 characters) |
| latitude? | string | Not used, but must be 1-32 characters when sent |
| longitude? | string | Not used, but must be 1-32 characters when sent |
1 Null or automatic selects automatic routing. Leave it out to change nothing.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The region was updated, or no change was requested |
| 400 | error response | INVALID_FORM_BODY with INVALID_OR_RESTRICTED_RTC_REGION when the region is unknown or restricted |
| 404 | error response | NO_ACTIVE_CALL when the channel has no call |
The rate limit is 10 requests per 10 seconds, on the channel:call:update::channel_id bucket.
Ring call recipients
Section titled “Ring call recipients”POST/v1/channels/{channel_id}/call/ringStarts a call, or adds recipients to the ringing set of an active call. Fluxer rings a recipient only when Get call eligibility would return ringable true and silent false for them, and it skips the others without an error. In a direct message you can ring only the other recipient.
A new call sends Call Create and Message Create for its call message. Ringing into an active call sends Call Update. Anyone whose channel was closed gets Channel Create.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| recipients?1 | array[snowflake] | The IDs of the recipients to ring |
| latitude? | string | Not used, but must be 1-32 characters when sent |
| longitude? | string | Not used, but must be 1-32 characters when sent |
1 Omit it to ring every other recipient. An empty array starts the call and rings nobody.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The ring request was accepted |
| 400 | error response | INVALID_FORM_BODY with USER_NOT_IN_CHANNEL when a recipient isn't in the channel or is you |
| 400 | error response | CANNOT_SEND_MESSAGES_TO_USER when you can't message the other recipient |
| 400 | error response | CALL_ALREADY_EXISTS when another request started the call at the same time |
| 403 | error response | NEW_CONVERSATIONS_LIMITED under the new conversation limit |
| 403 | error response | UNCLAIMED_ACCOUNT_CANNOT_SEND_DIRECT_MESSAGES or DIRECT_MESSAGE_EMAIL_VERIFICATION_REQUIRED when your account tier can't send direct messages |
Each recipient rings for 30 seconds, and a call nobody joins ends when the ringing stops, with Call Delete.
The rate limit is 5 requests per 10 seconds, 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 call. Sends Call Update when the set changes.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| recipients?1 | array[snowflake] | The IDs of the recipients to stop ringing |
| latitude? | string | Not used, but must be 1-32 characters when sent |
| longitude? | string | Not used, but must be 1-32 characters when sent |
1 Omit it to stop ringing yourself, which declines an incoming call.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The ringing set was updated |
| 404 | error response | NO_ACTIVE_CALL when the channel has no call |
The rate limit is 20 requests per 10 seconds, on the channel:call:stop_ringing::channel_id bucket.
End call session
Section titled “End call session”POST/v1/channels/{channel_id}/call/endDoes nothing and returns 204 for any channel ID. A call ends when its last participant leaves, and you leave by sending Voice State Update with a null channel.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The request was accepted |
The rate limit is 10 requests per 10 seconds, on the channel:call:update::channel_id bucket.