Como determinar se um número de telefone ainda pertence a alguém com a API Twilio Lookup

Como determinar se um número de telefone ainda pertence a alguém com a API Twilio Lookup

Para manter a conformidade com o código de defesa do consumidor de telefonia (TCPA), você precisa obter o consentimento das pessoas antes de entrar em contato com elas por meio do seu aplicativo. Um desafio comum que pode resultar em violações do TCPA acontece se um número de telefone que costumava pertencer a alguém que forneceu consentimento tiver sido reatribuído. Você pode ter obtido consentimento para o número de telefone, mas como ele não está mais associado ao mesmo indivíduo, você não tem consentimento para entrar em contato com o novo proprietário.

A API Lookup da Twilio oferece uma maneira determinística de verificar se um número de telefone foi reatribuído para ajudar você a melhorar as taxas de contato, aumentar a eficiência da campanha e evitar multas de conformidade. Esse recurso é especialmente útil para notificações de marketing.

Como configurar e usar a API Twilio Lookup para números reatribuídos

Os pré-requisitos para usar a API Lookup incluem:

1. Uma conta da Twilio - crie a sua hoje mesmo.
2. Credenciais de teste da Twilio - encontre-as na página de Tokens de autenticação do Console.
3. Para uso em produção, será necessária uma aprovação adicional para utilizar o pacote de dados de números reatribuídos. As aprovações geralmente levam de 2 a 4 dias úteis. Observação: você poderá usar a API imediatamente em ambiente de desenvolvimento usando credenciais de teste.

Neste tutorial, você fará chamadas à API Lookup usando credenciais de teste para obter uma resposta previsível que represente números de telefone reatribuídos.

Além do número de telefone, a solicitação à API exige dois parâmetros:

1. Campos: reassigned_number. A API Lookup tem muitos pacotes de dados que são especificados pelo parâmetro Fields. Consulte os outros pacotes disponíveis.
2. LastVerifiedDate. Formatada como AAAAMMDD, essa é a data em que você obteve o consentimento para entrar em contato com o usuário final, entrou em contato com ele pela última vez ou em que o usuário final atualizou seu número de telefone pela última vez no seu aplicativo.

Depois de obter suas credenciais de teste, use-as para substituir as credenciais na solicitação a seguir. Confira a documentação sobre como fazer a mesma solicitação usando Node.js, Python e outras linguagens de programação.

Isso retorna um número reatribuído na resposta. Você verá várias outras chaves na resposta que podem conter valores nulos, como sim_swap ou line_type_intelligence. Isso acontece porque você pode solicitar vários pacotes de dados com o parâmetro Fields. Por padrão, a API Lookup também retorna informações de formatação e validação.

Observe que o campo is_number_reassigned não é uma resposta booleana, mas pode ser uma das três opções:

1. yes. O número de telefone foi reatribuído desde a última data verificada e você deve encontrar outra maneira de entrar em contato com o usuário para solicitar novamente seu número de telefone e consentimento para entrar em contato.
2. no. O número de telefone ainda pertence ao usuário final. Esta resposta indica um porto seguro contra violações de TCPA, desde que haja comprovação do consentimento.
3. no_data_available. Geralmente significa que sua LastVerifiedDate é anterior a janeiro de 2021 e que você deve solicitar novamente o consentimento para contato.

Para obter respostas adicionais, tente outros números mágicos para testar a API Lookup.

Como funciona o banco de dados FCC e o "Porto Seguro"

A Twilio usa o banco de dados oficial mantido pela Comissão Federal de Comunicações dos EUA (Federal Communications Commission, FCC). Esse banco de dados é atualizado mensalmente no 16.º dia de cada mês. Para clientes que precisam validar o status de reatribuição de números mais de uma vez por mês, recomendamos atualizar seu banco de dados no 17.º dia de cada mês. Os dados obtidos no 17.º dia do mês permanecerão válidos até que o banco de dados seja atualizado novamente no 16.º dia do mês seguinte. Se, por qualquer motivo, houver algum problema com o banco de dados, a FCC indicou que o autor da chamada poderá estar protegido contra responsabilização, desde que possua a documentação adequada.

