Development

Tutorial PHP paso a paso: cómo crear tu nueva aplicación web para SMS con la API de Infobip

Bienvenido al tutorial básico para crear tu propia aplicación web para SMS.

October 20 2015

Bienvenido al tutorial básico para crear tu propia aplicación web para SMS. Te guiaremos paso a paso hacia la implementación de la API de SMS de Infobip y de los servicios de SMS. El tutorial incluye tres ejemplos de algunas de las características más importantes del envío de mensajes de texto y del control de estado:

Comenzaremos con ejemplos y presentaciones para que puedas elegir qué acción realizar.

Para poder seguir este tutorial, para escribir y probar por tu cuenta, debes preparar el ambiente (y no nos referimos a bajar las luces y preparar café). Para poder enviar mensajes, obtener registros y recibir informes de envío, debes habilitar la extensión cURL php en tu servidor web.

Para este tutorial, puedes utilizar una de las alternativas del conjunto de soluciones AMP (wamp, xampp u otro). Estos son conjuntos de soluciones de varios sistemas operativos, que se componen del servidor web Apache, la base de datos MySQL y el soporte de lenguaje de programación PHP. Debes habilitar la extensión phpcurl para la opción que elijas.

Nota: Para enviar mensajes de texto de manera segura, estos ejemplos deben alojarse en HTTPS (usando TLS) en situaciones reales. Para simplificar este tutorial, hemos usado HTTP plano.

 Mensaje de texto con todas las prestaciones 

La página (advancedSms.php) de mensajes de texto con todas las prestaciones contiene el formulario para enviar un mensaje. El botón "submit" enviará la solicitud a la página especificada en el atributo action del formulario. En este ejemplo, el formulario se va a enviar a sí mismo.

  <form action="<?php echo htmlspecialchars($_SERVER["PHP_SELF"]); ?>" method="POST" ... >

Creación de la solicitud

Antes de comenzar a manipular valores, debes controlar si los has colocado de la manera correcta. En este ejemplo, sólo hemos controlado el campo “toInput” field. No necesitas controlarlos a todos porque el método POST HTTP colocará todo automáticamente (si alguno de los campos está vacío, su valor será el de una cadena de caracteres vacía). Si estás cargando la página por primera vez, recuerda que ninguno de estos campos estará presente. Estamos solo a dos pasos de configurar todo. Después de controlar los campos, debes definir la URL para enviar la solicitud URL for sending request y el cuerpo de la solicitud body of the requestque se va a mandar. El cuerpo de la solicitud POST se presentará como una cadena de caracteres JSON. La creación del cuerpo de la solicitud lucirá de esta manera:

 // URL for sending request
$postUrl = "https://api.infobip.com/sms/1/text/advanced";

// creating an object for sending SMS
$destination = array("messageId" => $messageId, 
            "to" => $to);
$message = array("from" => $from,
        "destinations" => array($destination),
        "text" => $text,
        "notifyUrl" => $notifyUrl,
        "notifyContentType" => $notifyContentType,
        "callbackData" => $callbackData);
$postData = array("messages" => array($message));
// encoding object
$postDataJson = json_encode($postData)

En el ejemplo, el mensaje de texto se envía a un solo destinatario. Si quieres enviar este mensaje a varios destinatarios, solo debes crear otro objeto destination y agregarlo al arreglo destinations.

Como "to" (destinatario) es el único campo requerido, debes controlar si está vacío antes de enviar la solicitud. Si esto es así, notifica a tu usuario sobre el campo incompleto.

if (isset($_POST['toInput'])) { 
// all the logic goes here 
}

Para enviar la solicitud, nosotros seleccionamos cURL.

 $ch = curl_init();
$header = array("Content-Type:application/json", "Accept:application/json");

curl_setopt($ch, CURLOPT_URL, $postUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 2);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_MAXREDIRS, 2);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postDataJson);

// response of the POST request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$responseBody = json_decode($response);
curl_close($ch);

En el código citado, utilizamos varias opciones para configurar la solicitud. Estas opciones se inician mediante curl_init():

  • CURLOPT_URL - Configuración de la URL con un método que finalice en ella
  • CURLOPT_HTTPHEADER - Títulos de la solicitud: Content (contenido), Type (tipo) y Accept (aceptar)
  • CURLOPT_HTTPAUTH, CURLOPT_USERPWD - Tipo de autenticación, nombre de usuario y contraseña
  • CURLOPT_POST - Método POST de HTTP utilizado
  • CURLOPT_POSTFIELDS - Cadena de caracteres estructurada en XML o JSON creada previamente
  • Aquí puedes ver otras opciones cURL para los envíos.

Cuando hayas configurado todas las opciones, ejecuta la solicitud con curl_exec($ch). Este método te brindará una respuesta que puedes presentar como JSON y que se adapta a futuros análisis sintácticos. Después de ejecutar la solicitud, la información sobre el código de respuesta HTTP estará disponible, y la utilizaremos más adelante en este tutorial-curl_getinfo($ch, CURLINFO_HTTP_CODE).

Análisis de la respuesta

Si todo salió bien y llegó el código de respuesta HTTP desde familia 2xx (200 OK, 201 CREADOS, etc.), puedes extraer la información necesaria del cuerpo de la respuesta y presentársela a tu usuario. En nuestro ejemplo, elegimos presentar: Message ID, To, SMS Count, Status Group, Status Group Name, Status ID, Status Name and Status Description, (ID del mensaje, destinatario, conteo de segmentos del mensaje, ID del grupo de estados, nombre del grupo de estados, ID del estado, nombre del estado y descripción del estado), pero puedes elegir los que tú quieras.

