Verificação de telefone

A verificação de telefone prova que a conta atual controla um número de telefone. A conta recebe um código de uso único via SMS de saída, ou envia por mensagem de texto um código de desafio emitido para um número do Decoding Chat. O sucesso define o estado do telefone como verificado na conta, o qual as ações obrigatórias de telefone e o nível de verificação VERY_HIGH da guilda verificam.

Toda rota aqui precisa de uma sessão de usuário que não seja um bot, e cada uma admite uma sessão com estado de conta suspeito.

Elegibilidade

Enviar verificação de telefone e Verificar código de telefone admitem apenas uma conta que atenda a pelo menos uma destas condições.

A conta já possui um telefone verificado.
Um autenticador TOTP está registrado na conta.
O campo de bits de atividade suspeita armazenado é diferente de zero.
A conta pertence a pelo menos uma guilda cujo nível de verificação é VERY_HIGH.

Uma conta que não satisfaça nenhuma delas é recusada com 403 PHONE_ADD_NOT_ELIGIBLE.

Ambas as operações executam a verificação antes de examinarem o número enviado. Uma conta recusada não recebe nenhuma mensagem e não consome nenhum desafio. Iniciar desafio de telefone de entrada ignora a verificação completamente e emite um desafio para qualquer sessão não pertencente a bot.

Requisito de telefone adiado

No registro, uma instância pode adiar o requisito de telefone de uma nova conta. A política do portão de telefone adiado define a janela após o registro em que um ingresso qualificativo torna a exigência devida, e a contagem de membros acima da qual uma guilda é qualificativa. Uma guilda com o recurso DISCOVERABLE se qualifica com qualquer contagem de membros.

Uma exigência adiada está ausente da matriz de ações obrigatórias e não restringe nada. Uma tentativa de ingressar em uma guilda qualificativa dentro da janela a torna devida, e Aceitar convite recusa essa tentativa com 403 ACCOUNT_SUSPICIOUS_ACTIVITY. A conta então passa a dever REQUIRE_VERIFIED_PHONE ou REQUIRE_REVERIFIED_PHONE, e toda rota comum de usuário a recusa com o mesmo código.

Obter prévia de fuga do portão de telefone e Executar fuga do portão de telefone deixam essa exigência de lado novamente sem verificar um número. Ambas admitem uma conta que o restante da API recusa. A fuga só está disponível enquanto todas estas condições forem válidas.

A instância tem o portão de telefone adiado ativado.
A conta não possui nenhum telefone verificado.
A conta deve REQUIRE_VERIFIED_PHONE ou REQUIRE_REVERIFIED_PHONE.
A conta não deve REQUIRE_INBOUND_PHONE_VERIFICATION.
A exigência tornou-se devida por meio de um ingresso qualificativo e não foi adiada novamente.
A conta possui pelo menos uma ação obrigatória visível.

Representação de número

O campo phone é um número já na forma canônica E.164. O Decoding Chat remove os caracteres de controle e formatação, apara o valor e, em seguida, faz a correspondência com ^\+[1-9]\d{1,14}$. Um valor que falhe retorna 400 INVALID_FORM_BODY com uma entrada de erro de validação cuja path seja phone e cuja code seja PHONE_NUMBER_INVALID_FORMAT.

Um número cujos caracteres iniciais apareçam na lista de prefixos banidos da instância é recusado com 400 INVALID_PHONE_NUMBER. A lista contém um conjunto integrado de prefixos de países mais adições de operadoras, e uma entrada bloqueia todo número que comece com ela.

Valores de canal de verificação de telefone

Valor	Descrição
sms¹	O Decoding Chat solicita ao provedor de SMS que entregue um código de uso único ao número submetido
inbound_challenge²	O usuário envia o código de desafio emitido por mensagem de texto para o número retornado do Decoding Chat

¹ Solicitar este valor é equivalente a omitir o campo ² Solicitar este valor sempre gera um desafio de entrada, e nem o provedor de pesquisa nem o provedor de SMS de saída são contatados

Vereditos de pesquisa de provedor

Um SMS de saída exige que o número passe nas seguintes verificações. O Decoding Chat avalia as linhas na ordem e utiliza o veredito da primeira linha cuja condição corresponda. Um número roteado diretamente para um desafio de entrada não precisa dessa pesquisa.

