Compartilhar:
){kind=small}
Ashley é uma desenvolvedora web freelance especializada em Laravel que adora contribuir com projetos de código aberto, criar sistemas interessantes e ajudar outras pessoas a aprender sobre desenvolvimento web.
Envie mensagens pelo WhatsApp no Laravel com o SDK nativo da Vonage
Tempo de leitura: 11 minutos
Em suas aplicações Laravel, talvez você queira entrar em contato com seus usuários pelo WhatsApp. Seja para enviar notificações aos seus usuários ou, talvez, divulgar promoções de vendas a possíveis clientes em potencial. A possibilidade de enviar mensagens diretamente para os celulares dos seus usuários e se comunicar com eles pode ser uma ferramenta extremamente poderosa em seu arsenal.
No entanto, a comunicação direta com a API do WhatsApp pode, às vezes, ser um pouco complicada. Portanto, em vez de fazer isso, podemos usar o Vonage para cuidar do envio das mensagens e da comunicação com a API do WhatsApp.
A Vonage é uma plataforma de comunicações em nuvem que oferece uma variedade de APIs que permitem que você se comunique com seus usuários por SMS, voz, WhatsApp e muito mais. Ela oferece uma maneira prática de enviar mensagens pelo WhatsApp sem precisar se preocupar com a complexidade subjacente da API do WhatsApp. Ela também conta com um pacote para Laravel que facilita muito a integração com sua aplicação Laravel.
Neste tutorial, veremos como você pode enviar mensagens pelo WhatsApp usando o Laravel e o Vonage.
Ao usar o WhatsApp, há vários aspectos que você deve levar em conta no que diz respeito aos tipos de mensagens que pode enviar e quando pode enviá-las.
Para tentar reduzir a quantidade de spam que as empresas podem enviar às pessoas, uma empresa (como a sua) pode apenas iniciar uma conversa com um usuário enviando um “modelo de mensagem” (MTM). Os MTMs são mensagens pré-aprovadas que você precisa criar no WhatsApp Business Manager e que precisam ser aprovadas pelo WhatsApp antes que você possa usá-las.
Os MTMs oferecem parâmetros que permitem personalizar as mensagens enviadas aos usuários. Por exemplo, é possível criar um MTM com o seguinte conteúdo:
Hello {{1}}. Your order {{2}} has been shipped.Se usássemos "John" como primeiro parâmetro e "1234" como segundo parâmetro, a mensagem que seria enviada ao usuário seria:
Hello John. Your order 1234 has been shipped.No entanto, se o usuário enviar uma mensagem para você primeiro, você poderá responder a ele dentro de um prazo de 24 horas sem precisar usar um MTM.
O WhatsApp oferece um período de atendimento ao cliente de 24 horas. Dentro desse período, uma empresa pode enviar mensagens livremente a um usuário final, sem a necessidade de enviar uma mensagem padrão.
O período de 24 horas pode ser iniciado de duas maneiras diferentes:
O usuário responde a um MTM enviado pela empresa.
O usuário envia uma mensagem para a empresa.
Então, como você pode ver, o prazo de 24 horas exige a participação do usuário na conversa.
Se nenhuma mensagem for enviada dentro do prazo de 24 horas, esse prazo expirará e você precisará iniciar um novo.
Antes de começarmos a trabalhar com qualquer coisa relacionada a código, você precisa primeiro se certificar de que possui um Account ativo do WhatsApp Business com um número de telefone configurado.
Você também precisará ter um Account na Vonage. Se ainda não tiver um, pode se cadastrar aqui. Depois de criar o Account, você precisará obter sua chave API e seu segredo no painel de controle da Vonage.
Depois de fazer isso, você poderá acessar a página “Contas externas” no seu painel do Vonage. Lá, você poderá conectar sua conta do WhatsApp à sua conta do Vonage. Será necessário seguir as etapas para vincular as duas contas.
Depois de fazer isso, seu account da Vonage já deve estar conectado ao WhatsApp e pronto para uso.
Se você tiver alguma dificuldade para configurar seu account da Vonage ou conectar seu account do WhatsApp Business, vale a pena conferir a documentação da Vonage para obter mais informações.
Agora que nosso account da Vonage está pronto para uso, podemos começar a configurar nossa aplicação Laravel para utilizá-la. Para começar, precisaremos instalar o pacote Vonage para Laravel usando o Composer. Você pode fazer isso executando o seguinte comando na raiz do seu projeto:
Depois que o pacote estiver instalado, podemos publicar o arquivo de configuração do pacote. Isso nos permitirá configurar nossa chave e nosso segredo da API da Vonage. Você pode fazer isso executando o seguinte comando:
Para os fins deste tutorial, vou partir do pressuposto de que o mesmo número de telefone é usado sempre que quisermos enviar uma mensagem pelo WhatsApp; portanto, vamos definir nosso número de telefone do WhatsApp no meu .env arquivo. Para fazer isso, também precisaremos adicionar um novo campo de configuração para que possamos recuperar o número de telefone no código do nosso aplicativo. Vou colocar esse novo campo de configuração no meu config/services.php arquivo:
return [
// ...
'vonage' => [
'whatsapp' => [
'from_phone_number' => env('WHATSAPP_PHONE_NUMBER'),
],
],
// ...
];
Assim, poderemos recuperar esse valor no código do nosso aplicativo usando config('services.vonage.whatsapp.from_phone_number').
Agora que criamos nossos novos campos de configuração, podemos adicionar nosso número de telefone, chave de API e segredo de API ao nosso .env arquivo:
É isso aí! Estamos prontos para começar a enviar mensagens pelo WhatsApp.
Agora que nossa aplicação está pronta, podemos começar a enviar mensagens pelo WhatsApp aos nossos usuários.
Como já discutimos anteriormente, se uma empresa quiser iniciar um novo período de 24 horas e abrir uma conversa com o usuário, ela precisará primeiro enviar um MTM.
Para enviar um MTM, você precisará localizar seu “espaço de nomes de modelos” no WhatsApp Business Manager. Isso é necessário para que você possa identificar qual modelo deseja enviar, já que o mesmo nome de modelo pode ser usado por outras pessoas em todo o mundo.
Ao enviar sua mensagem, você precisará concatenar o namespace do modelo com o nome do modelo, usando : como separador. Por exemplo, digamos que o namespace do seu modelo seja abc123 e o nome do seu modelo é sample_issue_resolution. Você deveria então concatenar esses dois valores para obter abc123:sample_issue_resolution como o nome completo do modelo, que você passará para a Vonage.
Como exemplo, vamos considerar um dos modelos de mensagem que o WhatsApp nos oferece. O modelo se chama sample_issue_resolution e tem a seguinte estrutura:
Hi {{1}}, were we able to solve the issue that you were facing?Esse modelo nos permite passar o nome do usuário como um único parâmetro. Portanto, se quiséssemos enviar essa mensagem ao usuário, precisaríamos fazer o seguinte:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppTemplate;
use Vonage\Messages\MessageObjects\TemplateObject;
$toNumber = '447123456789';
$locale = 'en_US';
$templateName = 'abc_123:sample_issue_resolution';
$templateParams = [
'John',
];
$whatsAppMessage = new WhatsAppTemplate(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
templateObject: new TemplateObject(
name: $templateName,
parameters: $templateParams,
),
locale: $locale,
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução desse código resultaria no envio de uma mensagem para o número de telefone +447123456789 com o seguinte formato:
Hi John, were we able to solve the issue that you were facing?Como você pode ver no exemplo de código, primeiro precisamos criar um novo WhatsAppTemplate objeto e especificar:
O número de telefone para o qual o modelo está sendo enviado.
O número de telefone do qual o modelo está sendo enviado.
O objeto de modelo, que contém o nome do modelo e os parâmetros.
A localidade do modelo.
Depois de criarmos nosso WhatsAppTemplate objeto, podemos enviá-lo usando o Vonage Client.
Você também deve ter notado que estamos passando um locale parâmetro para o WhatsAppTemplate objeto. Isso ocorre porque o WhatsApp permite criar modelos de mensagem em vários idiomas. Por exemplo, se tivéssemos o mesmo modelo em inglês e em espanhol, poderíamos enviar a versão em inglês passando en_US como localidade (conforme mostrado no exemplo acima) e a versão em espanhol passando es como localidade. Portanto, se passássemos es como localidade, o usuário receberia a seguinte mensagem:
Hola, Ashley. ¿Pudiste solucionar el problema que tenías?Esse é um recurso realmente poderoso que pode ser útil caso você precise oferecer comunicação internacional a partir do seu aplicativo. Por exemplo, você poderia usá-lo para oferecer suporte aos seus usuários em vários idiomas.
Supondo que você esteja dentro do prazo de 24 horas do atendimento ao cliente, também é possível enviar mensagens de texto de formato livre a partir do seu aplicativo Laravel. Para isso, você precisará criar um novo WhatsAppText objeto e passá-lo para o Vonage Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppText;
$toNumber = '447123456789';
$message = 'Hello, this is a test message.';
$whatsAppMessage = new WhatsAppText(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
text: $message,
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código acima resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 com o seguinte conteúdo:
Hello, this is a test message.
Com o Vonage, você também pode enviar imagens aos seus usuários. Para isso, será necessário criar um novo WhatsAppImage objeto e passá-lo para o Vonage Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppImage;
use Vonage\Messages\MessageObjects\ImageObject;
$toNumber = '447123456789';
$imageUrl = 'https://example.com/image.png';
$caption = 'This is an example image.';
$whatsAppMessage = new WhatsAppImage(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
image: new ImageObject(
url: $imageUrl,
caption: $caption,
),
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código a seguir resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 que contém uma imagem com a legenda “Esta é uma imagem de exemplo.”.
Você também pode enviar mensagens de Video a partir do seu aplicativo Laravel. Para isso, será necessário criar um novo WhatsAppVideo objeto e passá-lo para o Vonage Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppVideo;
use Vonage\Messages\MessageObjects\VideoObject;
$toNumber = '447123456789';
$videoUrl = 'https://example.com/video.mp4';
$whatsAppMessage = new WhatsAppVideo(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
videoObject: new VideoObject(
url: $videoUrl,
),
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código a seguir resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 que contém um Video.
Com o Vonage, você também pode enviar mensagens de áudio a partir do seu aplicativo Laravel. Para isso, será necessário criar um novo WhatsAppAudio objeto e passá-lo para o método Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppAudio;
use Vonage\Messages\MessageObjects\AudioObject;
$toNumber = '447123456789';
$audioUrl = 'https://example.com/audio.mp3';
$whatsAppMessage = new WhatsAppAudio(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
audioObject: new AudioObject(
url: $audioUrl,
),
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código a seguir resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 que contém um arquivo de áudio.
Você também pode querer enviar arquivos aos seus usuários a partir do seu aplicativo Laravel. Para isso, será necessário criar um novo WhatsAppFile objeto e passá-lo para o Vonage Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppFile;
use Vonage\Messages\MessageObjects\FileObject;
$toNumber = '447123456789';
$fileUrl = 'https://example.com/file.pdf';
$caption = 'This is an example file.';
$whatsAppMessage = new WhatsAppFile(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
fileObject: new FileObject(
url: $fileUrl,
caption: $caption,
),
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código a seguir resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 que contém um arquivo com a legenda “Este é um arquivo de exemplo.”.
Em alguns casos (como ao fornecer instruções de como chegar), você também pode querer enviar localizações aos seus usuários. Para isso, será necessário criar um novo WhatsAppLocation objeto e passá-lo para o Vonage Client:
use Vonage\Client;
use Vonage\Messages\Channel\WhatsApp\WhatsAppCustom;
$toNumber = '447123456789';
$longitude = -40.34764;
$latitude = -74.18875;
$name = Vonage HQ';
$address = '23 Main Street, Holmdel, NJ 07733';
$whatsAppMessage = new WhatsAppCustom(
to: $toNumber,
from: config('services.vonage.whatsapp.from_phone_number'),
custom: [
'type' => 'location',
'location' => [
'longitude' => $longitude,
'latitude' => $latitude,
'name' => $name,
'address' => $address,
],
],
);
app(Client::class)
->messages()
->send($whatsAppMessage);
A execução do código a seguir resultaria no envio de uma mensagem pelo WhatsApp para o número de telefone +447123456789 que contém um local com o nome “Vonage HQ” e o endereço “23 Main Street, Holmdel, NJ 07733”.
Esperamos que este artigo tenha lhe dado uma ideia de como você pode enviar diferentes tipos de mensagens pelo WhatsApp a partir do seu aplicativo Laravel usando o Vonage. Você também deve ter entendido como funcionam os modelos de mensagens do WhatsApp e o prazo de 24 horas que você tem para enviar as mensagens.