El bucle foreach que se muestra debajo iterará en el arreglo de respuestas de mensajes enviados y escribirá una fila para cada mensaje enviado:

if ($httpCode >= 200 && $httpCode < 300) {
        $messages = $responseBody->messages;        

        ...

        foreach ($messages as $message) {
            echo "";
            echo "" . $message->messageId . "";
            echo "" . $message->to . "";
            echo "" . $message->status->groupId . "";
            echo "" . $message->status->groupName . "";
            echo "" . $message->status->id . "";
            echo "" . $message->status->name . "";
            echo "" . $message->status->description . "";
            echo "" . $message->smsCount . "";
            echo "";
        }
}

Nota:En este ejemplo, enviaremos solo un mensaje a un destinatario, así que el grupo de respuestas de mensajes enviados contendrá solo un elemento, y no hay necesidad de utilizar un bucle. De todos modos, si decides enviar un mensaje a más de un destinatario, debes iterar en el arreglo de respuestas.

Si se presenta la excepción, puedes presentar el mensaje al usuario de esta manera:

<div class="alert alert-danger" role="alert">
    <b>An error occurred!</b> Reason:
    <?php
    echo $responseBody->requestError->serviceException->text;
    ?>
</div>

Registros de mensajes enviados

Cuando eliges esta opción, se abre la página logs.php con el formulario de entrada para enviar registros de mensajes. El botón para enviar realizará un POST de esos campos a sí mismo.

Armado de la solicitud

logs.php es la página donde se presentarán los registros de los mensajes enviados. Debes definir la URL for sending request con el destino final de los registros de mensajes enviados y enviar la solicitud allí con el método GET HTTP (la opción CURLOPT_HTTPGET configurada en TRUE):

$getUrl = 'https://api.infobip.com/sms/1/logs?limit=20';

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Accept: application/json'));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($curl, CURLOPT_HTTPGET, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$responseBody = json_decode($response);
curl_close($curl);

Luego de ejecutar la solicitud - culr_exec($curl), y obtener el código de respuesta HTTP, puedes comenzar a analizar el cuerpo según el valor del código de respuesta. Este paso es similar a lo que hicimos en el capítulo Mensaje de texto con todas las prestaciones.

Análisis de la respuesta

Si todo salió bien y llegó el código de respuesta HTTP desde familia 2xx (200 OK, 201 CREADOS, etc.), puedes extraer la información necesaria del cuerpo de la respuesta y presentársela a tu usuario. En nuestro ejemplo, elegimos estos datos: Message ID, To, From, Text, Status Group Name, Status Description and Sent At, (ID del mensaje, destinatario, emisor, texto, nombre del grupo de estados, descripción del estado y enviado a), pero puedes elegir lo que quieras, como lo hicimos anteriormente.

if ($httpCode >= 200 && $httpCode < 300) {
    $logs = $responseBody->results;

    ...

    foreach ($logs as $log) {
        echo "";
        echo "" . $log->messageId . "";
        echo "" . $log->to . "";
        echo "" . $log->from . "";
        echo "" . $log->text . "";
        echo "" . $log->status->groupName . "";
        echo "" . $log->status->description . "";

        $formattedSentAt = date("M d, Y - H:i:s P T", strtotime($log->sentAt));    
        echo "" . $formattedSentAt . "";
        echo "";         
    }
}

El próximo bucle foreach iterará en el arreglo de registros de mensajes enviados y escribirá una única línea con las columnas apropiadas en ellos. En este caso, el bucle foreach es necesario porque solicitamos obtener todos los registros de los mensajes.

Al final, puedes analizar el cuerpo de la solicitud si ocurre la excepción, como hicimos con el método de envío de mensajes:

<div class="alert alert-danger" role="alert">
    <b>An error occurred!</b> Reason:
    <?php
        echo $responseBody->requestError->serviceException->text;
    ?>
</div>

Informes de envío a NotifyURL (URL de notificación)

Esta característica es diferente de las otras dos. La página dlrPush.php no se utiliza para solicitar información, sino que espera recibirla. Cuando se realiza un push a esta página, se puede analizar y mostrar al usuario de la manera apropiada.

Nota:Se realiza un push del informe de envío desde la página del mensaje de texto con todas las prestaciones ingresando this page URL en el campo Notify URL. Además, el campo Notify ContentType(Notificar tipo de contenido) en esa página define qué tipo de cuerpo está por ingresar.

Recepción del informe de envío del push

$responseBody = file_get_contents('php://input');

if ($responseBody <> "") {
    if (isJson($responseBody)) {
        $responseJson = json_decode($responseBody);
        $results = $responseJson->results;
    } else if (strpos(trim($responseBody), '<reportResponse>') == 0) {
        $responseXml = simplexml_load_string($responseBody);
        $results = $responseBody->results->result;
    }
}

Este código muestra que el método file_get_contents('php://input') se utiliza para obtener información POST sin procesar como cadena de caracteres. Las líneas que siguen muestran cómo verificar si la información está analizada como XML o JSON y cómo extraer los informes de envío delpush. Para XML, inspeccionamos si la cadena de caracteres del cuerpo de respuesta comienza con y si no es así, intentamos decodificarlo sin errores: función isJson(). Si todas las condiciones son FALSE, la variable $result se mantiene invariable. Esto significa que deberíamos informarle al usuario que no se realizó el push de ningún informe de envío al servidor de retrollamada.

Análisis del resultado

Analizar los informes de envío es muy similar a analizar la respuesta del mensaje de texto con todas las prestaciones y los métodos de registros de mensajes enviados, salvo que no revisamos el código de respuesta HTTP (porque no hay respuesta alguna). Lo único que debemos hacer es elegir qué información del push de informes de envío queremos mostrar y escribirla en la página.