Compartir:
){kind=small}
Antiguo redactor técnico en Vonage. Le encanta jugar con las API y documentarlas.
Recepción de recibos de entrega de SMS con Java y Spark
Has aprendido cómo enviar un mensaje de texto desde tu número virtual de Vonage usando la SMS API. Todo se ve bien: tu aplicación no tiene errores y la API devuelve status: 0por lo que estás bastante seguro de que tu mensaje ha sido enviado.
Pero, a menos que tenga acceso directo al dispositivo asociado a ese número, ¿cómo puede estar seguro de que se ha entregado?
Bueno, la buena noticia es que muchas de las redes que Vonage utiliza para transmitir tu mensaje proporcionarán un recibo de entrega. Puedes acceder a ese recibo de entrega mediante programación, y eso es lo que te mostraremos cómo hacer en esta publicación.
La mala noticia es que no todos los recibos de entrega de las redes son prueba fehaciente de que el mensaje se haya entregado realmente, ya que los operadores de algunos países son más fiables que otros.
Algunos transportistas te dirán que han recibido tu mensaje, pero no te confirmarán si ha llegado a su destino. Algunos generan recibos falsos. Otros no envían ningún recibo.
Por lo tanto, antes de confiar en los recibos de entrega como fuente de la verdad, consulta la Base de conocimientos de Vonage para obtener información específica de cada país.
Para solicitar un acuse de recibo debe crear un webhook de acceso público webhook y configurar tu Account de Vonage para usarlo. Utilizaremos Java y el Spark web framework para crear el webhook. Puedes encontrar el código de este tutorial en GitHub.
El sitio JDK o su equivalente de código abierto OpenJDK. Este tutorial fue escrito usando OpenJDK 11, pero la versión 8 o superior de cualquiera de los dos debería estar bien.
Gradle (versión 3.4 o posterior) para construir tu proyecto y gestionar sus dependencias.
ngrok para que su webhook esté disponible en la Internet pública.
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.
Cree un directorio para su proyecto llamado get-delivery-receiptcambie a ese directorio y utilice gradle para inicializar el proyecto:
Acepte todos los valores predeterminados y, a continuación, abra el proyecto generado en su IDE.
Localice el archivo build.gradle y cambie el repositorio de dependencias de jcenter() a mavenCentral():
repositories {
mavenCentral()
}Sustituya la dependencies sección por lo siguiente:
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'
}
Gradle creó la clase App clase en la carpeta src/main/java/get/delivery/receipt carpeta
Abra App.java en su IDE. Elimine el método getGreeting() método que gradle ha creado para usted y añada las import necesarias para las sentencias spark y JsonWriter paquetes.
Luego, llama al método port para indicar que tu aplicación está a la escucha de peticiones en el puerto 3000.
Su App.java debería tener este aspecto:
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
}
}
Cuando Vonage recibe un recibo de entrega de un proveedor, verifica la configuración de tu Account para ver si has proporcionado la URL de un punto final de webhook. Si es así, Vonage realiza una solicitud a este punto final con la información del recibo de entrega.
Por defecto, se trata de una GET request, así que lo codificaremos primero. El endpoint que expondremos es /webhooks/delivery-receipt.
Añada lo siguiente a su método 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 en su endpoint, extrae la información del recibo de entrega de la cadena de consulta y la escribe en el archivo stdout. Luego devuelve el código de estado HTTP 204 para indicar a las API de Vonage que la solicitud se realizó correctamente, pero que no deben esperar ningún contenido en la respuesta.
También puedes configurar tu Account de Vonage para que Vonage suministre el recibo de entrega mediante una POST solicitud: ya sea como un formulario codificado en URL o una carga útil JSON.
Para que su aplicación pueda aceptar GET o POST añada el siguiente código a 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 "";
});
Ese es todo el código que necesitas para capturar recibos de entrega independientemente del método HTTP que Vonage utilice para enviarlos.
Debes hacer que tu webhook sea accesible para las API de Vonage. Una excelente manera de hacerlo durante el desarrollo es utilizar ngrok. Para obtener más información, lee nuestra entrada de blog sobre ngrok.
Descargue e instale ngroky ejecute el siguiente comando para exponer su aplicación en el puerto 3000 a la Internet pública:
Tome nota de las URL públicas que ngrok proporciona y déjelo funcionando mientras dure este tutorial (porque le da una nueva URL aleatoria cada vez que lo ejecuta, a menos que se suscriba a un plan de pago):
Terminal showing the ngrok URLs
Ahora que tienes una URL para tu webhook, debes decirle a Vonage que la use.
Inicie sesión en el panel de desarrollador y, debajo del nombre de su Account, en el menú de navegación de la izquierda, seleccione "Configuración".
En la parte derecha de esa página, en "Default SMS Setting", introduzca la URL completa de su webhook (ngrok URL más /webhooks/delivery-receipt) y haz clic en "Guardar cambios". Tenga en cuenta la opción de recibir notificaciones de los recibos de entrega a través de POST en lugar del predeterminado GET método HTTP:
Setting the delivery receipt webhook URL in the developer dashboard
Ya está todo listo. Ahora puedes probarlo.
Ejecute su aplicación Java desde el directorio de aplicaciones:
Envía un mensaje de prueba a tu número de móvil personal.
Una vez que Vonage recibe un recibo de entrega de la red, lo reenvía a tu aplicación y ésta lo muestra:
Cambie el método HTTP en la página página de configuración del salpicadero a uno de los métodos POST y envíe otro SMS para asegurarse de que su aplicación aún puede recuperar la información del recibo de entrega. Por ejemplo 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"
}
En este tutorial, aprendiste a crear una aplicación Java con el framework Spark para recuperar un recibo de entrega de Vonage utilizando la SMS API. El webhook que codificaste fue capaz de extraer el recibo de entrega independientemente del método HTTP que se utilizó para hacer la solicitud.