Guia técnico para a descontinuação da API de US Short Codes

Estão ocorrendo mudanças no setor de mensagens Application to Person (A2P). A Vonage está descontinuando a API de US Short Codes compartilhados devido ao novo código de conduta da T-Mobile e da AT&T, que proíbe o uso de originadores compartilhados para tráfego A2P. Essa descontinuação está associada à nova padrão A2P 10DLC , que oferece mais flexibilidade para códigos longos e limita o uso de códigos curtos pelas empresas.

Como resultado, as operadoras dos EUA não oferecerão mais suporte ao tráfego de códigos curtos compartilhados (SSC). Observe que isso não afeta os códigos curtos dedicados.

O que isso significa para os clientes que utilizam a API de US Short Codes compartilhados

Os clientes que utilizam a API de códigos curtos compartilhados dos EUA da Vonage precisarão migrar para uma das outras APIs disponíveis. Se você estiver utilizando a API de códigos curtos compartilhados dos EUA para comunicações via SMS, precisará fazer ajustes em seu código e em suas configurações para usar a SMS API. Além disso, se você estiver usando essa API para autenticação de dois fatores, precisará fazer ajustes no seu código para usar a SMS API ou a Verify API.

Caso você não deseje utilizar os SDKs compatíveis com a Vonage, as próprias APIs estão prontamente disponíveis. Para obter mais informações sobre essas APIs, consulte a referência da SMS API e a referência da Verify API.

Como migrar para a SMS API e suas implicações

A Vonage disponibiliza bibliotecas para várias linguagens de programação, que você pode encontrar no Visão geral do SMS no Painel do Desenvolvedor. No entanto, nesta página, mostraremos alguns exemplos usando o Node.js.

Enviar um SMS com o Node.js

O SDK pode ser instalado com o seguinte comando:

O trecho de código abaixo é um exemplo de como enviar um SMS para um número de telefone pré-definido:

const Vonage = require('@vonage/server-sdk')
const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET
})
const from = VONAGE_BRAND_NAME
const to = TO_NUMBER
const text = 'A text message sent using the Vonage SMS API'
vonage.message.sendSms(from, to, text, (err, responseData) => {
    if (err) {
        console.log(err);
    } else {
        if(responseData.messages[0]['status'] === "0") {
            console.log("Message sent successfully.");
        } else {
            console.log(`Message failed with error: ${responseData.messages[0]['error-text']}`);
        }
    }
})

Recebendo SMS com o Node.js

Para receber um SMS, é necessário que seu projeto tenha um webhook acessível ao público. Para fins de desenvolvimento, recomendamos o uso do ngrok; temos um tutorial sobre como utilizá-lo com nossos serviços aqui.

Primeiro, o projeto requer duas bibliotecas de terceiros, a `express` e a `body-parser`, que você pode instalar executando o seguinte:

O trecho de código abaixo mostra um exemplo de como lidar com o recebimento de uma mensagem SMS recebida por meio do webhook: /webhooks/inbound-sms

const app = require('express')()
const bodyParser = require('body-parser')
app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))
app
  .route('/webhooks/inbound-sms')
  .get(handleInboundSms)
  .post(handleInboundSms)
function handleInboundSms(request, response) {
  const params = Object.assign(request.query, request.body)
  console.log(params)
  response.status(204).send()
}
app.listen(process.env.PORT || 3000)

A SMS API não possui a funcionalidade que permite aos usuários optar por receber ou deixar de receber comunicações. Essa mudança significa que os desenvolvedores deverão lidar com essa funcionalidade por conta própria, fazendo ajustes no exemplo acima e configurando um método para armazenar as preferências de contato dos usuários, por exemplo, em um banco de dados.

Como posso obter um novo número?

Com a remoção dos US Short Codes, os clientes precisarão adquirir um novo número para enviar e receber mensagens SMS. Você pode adquirir números no Painel do Desenvolvedor. Certifique-se de escolher um número com recursos para SMS.

Você pode encontrar as opções de migração com as orientações de nossos especialistas na área.

Como posso registrar modelos para usar nas minhas mensagens SMS?

A API de US Short Codes possui uma funcionalidade no painel que permite registrar modelos para o uso de diferentes tipos de alertas, como alertas, marketing ou autenticação de dois fatores. Esse recurso não está mais disponível, e você precisará criar esses modelos dentro do seu projeto.

Quaisquer outras informações

Para obter mais informações sobre como usar a SMS API, você encontrará todas as informações necessárias no Painel do Desenvolvedor.

Caso deseje obter informações sobre os preços da SMS API, consulte a página de preços.

Como migrar para a Verify API e suas implicações

A Vonage possui bibliotecas compatíveis com várias linguagens de programação, que você pode conferir na visão geral do Verify na Documentação do Desenvolvedor. No entanto, nesta página, apresentaremos alguns exemplos utilizando o Node.js.

Como fazer uma solicitação de verificação

Primeiro, o projeto requer o SDK do Vonage Node @vonage/server-sdk, que você pode instalar executando o seguinte:

O trecho de código abaixo mostra um exemplo de como solicitar a verificação de um usuário. Certifique-se de substituir o seguinte:

• sua chave de API da Vonage

• sua chave secreta da API da Vonage

• o número do destinatário

• e o nome da sua marca / seu número

const Vonage = require('@vonage/server-sdk');
const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET
});
vonage.verify.request({
  number: RECIPIENT_NUMBER,
  brand: BRAND_NAME
}, (err, result) => {
  if (err) {
    console.error(err);
  } else {
    const verifyRequestId = result.request_id;
    console.log('request_id', verifyRequestId);
  }
});

Verifique o código de verificação

O código abaixo também requer a instanciação do Vonage, conforme mostrado no exemplo da etapa anterior. No entanto, para verificar o código de verificação inserido pelo usuário, o trecho de código a seguir demonstra essa funcionalidade.

Não se esqueça de atualizar o REQUEST_ID e CODE com valores válidos.

vonage.verify.check({
  request_id: REQUEST_ID,
  code: CODE
}, (err, result) => {
  if (err) {
    console.error(err);
  } else {
    console.log(result);
  }
});

Observe que a Verify API oferece, por padrão, a capacidade de gerenciar uma lista de bloqueio. Essa capacidade significa que há um recurso integrado para responder automaticamente aos usuários finais que responderem com “STOP” e marcá-los para que não recebam mais mensagens.

Se você era cliente da Vonage e utilizava seu modelo de autenticação de duas etapas (2FA) por meio da API USSC, talvez seja possível personalizar um modelo usando a Verify API. Consulte nossa documentação da Verify para entender os requisitos do modelo.

Como posso registrar modelos para usar nas minhas mensagens de SMS?

A API de US Short Codes possui uma funcionalidade no painel que permite registrar modelos para o uso de diferentes tipos de alertas, como alertas, marketing ou autenticação de dois fatores. Esse recurso não está mais disponível, e você precisará criar esses modelos dentro do seu projeto.

Quaisquer outras informações

Para obter mais informações sobre como usar a Verify API, você encontrará todas as informações necessárias no Painel do Desenvolvedor.

Caso deseje obter informações sobre os preços da Verify API, consulte a página de preços.