Como receber confirmaciones de entrega de SMS com PHP

Já abordamos anteriormente o envio e recebimento mensagens SMS com PHP, mas falta uma coisa: os comprovantes de entrega.

Os comprovantes de entrega são enviados:

• quando um aparelho recebe uma mensagem,

• por uma rede

• ou nem mesmo, dependendo da rede para a qual você está enviando a mensagem.

Você pode encontrar mais informações sobre isso na base de conhecimento da Vonage.

O código-fonte desta postagem do blog está disponível no GitHub.

Pré-requisitos

Você precisará ter o PHP instalado antes de seguir as instruções deste post. Estou usando o PHP 7.4, mas o código aqui deve funcionar no PHP 7.3 e versões posteriores.

Você também precisará de do Composer para baixar nossas dependências.

Por fim, você precisará do CLI da Vonage instalado. Vamos usá-lo para configurar a URL do comprovante de entrega em nosso Account da Vonage.

Account da API da Vonage

Para concluir este tutorial, você precisará de uma Account na API da Vonage. Se você ainda não tiver uma, pode se cadastrar hoje mesmo e começar a desenvolver com crédito gratuito. Depois de criar um Account, você encontrará sua chave de API e seu segredo de API na parte superior do Painel da API da Vonage.

Recebendo um comprovante de entrega de SMS com PHP

Quando uma rede informa à Vonage que uma mensagem SMS foi entregue, a Vonage pode encaminhar essa informação para o seu aplicativo na forma de uma solicitação HTTP.

Quando a Vonage recebe um SMS para um número de telefone de sua propriedade, ela faz uma solicitação HTTP para uma URL que você configurou, contendo todas as informações sobre o SMS. (Não se preocupe em configurar essa URL por enquanto; falaremos sobre isso um pouco mais adiante)

Para receber o comprovante de entrega, vamos usar o framework Slim Vamos instalá-lo agora com composer:

A Vonage fará uma GET ou uma POST solicitação ao seu aplicativo com os dados, dependendo de como você configurou sua Account (você pode encontrar a opção selecionada HTTP Method no painel). Nesta postagem, vamos criar uma aplicação capaz de lidar com ambos os métodos HTTP.

Para processar a solicitação recebida, vamos criar uma nova Slim aplicativo e registraremos um manipulador que responda a ambos GET e POST a /webhooks/delivery-receipt. Para isso, crie um arquivo chamado index.php com o seguinte conteúdo:

<?php

use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
require __DIR__ . '/vendor/autoload.php';

$app = AppFactory::create();

$handler = function (Request $request, Response $response) {
    return $response->withStatus(204);
};

$app->get('/webhooks/delivery-receipt', $handler);
$app->post('/webhooks/delivery-receipt', $handler);

$app->run();

Este aplicativo processará a solicitação recebida e responderá com um código de sucesso à Vonage, mas ainda não faz nada. Queremos pegar os valores da solicitação recebida e registrá-los no terminal. Para isso, verificaremos se há valores no corpo da solicitação POST, recorrendo aos parâmetros GET caso não haja. Assim que tivermos um array de $params, vamos registrá-lo no terminal usando error_log. Atualize seu $handler para que fique da seguinte forma:

$handler = function (Request $request, Response $response) {
    $params = $request->getParsedBody();

    // Fall back to query parameters if needed
    if (!count($params)){
        $params = $request->getQueryParams();
    }

    error_log(print_r($params, true));
    return $response->withStatus(204);
};

É tudo o que precisamos para registrar os recibos de entrega recebidos da Vonage usando PHP.

Executando seu código localmente

Em seguida, você precisa iniciar o servidor PHP local para poder fazer chamadas HTTP ao seu aplicativo. Para iniciar o servidor PHP local, abra um novo terminal e execute php -S localhost:8000. Agora, seu aplicativo está escutando na porta 8000 na sua máquina local.

Como disponibilizar seu aplicativo com o ngrok

Embora tenhamos uma aplicação pronta para processar os comprovantes de entrega, precisamos disponibilizá-la na internet para que a Vonage possa enviar solicitações a ela.

Podemos usar o ngrok para expor nosso aplicativo local à internet executando ngrok http 8000. Anote a ngrok URL gerada (ela será algo como http://abc123.ngrok.io) pois precisaremos fornecer essa URL à Vonage para que eles saibam para onde enviar o comprovante de entrega.

Configure seu account da Vonage

A última coisa a fazer é configurar a URL do webhook para os comprovantes de entrega no painel do Vonage. Acesse suas página de configurações , atualize a URL do webhook para o comprovante de entrega com sua ngrok URL (por exemplo, http://abc123.ngrok.io/webhooks/delivery-receipt) e clique em “Salvar alterações”.

Neste momento, podemos enviar um SMS e acompanhar a confirmação de entrega. Você pode ler um tutorial anterior sobre como enviar um SMS com PHP aqui ou executar o código a seguir para enviar um SMS:

Nem todos os países oferecem suporte a remetentes alfa. Se for esse o caso, talvez você precise adquirir um número, primeiro encontrando um número para comprar com vonage numbers:search US e, em seguida, comprando um digitando vonage numbers:buy <number> e usar esse número como seu from parâmetro.

$client = new \Vonage\Client(new Vonage\Client\Credentials\Basic(API_KEY, API_SECRET));     

$text = new \Vonage\SMS\Message\SMS(VONAGE_TO, VONAGE_FROM, 'Test message using PHP client library');
$text->setClientRef('test-message');

$client->sms()->send($text);

Pode demorar alguns minutos devido à latência da rede, mas a mensagem SMS deve ser entregue em breve, e o comprovante de entrega deve chegar logo em seguida.

Conclusão

Receber um aviso de entrega de SMS é muito semelhante a receber uma mensagem SMS. Quando a Vonage recebe dados da rede, ela os transforma em uma solicitação HTTP e os envia para uma URL que você configurou.

O Nexmo Developer oferece mais informações sobre como receber confirmações de entrega de SMS com PHP, incluindo um diagrama de fluxo sobre como os dados são trocados entre você, a Vonage e a operadora de telefonia.

Não se esqueça: se tiver alguma dúvida, sugestão ou ideia que gostaria de compartilhar com a comunidade, sinta-se à vontade para participar do nosso espaço de trabalho da Comunidade no Slack ou deixar uma resposta aqui embaixo 👇. Adoraria receber feedback de quem já colocou este tutorial em prática e saber como está o seu projeto.