
Compartilhar:
Sou ator formado, com uma dissertação sobre stand-up comedy, e comecei a me dedicar ao desenvolvimento em PHP por meio dos encontros da comunidade. Você pode me encontrar dando palestras e escrevendo sobre tecnologia, ou ouvindo e comprando discos curiosos da minha coleção de vinil.
Como receber confirmaciones de entrega de SMS com PHP e Vonage
Tempo de leitura: 6 minutos
Os comprovantes de entrega de SMS enviadas são uma excelente fonte de dados que permite aos desenvolvedores acompanhar o trajeto das mensagens. Isso é particularmente útil se a qualidade dos números para os quais você está enviando exigir uma alta taxa de sucesso, se você tiver um sistema de produção que tenha crescido a ponto de as solicitações de SMS API não entregues se tornarem onerosas para o sistema, ou se você estiver realizando uma campanha e precisar acompanhar os resultados.
Os recibos são enviados como webhooks quando o dispositivo final recebe a carga útil (DELIVRD), ou quando a operadora recebe o SMS e o envia para o dispositivo (ACCEPTD). Há uma opção adicional para ativar “Considerado entregue”, que é útil quando a operadora de reencaminhamento não emite recibos.
Esses dados oferecem muito mais visibilidade sobre sua pilha de mensagens; neste tutorial, vamos criar uma implementação para ler Relatórios de Entrega (DLRs) usando o framework Slim em PHP.
Pré-requisitos
Criar um aplicativo enxuto
Primeiramente, você precisará criar um novo projeto no Composer e, em seguida, baixar o Slim.
mkdir dlr-reports && cd dlr-reports
composer initSiga as instruções interativas da CLI; você pode usar as configurações padrão para tudo, exceto na escolha interativa dos pacotes. Agora você deve ter um composer.json arquivo: no meu caso, ele fica assim:
{
"name": "j-seconde/dlr-reports",
"autoload": {
"psr-4": {
"JSeconde\\DlrReports\\": "src/"
}
},
"authors": [
{
"name": "Jim Seconde",
"email": "test@test.com"
}
],
"require": {}
}Agora, vamos adicionar o Slim, o mecanismo de tratamento de HTTP compatível com PSR-7 do Slim e o SDK PHP da Vonage:
composer require slim/slim
composer require slim/psr7
composer require vonage/client-core Adicionando uma rota de webhook
A rota aceitará uma POST solicitação que conterá recibos de entrega na carga útil. No Painel da Vonage, você pode escolher se deseja receber um POST ou GET solicitação, mas vamos optar por POST como a forma mais comum de enviar dados.
touch src/index.phpEm seguida, adicione nosso código ao novo arquivo:
<?php
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
require 'vendor/autoload.php';
$app = AppFactory::create();
$handler = function (Request $request, Response $response) {
return $response->withStatus(204);
};
$app->map(['POST'], '/webhooks/sms', $handler);
$app->run();O próximo passo é que queremos algum tipo de comprovação de que o aplicativo recebeu um Webhook, o que não podemos fazer respondendo à solicitação da Vonage. As duas maneiras de fazer isso são usando um Logger ou configurando um banco de dados para armazenar os dados do Webhook. Para facilitar um pouco as coisas, vamos usar um Logger capaz de exibir a carga útil, que também podemos utilizar para executar alguma lógica no comprovante de entrega e gerar um valor para ele. Vamos usar o Monolog para fazer isso:
composer require monolog/monologEm seguida, implementamos a hidratação do Webhook e sua gravação em nosso arquivo de log no $handler:
<?php
use Monolog\Level;
use \Psr\Http\Message\ServerRequestInterface as Request;
use \Psr\Http\Message\ResponseInterface as Response;
use Slim\Factory\AppFactory;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
require 'vendor/autoload.php';
$app = AppFactory::create();
$logger = new Logger('sms');
$logger->pushHandler(new StreamHandler(__DIR__ . '/../log.txt', Level::Info));
$handler = function (Request $request, Response $response) use ($logger) {
$logger->info('Delivery Receipt Receieved:' . $sms->toArray());
return $response->withStatus(204);
};O aplicativo está pronto para uso: execute-o usando o servidor web integrado do PHP:
php -S 127.0.0.1:8000 -t src/ Instalando a CLI da Vonage
Usando um gerenciador de pacotes JavaScript, como npm ou yarn, instale a CLI da Vonage globalmente:
npm install -g @vonage/cliAgora, será necessário concluir duas configurações: você precisará configurar suas chaves de API no ngrok como parte do processo de configuração e seguir as instruções de configuração da Vonage para a CLI da Vonage.
Criação de um aplicativo
Precisaremos de uma instância do aplicativo Vonage tanto para autenticar nossas mensagens SMS enviadas quanto para redirecionar nossos webhooks de volta para nosso aplicativo. Tudo isso será feito pela CLI do Vonage. Crie um aplicativo no terminal:
Primeiro, crie o aplicativo:
vonage apps create "My App"Em seguida, habilite a funcionalidade “Mensagens”:
vonage apps capabilities update <your-app-id> messages \
--messages-inbound-url=https://example.com/webhooks/inbound \
--messages-status-url=https://example.com/webhooks/statusAdicionamos example.com como um espaço reservado por enquanto, pois a CLI irá gerenciar nossos domínios, como você verá mais adiante.
Como usar o túnel da Vonage
Para permitir que a Vonage envie webhooks para o seu aplicativo Slim, você precisará expor seu servidor de desenvolvimento local à internet. Uma maneira simples de fazer isso é usando o ngrok. Embora seja possível executar o ngrok diretamente, a CLI da Vonage oferece um wrapper prático que simplifica o processo de configuração e torna a experiência geral de desenvolvimento mais tranquila.
Você pode usar o função para abrir seu aplicativo e receber webhooks com o seguinte comando:
vonage tunnel ngrok <your-app-id>O que esse comando faz é bastante útil. Em vez de simplesmente iniciar um túnel ngrok para o seu aplicativo, ele também atualiza a configuração do webhook do seu aplicativo para usar a URL temporária do ngrok em vez do seu domínio atual (por exemplo, substituindo https://example.com por https://3d3daF.ngrok.com).
Isso mantém os caminhos dos webhooks existentes e apenas troca o domínio; portanto, endpoints como /webhooks/inbound e /webhooks/status continuam funcionando sem nenhuma configuração adicional.
Quando você interrompe o túnel do ngrok, o comando tenta automaticamente restaurar as URLs originais dos seus webhooks, retornando seu aplicativo à configuração anterior.
Configurar SMS de saída
Em seguida, precisamos enviar uma mensagem. Você poderia fazer isso com um comando, implementando uma CLI como a CLI do Symfony, mas será mais fácil acessar uma nova POST rota que receba a mensagem a ser enviada e o número de destino na carga útil. Também precisamos instalar e configurar o Client SDK PHP da Vonage. O Client SDK PHP também requer um cliente HTTP compatível com PSR-7; portanto, instalaremos primeiro o cliente HTTP do Symfony e, em seguida, o Client SDK PHP da Vonage.
composer require symfony/http-client
composer require vonage/client-core Uma rota para envio de SMS
Precisamos de uma nova rota que envie um SMS, o que significa que precisamos criar um controlador (se formos seguir uma configuração típica de framework PHP). Esses arquivos devem ficar em uma pasta própria:
mkdir src/Controller
touch ./src/Controller/SMSController.phpAgora, configure a rota no seu index.php ponto de entrada:
// make sure you import the controller (this is an example for how my PSR-4 is working, replace yours appropriately)
use JSeconde\BlogMessagesDeliveryReceipts\Controller;
// then, at the bottom of the file
$app->get('/send', SMSController::send);Nesse controlador, vamos configurar o cliente Vonage e enviar um SMS. Quando você acionar essa rota, a mensagem será enviada e, em seguida, seu aplicativo receberá os recibos de entrega em outra rota nova. Abra o controlador e escreva o código:
public function __invoke(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
{
$params = $request->getQueryParams();
$message = $params['message'] ?? null;
if (!$message) {
$response->getBody()->write(json_encode(['error' => 'message query parameter is required']));
return $response->withHeader('Content-Type', 'application/json')->withStatus(400);
}
$privateKey = file_get_contents(__DIR__ . '/../../private.key');
$applicationId = $_ENV['VONAGE_APPLICATION_ID'];
$vonage = new Client(new Keypair($privateKey, $applicationId));
$sms = new SMSText(
to: $_ENV['VONAGE_TO'],
from: $_ENV['VONAGE_FROM'],
message: $message
);
$result = $vonage->messages()->send($sms);
$response->getBody()->write(json_encode(['message_uuid' => $result['message_uuid'] ?? null]));
return $response->withHeader('Content-Type', 'application/json');
}
}Esse controlador só funcionará depois que você tiver criado um arquivo .env com o ID do seu aplicativo, um número de origem e um número de destino. Você também precisará colocar o seu private.key baixado do painel de controle na pasta raiz do seu código.
Este código utiliza a biblioteca ENV do PHP; portanto, instale-a:
composer require vlucas/phpdotenvEm seguida, crie seu .env arquivo na raiz do projeto:
touch .envInsira suas variáveis:
VONAGE_TO=<device-number>
VONAGE_FROM=VonageDemo
VONAGE_APPLICATION_ID=<your-app-id>Ao acionar esse controlador, agora será enviado um SMS, o que acionará um Webhook da Vonage para o seu túnel, além de /webhooks/status como caminho. Ainda não configuramos isso, então adicione um novo método ao seu SMSController e faça com que ele grave o status de entrega da mensagem recebida no seu arquivo de log.
public function receive(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
{
$body = (string) $request->getBody();
$logger->info('Webhook status received', json_decode($body, true) ?? ['raw' => $body]);
return $response->withStatus(200);
}A última coisa a fazer é configurar sua rota para chamar o novo método do controlador em seu index.php :
$controller = new TestController($logger);
$app->get('/test', $controller);
$app->post('/webhook/status', [$controller, 'receive']);Pronto. Acesse seu endpoint de envio e veja os recibos de entrega chegarem ao seu webhooks.txt arquivo de log!
Conclusão
Já vinculamos o envio e o recebimento de dados por SMS, mas há muito mais que você pode fazer. Por exemplo, você pode adicionar uma lógica de roteamento com base no conteúdo da notificação, de modo que uma mensagem com falha possa ser colocada na fila para tentar um novo envio. Alternativamente, se você configurar seu aplicativo PHP para armazenar grandes quantidades de dados, poderá configurar o Event Sourcing usando uma biblioteca como Laravel Verbs para registrar e reproduzir seu histórico de envios com números individuais.
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.
Compartilhar:
Sou ator formado, com uma dissertação sobre stand-up comedy, e comecei a me dedicar ao desenvolvimento em PHP por meio dos encontros da comunidade. Você pode me encontrar dando palestras e escrevendo sobre tecnologia, ou ouvindo e comprando discos curiosos da minha coleção de vinil.