Como enviar mensagens pelo WhatsApp com o Laravel

Se você não está familiarizado com a Messages API, é possível enviar texto, imagens e Video para o Facebook Messenger, Viber, WhatsApp e também pelo canal mais básico de SMS. A Vonage oferece um ambiente de testes (sandbox) para você experimentar esses recursos; portanto, neste tutorial, vamos usá-lo para testar o envio de mensagens pelo WhatsApp usando um aplicativo Laravel de demonstração que já configurei.

Pré-requisitos

Vamos tentar deixar isso o mais simples possível. Você vai precisar de:

• PHP 8.3 ou superior

• Compositor

• git

• ngrok

• Um Account da API da Vonage

Como clonar o código do repositório

Usando a linha de comando, clone o código do aplicativo:

git clone git@github.com:Vonage-Community/blog-messages-laravel.git

Copie o .env.example como .env para criar nosso arquivo de variáveis de ambiente:

cd blog-messages-laravel
cp .env.example .env

E, por fim, instale as dependências com o Composer:

composer install

Como configurar o painel do Vonage

Primeiro, vamos precisar de um ID de aplicativo para enviar mensagens. Acesse o Painel da Vonage e crie um novo aplicativo:

Hit 'create a new Application' to get started

Dê um nome à sua aplicação usando um identificador (por exemplo, laravel-messages) e ative o recurso “Mensagens”. Você precisará adicionar dois webhooks aqui, mas como não vamos usá-los de fato, pode inserir placeholders fictícios, por exemplo: https://www.example.com

Clique em “Gerar chave pública e privada”. Você perceberá que um private.key será gerado: mova-o para o diretório raiz do código do seu aplicativo. Anote o ID do aplicativo que foi criado: precisaremos dele em breve.

Com isso, as configurações das Applications estão prontas; agora precisamos configurar o Sandbox.

Acesse esta página ou acesse-a usando a barra lateral esquerda em Troubleshoot & Learn > Developer Tools > Messages Sandboxe siga as instruções para criar uma sandbox do WhatsApp escaneando o código QR.

Scan the QR code and follow the instructions to enable the Sandbox

Para uma solução totalmente integrada à produção, você precisaria de um Account do WhatsApp Business (WABA) registrado na Meta. O que o ambiente de teste permite é que você use um Account WABA temporário — agora seu número estará em uma lista de permissões, com um número predefinido vinculado aos servidores da Vonage.

Depois que o número estiver configurado, você pode rolar a página para baixo até um exemplo de código cURL que fornece o número do remetente a ser usado:

Take note of the from number in this panel

Configurar o ambiente da aplicação

Quando criamos o .env arquivo, você vai perceber que há três variáveis para preencher:

VONAGE_APPLICATION_ID=
VONAGE_PRIVATE_KEY_PATH=
VONAGE_FROM_NUMBER=

Agora já devemos ter esses três. O from número foi criado na etapa anterior; insira-o private.key como nosso caminho (o código do aplicativo usa a função auxiliar do Laravel base_path() para determinar o caminho completo; portanto, se você quiser mover a chave para uma estrutura de diretórios diferente, deve definir o caminho de forma relativa à raiz). Nosso ID do aplicativo pode ser copiado do Painel do Vonage, onde criamos o aplicativo do Vonage.

Inicie o aplicativo

Nada de coisas sofisticadas como Vela ou Herd aqui: vamos simplesmente usar o servidor PHP embutido que o Laravel encapsula:

php artisan serve

E devemos acessar a linda página de destino navegando até localhost:8000:

A Splash Screen for true Artisans

Não temos como fazer com que os servidores da Vonage nos enviem webhooks de mensagens recebidas; portanto, para obter uma URL pública, vamos usar o ngrok para mapear nossa aplicação Laravel em execução:

ngrok http 8000

Ngrok up and running

Agora você tem uma URL pública! A última etapa da configuração é criar nossos webhooks; portanto, volte para o Sandbox de Mensagens no Painel de Controle da Vonage. Pegue a URL pública que temos e adicione /webhooks/status e /webhooks/inbound aos campos correspondentes:

Configure your Webhooks here

Experimente!

Acesse localhost:8000/message e mande uma mensagem!

Hit Submit to watch the magic

Our sandbox is working as expected

Como isso funciona?