Ordem	Condição	Veredito
1	A pesquisa não pôde ser realizada¹	Recusado com `INVALID_PHONE_NUMBER`
2	O provedor relata o número como inválido	Recusado com `INVALID_PHONE_NUMBER`
3	O tipo de linha é `fixedVoip` ou `nonFixedVoip`	Entrada, motivo `voip`
4	O número começa com `+1` e sua área de plano de numeração é canadense	Entrada, motivo `canadian`
5	O tipo de linha é ausente ou `unknown`	Entrada, motivo `unknown_line_type`
6	O tipo de linha é `landline`, `tollFree`, `premium`, `sharedCost`, `uan`, `voicemail` ou `pager`	Recusado com `INVALID_PHONE_NUMBER`
7	O tipo de linha é qualquer coisa diferente de `mobile` ou `personal`²	Recusado com `INVALID_PHONE_NUMBER`
8	A pontuação de risco de inflação de SMS atinge o limite para o país relatado³	Recusado com `INVALID_PHONE_NUMBER`
9	Nenhuma regra acima correspondeu	Aceito para SMS de saída

¹ Uma instância cujo provedor de pesquisa está indisponível ou não configurado recusa todos os números ² mobile e personal são os únicos tipos de linha aceitos ³ O limite é 100 para US e CA, 70 para GB, DE, FR, IT, ES, NL, SE, NO, DK, FI, AU, NZ, JP, KR, CH, AT, BE, IE e PT, e 35 para qualquer outro país e para uma pesquisa que não relata nenhum país

Apenas Enviar verificação de telefone converte um veredito de entrada em um desafio. Verificar código de telefone recusa os mesmos vereditos com 400 INVALID_PHONE_NUMBER.

Valores de motivo de desafio de entrada

Um motivo explica por que a tentativa não pôde ser concluída via SMS de saída.

Valor	Descrição
voip	A pesquisa do provedor classificou o destino como uma linha VoIP
canadian¹	O destino é uma área de plano de numeração canadense
unknown_line_type	A pesquisa do provedor relatou nenhum tipo de linha ou um tipo de linha desconhecido
expensive_destination²	A política de prefixo exigido para entrada configurada corresponde ao destino
account_forced³	A conta tem a flag que força a verificação de entrada
behavioural_risk	Os controles de risco de tentativas de telefone forçaram esta tentativa para o canal de entrada

¹ Determinado a partir da área de plano de numeração de um número +1, e avaliado após a regra de VoIP, de modo que um número VoIP canadense relata voip em vez disso ² Também relatado quando o chamador solicita explicitamente o canal inbound_challenge. A política de prefixos em si aplica-se apenas enquanto a conta não possui nenhum telefone verificado ³ Relatado de preferência a expensive_destination quando ambos se aplicariam

Objeto SMS delivery

Confirmação de que o provedor de SMS aceitou um código de uso único para entrega. Enviar verificação de telefone o retorna em um resultado de saída. O cliente então envia o mesmo número e o código entregue para Verificar código de telefone.

Estrutura

Campo	Tipo	Descrição
channel	string	O canal de entrega, sempre o literal `sms`

Objeto inbound challenge

As instruções para enviar um código de texto ao Decoding Chat, retornadas por Enviar verificação de telefone quando a política roteou a tentativa para a entrada. channel diferencia as formas de resposta.

Estrutura

Campo	Tipo	Descrição
channel	string	O canal de entrega, sempre o literal `inbound_challenge`
challenge_code¹	string	O código que o usuário envia por mensagem de texto para `our_number`
our_number	string	O número E.164 do Decoding Chat que recebe o código
expires_at²	ISO8601 timestamp	O momento em que o desafio deixa de ser resgatável
reason	string	O motivo de desafio de entrada que forçou esse canal

¹ Seis dígitos decimais ² 15 minutos após o desafio ter sido emitido

Exemplo

{
  "channel": "inbound_challenge",
  "challenge_code": "418207",
  "our_number": "+15550000000",
  "expires_at": "2026-03-04T18:15:00.000Z",
  "reason": "voip"
}

Objeto direct inbound challenge

O código e o número do Decoding Chat para um chamador que solicitou um desafio de entrada diretamente. Iniciar desafio de telefone de entrada o retorna.

