Chamadas
Uma chamada é a sessão de voz ao vivo de uma mensagem direta ou uma mensagem direta em grupo. Canais define o próprio canal, seu conjunto de destinatários e a lista de regiões que quem chama pode selecionar.
Entrar e sair de uma chamada é uma operação principal do Gateway. Um cliente entra ou sai de uma chamada enviando Voice State Update, e Call Create, Call Update, e Call Delete publicam o estado da chamada resultante.
Todas as rotas nesta página são apenas para usuários (user-only). Credenciais de bot e OAuth2 são rejeitadas.
Regras de acesso
Seção intitulada “Regras de acesso”Obter elegibilidade da chamada, Modificar região da chamada, Tocar para os destinatários da chamada e Parar de tocar para os destinatários da chamada exigem uma mensagem direta ou mensagem direta em grupo cujos destinatários incluam quem chama.
Um canal privado ausente ou quem chama que não é um destinatário retorna 404 UNKNOWN_CHANNEL. Um canal existente de outro tipo retorna 400 INVALID_CHANNEL_TYPE_FOR_CALL.
Encerrar sessão de chamada não aplica nenhuma dessas verificações.
Moderação de voz em uma chamada privada
Seção intitulada “Moderação de voz em uma chamada privada”Uma chamada privada não tem moderador e nem substituição de permissões (permission overwrites). Nenhuma conta além do próprio participante pode alterar o estado de voz desse participante, e o proprietário de uma mensagem direta em grupo não é exceção. Os campos mute, deaf e suppress de um estado de voz que pertence a uma chamada são, portanto, sempre falsos. Apenas o próprio Voice State Update do participante altera self_mute, self_deaf, self_video ou self_stream.
Modificar membro da guilda não pode moderar chamadas privadas. Um participante sai a seu próprio pedido ou quando sua conexão termina. Nenhuma rota nesta página ou comando do Gateway pode desconectar outro participante.
Silenciar outro participante acontece no cliente. Um cliente PODE silenciar (mute) um participante ou alterar o volume por participante. O cliente DEVE manter cada configuração local no dispositivo que escuta, para que nenhuma alcance o Gateway ou qualquer outro participante.
As operações abaixo nomeiam outro destinatário. Tocar para os destinatários da chamada adiciona destinatários nomeados ao conjunto que está tocando (ringing) de uma chamada, e Parar de tocar para os destinatários da chamada os remove dele. Qualquer destinatário atual PODE chamar qualquer um dos dois. Nenhum deles altera nada para um destinatário que já tenha se conectado, e nenhum deles escreve um estado de voz.
Objeto de elegibilidade de chamada
Seção intitulada “Objeto de elegibilidade de chamada”O Decoding Chat calcula a elegibilidade de um chamador contra um canal privado no momento da leitura. Nenhum evento do Gateway tem o resultado, e nenhum campo informa se uma chamada já está em andamento no canal.
Estrutura
Seção intitulada “Estrutura”| Campo | Tipo | Descrição |
|---|---|---|
| ringable1 | boolean | Se o usuário autenticado pode iniciar um toque audível neste canal |
| silent2 | boolean | Se uma chamada recém-iniciada notifica o outro destinatário sem um toque audível |
1 Falso quando o chamador já está conectado à chamada do canal, quando um chamador de mensagem direta nunca reivindicou suas credenciais e quando a política de chamadas recebidas do outro destinatário exclui o chamador
2 O campo só é significativo para uma mensagem direta, e é false para uma mensagem direta em grupo e sempre que ringable for false
Exemplo
Seção intitulada “Exemplo”{ "ringable": true, "silent": false}Obter elegibilidade da chamada
Seção intitulada “Obter elegibilidade da chamada”GET/v1/channels/{channel_id}/callRetorna o objeto de elegibilidade de chamada para uma mensagem direta ou mensagem direta em grupo. O chamador deve satisfazer as regras de acesso.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id1 | snowflake | O ID da mensagem direta ou canal de mensagem direta em grupo |
1 Um ID de canal de guilda é rejeitado com 400 INVALID_CHANNEL_TYPE_FOR_CALL
Uma mensagem direta relata ringable como falso quando a política de chamadas recebidas do outro destinatário exclui o chamador. Essa política é o bitfield incoming_call_flags das configurações do usuário do destinatário. O Decoding Chat verifica a política nesta ordem. A flag de ninguém (nobody) rejeita todos os chamadores. A flag apenas para amigos (friends-only) admite apenas um amigo. Sob qualquer outra política, um amigo é sempre admitido. Um chamador que compartilha um amigo com o destinatário é admitido quando a flag de amigos de amigos (friends-of-friends) está definida. Um chamador que compartilha uma guilda com o destinatário é admitido quando a flag de membros da guilda (guild-members) está definida. A flag de todos (everyone) admite todos os outros chamadores. Qualquer outro chamador é rejeitado. A flag silencioso para todos (silent-everyone) relata silent como verdadeiro para um chamador admitido pelo ramo de amigo em comum, guilda em comum ou de todos.
Para um destinatário que nunca armazenou configurações, ringable é verdadeiro e silent é falso. Uma mensagem direta que perdeu seu outro destinatário relata o mesmo par. Em uma mensagem direta em grupo, ringable é verdadeiro a menos que o chamador já esteja conectado à sua chamada, e silent é sempre falso.
O Decoding Chat avalia a mesma política novamente em uma solicitação posterior de Tocar para os destinatários da chamada.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 200 | objeto de elegibilidade de chamada | A elegibilidade foi retornada |
| 400 | resposta de erro | O canal não é uma mensagem direta ou mensagem direta em grupo e a solicitação retorna INVALID_CHANNEL_TYPE_FOR_CALL |
| 404 | resposta de erro | O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL |
Limite de taxa
Seção intitulada “Limite de taxa”60 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:call:get::channel_id.
Modificar região da chamada
Seção intitulada “Modificar região da chamada”PATCH/v1/channels/{channel_id}/callAltera a região de RTC de uma chamada ativa de mensagem direta ou mensagem direta em grupo. Retorna 204 com um corpo vazio. Emite um evento do Gateway Call Update.
Limitações
Seção intitulada “Limitações”- O chamador deve satisfazer as regras de acesso.
- Uma chamada ativa deve existir no canal.
- Uma região nomeada deve ser acessível ao chamador.
O chamador não precisa estar conectado à chamada.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id | snowflake | O ID da mensagem direta ou canal de mensagem direta em grupo |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| region?1 | ?string | O ID da região de RTC a ser selecionada (1 a 64 caracteres) |
| latitude?2 | string | A latitude relatada pelo cliente (1 a 32 caracteres) |
| longitude?2 | string | A longitude relatada pelo cliente (1 a 32 caracteres) |
1 Um campo omitido não solicita alteração, e um nulo explícito e o valor exato automatic selecionam o roteamento automático e ignoram a verificação de acessibilidade
2 Validado quanto ao comprimento e depois descartado, para que nunca afete a região selecionada
Qualquer outra region desconhecida ou inacessível retorna 400 INVALID_FORM_BODY com o código de validação INVALID_OR_RESTRICTED_RTC_REGION no campo region.
O corpo pode ser omitido. O Decoding Chat trata um corpo ausente, vazio ou contendo apenas espaços em branco como um objeto vazio, o que não solicita nenhuma alteração. Um corpo que não é um JSON válido retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body.
Um identificador de região é o id de um objeto de região de RTC. Nenhuma rota retorna as regiões aceitas por uma chamada, e Listar regiões de RTC responde apenas para um canal de voz de guilda.
Uma região ou servidor de voz não pode ser selecionado para uma chamada por qualquer um destes motivos:
- É restrito a guildas nomeadas, a um recurso de guilda ou a voz VIP.
- Sua lista de permissões de usuários exclui o chamador.
Uma região cujos servidores estão todos inativos ou todos fechados para o chamador não pode ser selecionada também. Uma instância com a voz desativada aceita qualquer string de região.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A região foi atualizada, ou nenhuma alteração foi solicitada |
| 400 | resposta de erro | O canal não é uma mensagem direta ou mensagem direta em grupo e a solicitação retorna INVALID_CHANNEL_TYPE_FOR_CALL, ou a região é desconhecida ou restrita e a solicitação retorna INVALID_FORM_BODY com o código de validação INVALID_OR_RESTRICTED_RTC_REGION |
| 404 | resposta de erro | O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL, ou não há chamada ativa e a solicitação retorna NO_ACTIVE_CALL |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”Fornecer region registra a nova região. Quando o estado da chamada publicado muda, o Decoding Chat emite Call Update para cada destinatário com o qual a chamada foi criada, e então emite a cada participante conectado um novo Voice Server Update para a região recém-selecionada. Selecionar a região que a chamada já mantém não emite nenhum dos dois. Omitir region não altera nada e não emite nenhum Dispatch.
Limite de taxa
Seção intitulada “Limite de taxa”10 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:call:update::channel_id.
Tocar para os destinatários da chamada
Seção intitulada “Tocar para os destinatários da chamada”POST/v1/channels/{channel_id}/call/ringInicia uma chamada de mensagem direta ou mensagem direta em grupo, ou adiciona destinatários tocando (ringing) a uma chamada existente. Retorna 204 com um corpo vazio. Emite eventos do Gateway Message Create, Call Create, Channel Create e Call Update.
Limitações
Seção intitulada “Limitações”- O chamador deve satisfazer as regras de acesso.
- Todo destinatário nomeado explicitamente deve ser um destinatário atual que não seja o chamador.
- Uma mensagem direta também exige que o chamador tenha permissão para enviar uma mensagem direta ao outro destinatário.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id | snowflake | O ID da mensagem direta ou canal de mensagem direta em grupo |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| recipients?1 | array[snowflake] | Os IDs dos destinatários para tocar |
| latitude?2 | string | A latitude relatada pelo cliente (1 a 32 caracteres) |
| longitude?2 | string | A longitude relatada pelo cliente (1 a 32 caracteres) |
1 Omitir o campo tem como alvo qualquer outro destinatário atual, e um array vazio explícito cria a chamada e reabre o canal para todos os outros destinatários sem tocar para ninguém 2 Validado quanto ao comprimento e depois descartado, de modo que uma nova chamada é sempre criada com roteamento automático
O corpo pode ser omitido. O Decoding Chat trata um corpo ausente, vazio ou contendo apenas espaços em branco como um objeto vazio, o que equivale a omitir recipients. Um corpo que não é um JSON válido retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body.
Um identificador que nomeia um não destinatário ou o próprio chamador retorna 400 INVALID_FORM_BODY com o código de validação USER_NOT_IN_CHANNEL. Um identificador repetido é aceito e toca esse destinatário uma vez.
Um destinatário nomeado só é tocado quando a política de chamadas recebidas descrita por Obter elegibilidade da chamada admite o chamador de forma audível. Um destinatário admitido apenas sob a flag silencioso para todos (silent-everyone) é notificado sem tocar. Em uma mensagem direta, o Decoding Chat ignora o conjunto nomeado ao escolher para quem tocar e sempre avalia a política em relação ao outro destinatário.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A operação de tocar foi concluída |
| 400 | resposta de erro | O canal não é uma mensagem direta ou mensagem direta em grupo e a solicitação retorna INVALID_CHANNEL_TYPE_FOR_CALL |
| 400 | resposta de erro | Um identificador nomeado não é um destinatário atual e a solicitação retorna INVALID_FORM_BODY com o código de validação USER_NOT_IN_CHANNEL |
| 400 | resposta de erro | A política de envio de mensagens diretas rejeita o chamador e a solicitação retorna CANNOT_SEND_MESSAGES_TO_USER |
| 400 | resposta de erro | Essa mesma política rejeita um chamador que nunca reivindicou suas credenciais com UNCLAIMED_ACCOUNT_CANNOT_SEND_DIRECT_MESSAGES |
| 400 | resposta de erro | Uma solicitação simultânea já criou a chamada e a solicitação retorna CALL_ALREADY_EXISTS |
| 404 | resposta de erro | O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”O canal privado é reaberto para o chamador e os destinatários notificados. Uma conta cujo canal foi fechado recebe Channel Create.
Uma nova chamada emite Call Create com seu conjunto de toques e região automática, seguido por uma mensagem de sistema de chamada por meio de Message Create. A mensagem é lida para o chamador e incrementa a contagem de menções não lidas para outros destinatários não-bot que não bloquearam o chamador.
Quando uma chamada já existe, o Decoding Chat em seu lugar estende o conjunto de toques e emite Call Update quando o conjunto cresce. Um destinatário que já está conectado à chamada nunca é adicionado ao conjunto de toques.
O toque (ringing) dura 30 segundos. Sua expiração emite Call Update. Se ninguém entrou e nenhum destinatário permanece tocando, a chamada termina com Call Delete.
Uma chamada criada com um conjunto de toques vazio não possui cronômetro de toque, portanto, termina no cronômetro ocioso de 120 segundos. Um array explícito recipients vazio produz tal chamada, e o mesmo ocorre com um toque que não admite nenhum candidato de forma audível.
Quando uma chamada termina, cada destinatário de canal privado recebe Message Update com o horário de término da chamada e os participantes.
A lista de destinatários da chamada é fixada quando a chamada é criada. Alterar o conjunto de destinatários de uma mensagem direta em grupo posteriormente não encerra a chamada nem atualiza essa lista. Adicionar destinatário de mensagem direta em grupo, Remover destinatário de mensagem direta em grupo e Excluir ou sair do canal deixam uma chamada em andamento intacta. Um destinatário adicionado posteriormente não recebe Dispatch por ela.
Limite de taxa
Seção intitulada “Limite de taxa”5 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:call:ring::channel_id.
Parar de tocar para os destinatários da chamada
Seção intitulada “Parar de tocar para os destinatários da chamada”POST/v1/channels/{channel_id}/call/stop-ringingRemove destinatários do conjunto de toques de uma chamada ativa de mensagem direta ou mensagem direta em grupo. Retorna 204 com um corpo vazio. Emite um evento do Gateway Call Update.
Limitações
Seção intitulada “Limitações”- O chamador deve satisfazer as regras de acesso.
- Uma chamada ativa deve existir no canal.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id | snowflake | O ID da mensagem direta ou canal de mensagem direta em grupo |
Corpo JSON
Seção intitulada “Corpo JSON”| Campo | Tipo | Descrição |
|---|---|---|
| recipients?1 | array[snowflake] | Os IDs dos destinatários para os quais se quer parar de tocar |
| latitude?2 | string | A latitude relatada pelo cliente (1 a 32 caracteres) |
| longitude?2 | string | A longitude relatada pelo cliente (1 a 32 caracteres) |
1 Omitir o campo visa apenas o chamador, que é a forma como um cliente recusa sua própria chamada recebida, e um array explícito vazio não remove ninguém 2 Validado quanto ao comprimento e depois descartado por esta operação
O corpo pode ser omitido. O Decoding Chat trata um corpo ausente, vazio ou contendo apenas espaços em branco como um objeto vazio, o que interrompe o toque (ringing) apenas para o chamador. Um corpo que não é um JSON válido retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body. Um identificador que não está tocando no momento é aceito e não altera nada.
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A operação de parar de tocar foi concluída |
| 400 | resposta de erro | O canal não é uma mensagem direta ou mensagem direta em grupo e a solicitação retorna INVALID_CHANNEL_TYPE_FOR_CALL |
| 404 | resposta de erro | O canal não existe ou o chamador não é um destinatário, cada um retornando UNKNOWN_CHANNEL, ou não há chamada ativa e a solicitação retorna NO_ACTIVE_CALL |
Efeitos colaterais
Seção intitulada “Efeitos colaterais”Quando o conjunto de toques muda, cada destinatário da chamada recebe Call Update. Esta operação não encerra a chamada imediatamente. Uma chamada sem participantes ou destinatários tocando termina dentro da janela de ociosidade existente de 120 segundos e emite Call Delete.
Limite de taxa
Seção intitulada “Limite de taxa”20 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:call:stop_ringing::channel_id.
Encerrar sessão de chamada
Seção intitulada “Encerrar sessão de chamada”POST/v1/channels/{channel_id}/call/endResponde com 204 para qualquer ID de canal bem formado e não recebe corpo. A rota não resolve nenhum canal, não realiza operação de chamada e não emite Dispatch do Gateway.
Parâmetros de rota
Seção intitulada “Parâmetros de rota”| Campo | Tipo | Descrição |
|---|---|---|
| channel_id1 | snowflake | O ID da mensagem direta ou canal de mensagem direta em grupo |
1 O valor só é verificado quanto à forma de snowflake, de modo que qualquer ID bem formado é aceito, independentemente de nomear um canal que o chamador pode alcançar
Resposta
Seção intitulada “Resposta”| Status | Corpo | Condição |
|---|---|---|
| 204 | vazio | A solicitação foi aceita |
Uma chamada termina no momento em que seu último participante conectado sai, quer um destinatário ainda esteja tocando ou não. O Decoding Chat publica Call Delete nesse momento. Uma chamada à qual nenhum participante jamais se juntou termina quando sua última entrada de toque expira. Uma chamada cujo conjunto de toques foi esvaziado por Parar de tocar para os destinatários da chamada termina no cronômetro ocioso de 120 segundos do Gateway.
Limite de taxa
Seção intitulada “Limite de taxa”10 solicitações por 10 segundos para cada usuário autenticado e ID de canal, no bucket channel:call:update::channel_id, compartilhado com Modificar região da chamada.