A regra dos 45 dias

Para compensar eventuais atrasos na comunicação de dados, a FCC implementou um período obrigatório de espera de 45 dias. As operadoras de telefonia estão proibidas de atribuir um número desconectado a um novo usuário por um período mínimo de 45 dias.

Como as operadoras devem informar as desconexões até o dia 15 de cada mês, esse período de 45 dias oferece uma margem de segurança para você, como autor da chamada. Por exemplo:

• Dia 1: Um cliente desconecta seu número.

• Dia 15: O provedor relata essa desconexão à FCC.

• Dia 16: O banco de dados é atualizado.

• Dia 45+: Somente a partir desse momento o número pode ser legalmente atribuído a outra pessoa.

Porto seguro

Uma resposta "não" da API de número reatribuído do Lookup garante a conformidade com o TCPA e fornece prova (2 e 3 abaixo) do Porto seguro definido pela FCC:

Para estar protegido contra responsabilização nos termos da TCPA, o autor da chamada deve comprovar que: (1) obteve o consentimento do destinatário pretendido da chamada; (2) ele próprio ou seu agente devidamente autorizado consultou o banco de dados antes de realizar a chamada, a fim de verificar se o número não havia sido permanentemente desconectado ou reatribuído após a data em que o consentimento foi obtido; e (3) o banco de dados retornou, em resposta à consulta, uma resposta "não" incorreta.

A FCC reconhece que nenhum banco de dados é em tempo real. O Porto seguro é a sua proteção jurídica por ter realizado a "devida diligência" ao consultar a fonte oficial. Observe que você ainda é responsável por comprovar o consentimento para ligar para o destinatário pretendido.

Depuração de códigos de erro comuns

Quando a API encontrar um erro, você verá o código de erro dentro da chave de resposta reassigned_number. A resposta ainda conterá o código de status 200, pois é possível solicitar vários pacotes Lookup em uma única requisição, e alguns deles podem ser bem-sucedidos.

Há quatro erros comuns que você pode encontrar:

• 60606 – O pacote não está habilitado. Solicite acesso por meio deste formulário e, enquanto isso, realize testes utilizando as credenciais de teste e os números mágicos.
• 60607 – Solicitação de um número de telefone fora dos Estados Unidos. O serviço de números reatribuídos atende apenas números dos EUA.
• 60617 – Campo LastVerifiedDate ausente.
• 60618 – O campo LastVerifiedDate não está formatado corretamente. O formato correto é AAAAMMDD. Remova todos os traços ou espaços.

Como colocar a detecção de números reatribuídos em produção

Garantir a conformidade das mensagens de marketing é essencial, e identificar números reatribuídos ajudará você a evitar multas. Observe que a Twilio não mantém uma lista de números que não devem ser contatados. Por isso, recomendamos usar o Lookup de números reatribuídos em conjunto com a Lista nacional de números que não devem ser contatados para verificar o consentimento de contato da sua base de usuários. Quando estiver pronto para executar seu aplicativo em produção, certifique-se de ter aprovação da operadora e comece a fazer requisições usando suas chaves de API de produção, em vez das credenciais de teste.

Depois de configurar a detecção de números reatribuídos, experimente outros pacotes de dados do Lookup com o Code Exchange, como identificar números VoIP com a Inteligência de tipo de linha ou encontrar um número de telefone que teve o cartão SIM trocado antes de enviar uma solicitação 2FA por SMS. Em seguida, você pode integrar a Verify API para confirmar que o usuário tem acesso ao número de telefone e concluir a jornada de verificação do usuário. Mal posso esperar para ver o que você vai criar e proteger!