Estrutura

Campo	Tipo	Descrição
challenge_code¹	string	O código que o usuário envia por mensagem de texto para `our_number`
our_number	string	O número E.164 do Decoding Chat que recebe o código
expires_at²	ISO8601 timestamp	O momento em que o desafio deixa de ser resgatável

¹ Seis dígitos decimais ² 15 minutos após o desafio ter sido emitido

Objeto phone verification result

Retornado por Verificar código de telefone em uma verificação bem-sucedida.

Estrutura

Campo	Tipo	Descrição
verified	boolean	Sempre o literal `true`

Objeto phone gate escape guild

Uma guilda em um objeto phone gate escape preview.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID da guilda
name	string	O nome sob o qual a guilda está listada

Objeto phone gate escape preview

O que Executar fuga do portão de telefone faria pela conta atual.

Estrutura

Campo	Tipo	Descrição
available	boolean	Se a fuga está aberta para esta conta no momento
guilds	array[objeto phone gate escape guild]	As guildas qualificativas que a fuga abandona, vazio enquanto `available` for false
owned_guilds	array[objeto phone gate escape guild]	As guildas qualificativas que a conta possui, as quais a fuga mantém

Enviar verificação de telefone

POST/v1/users/@me/phone/send-verification

Inicia a verificação do número submetido. Requer uma conta que satisfaça a elegibilidade. Retorna um objeto SMS delivery ou um objeto inbound challenge em caso de sucesso.

Diversas políticas independentes podem forçar o canal de entrada, e cada uma anula uma solicitação de sms. O Decoding Chat roteia a tentativa de forma de entrada antes de contatar os provedores de pesquisa e de SMS quando qualquer uma destas condições for verdadeira.

O chamador pede inbound_challenge.
A conta possui a flag que força a verificação de entrada.
A política configurada de prefixo exigido para entrada corresponde ao número enquanto a conta não possui um telefone verificado.

Uma tentativa que sobrevive a essa etapa passa por controles de risco de tentativa de telefone categorizados por conta, por endereço IP do cliente e por rede /24. Um bloqueio rígido retorna 429 PHONE_RATE_LIMIT_EXCEEDED com um Retry-After de 86400. Uma decisão de captcha retorna 400 CAPTCHA_REQUIRED, e esta rota não lê nenhum cabeçalho de solução de CAPTCHA, então a tentativa não pode ser repetida com uma solução. Uma decisão de entrada retorna um desafio com o motivo behavioural_risk.

Quando o provedor de SMS limita um envio ou uma verificação de código anterior para a mesma conta ou número, o Decoding Chat registra um tempo de recarga (cooldown). Uma solicitação durante esse tempo de recarga retorna 429 PHONE_RATE_LIMIT_EXCEEDED. O destino é então resolvido por meio da pesquisa do provedor. Um número que já completou a verificação duas vezes é recusado com 400 PHONE_ALREADY_USED.

Controles adicionais limitam a entrega de saída a 3 envios a cada 6 horas para cada conta e 3 envios a cada 5 dias para cada número. Qualquer negação retorna 429 PHONE_RATE_LIMIT_EXCEEDED. O provedor também pode recusar o envio. Um destino inválido retorna 400 INVALID_PHONE_NUMBER, e uma limitação retorna 429 PHONE_RATE_LIMIT_EXCEEDED. Qualquer outra recusa, incluindo um provedor inacessível, retorna 400 SMS_VERIFICATION_UNAVAILABLE. Em uma instância em que o fluxo de entrada ou o seu número de recebimento estiver desconfigurado, uma tentativa roteada como entrada retorna o mesmo código.

Corpo JSON

Campo	Tipo	Descrição
phone	string	O número na forma canônica E.164, correspondendo a `^\+[1-9]\d{1,14}$`
channel?¹	string	O canal de verificação de telefone preferido

¹ A omissão do campo solicita SMS de saída. Solicitar inbound_challenge sempre gera um desafio relatado com o motivo expensive_destination, a menos que a flag da conta force independentemente o canal e o motivo se torne account_forced

Resposta

