Compartilhar:
){kind=small}
Ex-redator técnico da Vonage. Adora experimentar e documentar APIs.
Recebimento de confirmaciones de entrega de SMS com Java e Spark
Você aprendeu como enviar uma mensagem de texto a partir do seu número virtual da Vonage usando a SMS API. Tudo parece estar certo: seu aplicativo não apresenta erros e a API retorna status: 0, então você está bastante confiante de que sua mensagem foi enviada.
Mas, a menos que você tenha acesso direto ao aparelho associado a esse número, como pode ter certeza de que a mensagem foi entregue?
Bem, a boa notícia é que muitas das redes que a Vonage utiliza para transmitir sua mensagem fornecem um comprovante de entrega. Você pode acessar esse comprovante de entrega por meio de programação, e é exatamente isso que vamos mostrar como fazer neste post.
A má notícia é que nem todos os comprovantes de entrega das redes constituem prova definitiva de que sua mensagem foi realmente entregue, sendo que as operadoras de alguns países são mais confiáveis do que outras.
Algumas operadoras informam que receberam sua mensagem, mas não confirmam se ela chegou ao destino. Algumas geram recibos falsos. Outras nem sequer enviam nenhum recibo.
Portanto, antes de considerar os comprovantes de entrega como fonte confiável, consulte a Base de Conhecimento da Vonage para obter informações específicas por país.
Para solicitar um comprovante de entrega, é necessário criar um webhook e configurar sua conta da Vonage para usá-lo. Usaremos Java e a framework web Spark para criar o webhook. Você pode encontrar o código deste tutorial no GitHub.
O JDK ou seu equivalente de código aberto, o OpenJDK. Este tutorial foi escrito usando o OpenJDK 11, mas qualquer uma das versões a partir da 8 deve funcionar bem.
Gradle (versão 3.4 ou posterior) para compilar seu projeto e gerenciar suas dependências.
ngrok para disponibilizar seu webhook na Internet pública.
Crie um diretório para o seu projeto chamado get-delivery-receipt, vá para esse diretório e, em seguida, use gradle para inicializar o projeto:
Aceite todas as configurações padrão e, em seguida, abra o projeto gerado no seu IDE.
Localize o build.gradle arquivo e altere o repositório de dependências de jcenter() para mavenCentral():
repositories {
mavenCentral()
}Substitua a dependencies seção pelo seguinte:
dependencies {
// Spark framework
implementation 'com.sparkjava:spark-core:2.8.0'
// Vonage client library
implementation 'com.nexmo:client:4.4.0'
// To display formatted JSON
implementation 'com.cedarsoftware:json-io:4.10.1'
}
O Gradle criou a App classe na src/main/java/get/delivery/receipt pasta.
Abra App.java no seu IDE. Remova o getGreeting() método que gradle foi criado para você e adicione as import instruções necessárias para o spark e JsonWriter pacotes.
Em seguida, chame o método port para indicar que seu aplicativo está à espera de solicitações na porta 3000.
O seu App.java deveria ficar assim:
package get.delivery.receipt;
import static spark.Spark.*;
import com.cedarsoftware.util.io.JsonWriter;
public class App {
public static void main(String[] args) throws Exception {
port(3000);
// Your code goes here
}
}
Quando a Vonage recebe um comprovante de entrega de uma operadora, ela verifica a configuração da sua Account para saber se você forneceu a URL de um endpoint de webhook. Se for o caso, a Vonage envia uma solicitação a esse endpoint com as informações do comprovante de entrega.
Por padrão, trata-se de uma GET solicitação, então vamos codificá-la primeiro. O endpoint que vamos expor é /webhooks/delivery-receipt.
Adicione o seguinte ao seu main método:
get("/webhooks/delivery-receipt", (req, res) -> {
System.out.println("DLR received via GET");
for (String param : req.queryParams()) {
System.out.printf("%s: %s\n", param, req.queryParams(param));
}
res.status(204);
return "";
});
Este código intercepta GET as solicitações no seu endpoint, remove as informações de confirmação de entrega da string de consulta e as grava em stdout. Em seguida, ele retorna um código de status HTTP 204 para informar às APIs da Vonage que a solicitação foi bem-sucedida, mas que não devem esperar nenhum conteúdo na resposta.
Você também pode configurar sua conta da Vonage para que a empresa forneça o comprovante de entrega por meio de uma POST solicitação: seja como um formulário codificado em URL ou como uma carga JSON.
Para que seu aplicativo possa aceitar tanto GET ou POST solicitações, adicione o código a seguir ao arquivo App.java:
post("/webhooks/delivery-receipt", (req, res) -> {
if (req.contentType().startsWith("application/x-www-form-urlencoded")) {
System.out.println("DLR received via POST");
for (String param : req.queryParams()) {
System.out.printf("%s: %s\n", param, req.queryParams(param));
}
} else {
System.out.println("DLR received via POST-JSON");
String prettyJson = JsonWriter.formatJson(req.body());
System.out.println(prettyJson);
}
res.status(204);
return "";
});
Esse é todo o código necessário para capturar os recibos de entrega, independentemente do método HTTP que a Vonage utilize para enviá-los.
Você deve tornar seu webhook acessível às APIs da Vonage. Uma ótima maneira de fazer isso durante o desenvolvimento é usar ngrok. Para saber mais, leia nossa postagem no blog sobre o ngrok.
Baixe e instale ngroke, em seguida, execute o comando a seguir para disponibilizar seu aplicativo na porta 3000 para a Internet pública:
Anote as URLs públicas que ngrok são fornecidos e deixe o programa em execução durante todo o tutorial (pois ele gera uma nova URL aleatória toda vez que você o executa, a menos que você se inscreva em um plano pago):
Terminal showing the ngrok URLs
Agora que você tem uma URL para o seu webhook, é preciso informar à Vonage para usá-la.
Faça login no painel do desenvolvedor e, abaixo do nome da sua conta no menu de navegação à esquerda, selecione “Configurações”.
No lado direito dessa página, na seção “Configuração padrão de SMS”, insira a URL completa do seu webhook (ngrok URL mais /webhooks/delivery-receipt) e clique em “Salvar alterações”. Observe a opção de ser notificado sobre os recibos de entrega por POST em vez do método padrão GET :
Setting the delivery receipt webhook URL in the developer dashboard
Está tudo pronto! Agora você pode testar.
Execute seu aplicativo Java a partir do diretório do aplicativo:
Envie uma mensagem de teste para o seu número de celular pessoal.
Assim que a Vonage recebe um aviso de entrega da rede, ela o encaminha para o seu aplicativo, que então o exibe:
Altere o método HTTP na página de configurações do painel para um dos POST métodos e envie outro SMS para garantir que seu aplicativo ainda consiga recuperar as informações do comprovante de entrega. Por exemplo, POST-JSON:
DLR received via POST-JSON
{
"msisdn":"447700900005",
"to":"NEXMOTEST",
"network-code":"23420",
"messageId":"140023462904E8",
"price":"0.03330000",
"status":"delivered",
"scts":"1907171217",
"err-code":"0",
"message-timestamp":"2019-07-17 11:17:52"
}
Neste tutorial, você aprendeu a criar um aplicativo Java com a estrutura Spark para obter um comprovante de entrega da Vonage usando a SMS API. O webhook que você programou conseguiu extrair o comprovante de entrega, independentemente do método HTTP utilizado para fazer a solicitação.