É hora de mergulhar no código. Toda a lógica está apenas no routes/web.php arquivo, em vez de nos controladores, para manter as coisas simples. Duas rotas importantes a serem analisadas constituem as partes essenciais do aplicativo. Primeiro, a rota de mensagens de saída:

Route::post('/message', static function(Request $request) {
   $number = $request->input('number');
   $fromNumber = config('vonage.from_number');
   $text = 'Hello from Vonage and Laravel :) Please reply to this message with a number between 1 and 100';
   $message = new Vonage\Messages\Channel\WhatsApp\WhatsAppText($number, $fromNumber, $text);

   $credentials = new Keypair(file_get_contents(config('vonage.private_key_path')), config('vonage.application_id'));
   $client = new Vonage\Client($credentials);
   $client->messages()->getAPIResource()->setBaseUrl('https://messages-sandbox.nexmo.com/v1/messages');
   $client->messages()->send($message);

   return view('thanks');
});

Este é o formulário e a solicitação POST ao enviar a mensagem inicial. A única função dessa rota é pegar o número inserido no formulário e enviar uma mensagem pelo WhatsApp. Se você está se perguntando como enviamos isso para a Vonage, a resposta está no SDK PHP da Vonage. O objeto Client SDK recebe um objeto de credenciais (neste caso, uma instância de Keypair), para o qual passamos as variáveis de ambiente Application ID e Private Key path, que criamos anteriormente, para o construtor.

$credentials = new Keypair(file_get_contents(config('vonage.private_key_path')), config('vonage.application_id'));
$client = new Vonage\Client($credentials);

Para obter mais informações sobre como usar o SDK do PHP, consulte o arquivo ReadMe , que traz exemplos de uso da Messages API. Para enviar uma mensagem, criamos um objeto WhatsAppText, passamos o número de destino e o número do sandbox from configurado anteriormente.

Antes de enviarmos a mensagem pelo cliente, há uma etapa importante específica para o nosso caso de uso:

$client->messages()->getAPIResource()->setBaseUrl('https://messages-sandbox.nexmo.com/v1/messages');

Esta linha aqui aproveita a natureza desacoplada do SDK do PHP (todas as partes do SDK podem ser reconfiguradas ou substituídas) para extrair o objeto APIResource configurado para produção e sobrescrevê-lo com a URL do ambiente de teste. Assim, tudo o que o cliente precisa fazer agora é enviá-lo:

$client->messages()->send($message);

Como receber uma mensagem no WhatsApp

A segunda parte consiste em programar uma rota que monitore os webhooks recebidos da Vonage — esses serão acionados sempre que alguém responder ao tópico que criamos na primeira etapa. Aqui está o endpoint:

Route::post('/webhooks/inbound', static function(Request $request) {
   $data = $request->all();
   $number = (int)$data\['text'];

   if ($number > 0) {
       $randomNumber = random_int(1, 8);
       $respondNumber = $number * $randomNumber;
       $toNumber = $data\['from'];
       $fromNumber = config('vonage.from_number');
       $text = "The answer is " . $respondNumber . ", we multiplied by " . $randomNumber . ".";
       $message = new Vonage\Messages\Channel\WhatsApp\WhatsAppText($toNumber, $fromNumber, $text);

   $credentials = new Keypair(file_get_contents(config('vonage.private_key_path')), config('vonage.application_id'));
   $client = new Vonage\Client($credentials);
   $client->messages()->getAPIResource()->setBaseUrl('https://messages-sandbox.nexmo.com/v1/messages');
   $client->messages()->send($message);
});

Aqui, extraímos os detalhes necessários para responder à mensagem — ou seja, o número de telefone para o qual devemos responder e o número que o remetente enviou como parte da mensagem. Com essas informações, o número enviado é multiplicado por um número aleatório entre 1 e 8, e enviamos uma resposta com a mesma estrutura da mensagem inicial.

Conclusão

E aí está: maneiras de interagir usando o WhatsApp no Vonage! Como você pode imaginar, esse tipo de configuração é ideal para chatbots automatizados, como uma linha de atendimento, mas o que você vai criar? Conte para a gente no Slack da Comunidade Vonage, rentre em contato pelo X, antes conhecido como Twitter. ou entre em contato comigo no Mastodon.

Mais recursos

• Encontre o código funcional no GitHub

• Referência da Messages API

• Guia da Sandbox da Messages API

• Mãos à obra! Como limpar seu aplicativo PHP com o PHPStan

• Envio de um SMS por meio de uma API PHP com o SlimPHP