Status	Corpo	Condição
200	objeto SMS delivery \| objeto inbound challenge	A verificação foi iniciada no canal nomeado pela resposta
400	resposta de erro	O número é recusado com `INVALID_PHONE_NUMBER`, foi verificado duas vezes antes e retorna `PHONE_ALREADY_USED`, os controles de risco exigem `CAPTCHA_REQUIRED`, ou o envio não pôde iniciar e retorna `SMS_VERIFICATION_UNAVAILABLE`
403	resposta de erro	A conta não é elegível e a requisição retorna `PHONE_ADD_NOT_ELIGIBLE`
429¹	resposta de limite de taxa	Controles de risco, uma limitação do provedor ou um controle de envio por conta ou por número nega a solicitação, que retorna `PHONE_RATE_LIMIT_EXCEEDED`

¹ Uma recusa de telefone usa o envelope de limite de taxa com o code definido como PHONE_RATE_LIMIT_EXCEEDED. Uma recusa de rota comum retorna RATE_LIMITED

No 429, o X-RateLimit-Scope relata shared quando o controle por número ou uma limitação de provedor com escopo de número produziu a recusa.

Efeitos colaterais

Em um resultado de saída, o Decoding Chat solicita ao provedor de SMS configurado para entregar um código de uso único. Em um resultado de entrada, ele cria um desafio de uso único para a conta atual.

Limite de taxa

5 requisições por minuto para cada usuário autenticado, no bucket phone:send_verification.

Iniciar desafio de telefone de entrada

POST/v1/users/@me/phone/inbound-challenge

Emite um desafio de entrada sem submeter ou examinar um número de telefone. Retorna um objeto direct inbound challenge em caso de sucesso.

A verificação de elegibilidade não se aplica aqui. O código de desafio possui seis dígitos decimais, dura por 15 minutos e pode ser resgatado uma vez. Solicitar um desafio adicional não revoga o anterior, então vários códigos emitidos para a mesma conta podem estar ativos ao mesmo tempo até que cada um expire ou seja resgatado.

Resposta

Status	Corpo	Condição
200	objeto direct inbound challenge	Um desafio foi emitido
400	resposta de erro	A instância não possui nenhum número de recepção para o desafio de entrada e a solicitação retorna `SMS_VERIFICATION_UNAVAILABLE`

Efeitos colaterais

O Decoding Chat cria um desafio de uso único para a conta atual. O desafio se completa de forma independente quando o provedor entrega a mensagem de entrada correspondente, e a resposta HTTP não possui participação nisso. Na conclusão, o Decoding Chat define o estado de telefone verificado, limpa as exigências de telefone do campo de bits de atividade suspeita armazenado, e despacha User Update. Quando o número de envio já tiver completado a verificação duas vezes, o Decoding Chat abandona a conclusão e não produz nenhum erro observável.

Limite de taxa

5 requisições por minuto para cada usuário autenticado, no bucket phone:send_verification, compartilhado com Enviar verificação de telefone.

Verificar código de telefone

POST/v1/users/@me/phone/verify

Verifica um código de SMS de saída. Requer uma conta que satisfaça a elegibilidade. Retorna um objeto phone verification result em caso de sucesso. Emite um evento de Gateway User Update.

O número é resolvido através da pesquisa de provedor novamente antes que o código seja verificado, de modo que um número que se tornou inelegível desde que o código foi enviado é recusado.

O provedor de SMS configurado verifica o número e o código em conjunto, então o provedor decide o tempo de vida do código e o limite de tentativas. Um código rejeitado retorna 400 INVALID_PHONE_VERIFICATION_CODE. Uma limitação do provedor retorna 429 PHONE_RATE_LIMIT_EXCEEDED e registra um tempo de recarga que também nega o Enviar verificação de telefone até que o mesmo expire. Um provedor inacessível, ou que responde com um erro de servidor, retorna 400 SMS_VERIFICATION_UNAVAILABLE. Depois que o código tiver sido aceito, um registro de conta que foi excluído ou que não pode mais ser lido falha com 400 PHONE_VERIFICATION_REQUIRED.

Corpo JSON

Campo	Tipo	Descrição
phone	string	O número na forma canônica E.164, correspondendo a `^\+[1-9]\d{1,14}$`
code¹	string	O código que o SMS de saída entregou (1-32 caracteres)

¹ Com os caracteres de controle e formatação removidos e aparado antes da verificação de comprimento, sendo o valor normalizado o que o provedor verifica

Resposta

Status	Corpo	Condição
200	objeto phone verification result	O número agora está verificado para a conta
400	resposta de erro	O número retorna `INVALID_PHONE_NUMBER`, o código retorna `INVALID_PHONE_VERIFICATION_CODE`, o provedor retorna `SMS_VERIFICATION_UNAVAILABLE`, o número retorna `PHONE_ALREADY_USED`, ou a conta retorna `PHONE_VERIFICATION_REQUIRED`
403	resposta de erro	A conta não é elegível e a solicitação retorna `PHONE_ADD_NOT_ELIGIBLE`
429¹	resposta de limite de taxa	Uma limitação do provedor recusa a solicitação, que retorna `PHONE_RATE_LIMIT_EXCEEDED`

¹ Uma recusa de telefone usa o envelope de limite de taxa com code definido como PHONE_RATE_LIMIT_EXCEEDED. Uma recusa de rota comum retorna RATE_LIMITED

No 429, X-RateLimit-Scope relata shared quando uma limitação de provedor com escopo de número produziu a recusa.

Efeitos colaterais

O Decoding Chat marca a conta como possuidora de um telefone verificado. Ele então limpa toda exigência de telefone do campo de bits de atividade suspeita armazenado: REQUIRE_VERIFIED_PHONE, REQUIRE_REVERIFIED_PHONE, as exigências combinadas de e-mail ou telefone, REQUIRE_INBOUND_PHONE_VERIFICATION, e o marcador de adiamento de um requisito de telefone até a conta se juntar a uma guilda comunitária qualificativa. Exigências apenas de e-mail permanecem, de modo que uma conta que também deve verificação de e-mail permanece restrita.

O Decoding Chat limpa a flag de spammer, quando presente, e despacha User Update. Quando a flag de spammer foi limpa, o Decoding Chat também despacha Guild Member Update para a conta em todas as guildas às quais ela pertence, antes do retorno da resposta HTTP.

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket phone:verify_code.

Obter prévia de fuga do portão de telefone

GET/v1/users/@me/required-actions/phone-gate-escape

Retorna um objeto phone gate escape preview para a conta atual. Para uma conta fora do estado descrito em Requisito de telefone adiado, available é false e ambos os arrays estão vazios.

Resposta

Status	Corpo	Condição
200	objeto phone gate escape preview	A prévia foi retornada

Limite de taxa

20 requisições por minuto para cada usuário autenticado, no bucket user:phone_gate_escape:preview.

Executar fuga do portão de telefone

POST/v1/users/@me/required-actions/phone-gate-escape

Abandona as guildas qualificativas que a conta não possui e adia o requisito de telefone novamente. Retorna o objeto user.

Limitações

A conta está no estado que Requisito de telefone adiado define, e uma que estiver fora dele é rejeitada com 400 PHONE_GATE_ESCAPE_UNAVAILABLE.
Uma requisição abandona no máximo 25 guildas.

Corpo JSON

O corpo é um objeto vazio. O Decoding Chat lê um corpo ausente ou vazio como um objeto vazio e descarta qualquer propriedade fornecida. Um corpo que não seja um JSON válido retorna 400 INVALID_FORM_BODY com INVALID_FORMAT no caminho body. Um JSON válido que não é um objeto é rejeitado com 400.

Resposta

Status	Corpo	Condição
200	objeto user	A fuga foi executada, totalmente ou até o limite por requisição
400	resposta de erro	A fuga não está disponível e a requisição retorna `PHONE_GATE_ESCAPE_UNAVAILABLE`

Efeitos colaterais

O Decoding Chat abandona cada guilda qualificativa que a conta não possui, no máximo 25 em uma requisição, com os mesmos efeitos de Sair da guilda. Uma guilda qualificativa que a conta possui é mantida e não bloqueia a fuga.

Uma requisição que abandona todo o conjunto então adia o requisito novamente e despacha User Update. Uma que parou no limite não escreve nenhum campo na conta, não despacha nada e retorna a conta com a exigência ainda pendente. Repita a requisição até que o required_actions retornado não possua entrada de telefone.

Limite de taxa

5 requisições por hora para cada usuário autenticado, no bucket user:phone_gate_escape:execute.