Crie um chatbot do WhatsApp com Twilio WhatsApp API, PHP e Laravel

Tempo de leitura: 6 minutos

March 06, 2020

Escrito por

Contribuidor

Crie um chatbot do WhatsApp com Twilio WhatsApp API, PHP e Laravel

Crie um chatbot com Twilio WhatsApp API, PHP e Laravel

Muitas vezes, conversas com familiares e amigos sobre assuntos delicados podem acabar em discussões. Ironicamente, muitas dessas conversas não ocorrem mais pessoalmente, mas em tempo real por meio de aplicativos de bate-papo, como o WhatsApp.

Quando essas situações complicadas ocorrem, você pode precisar verificar um fato ou procurar rapidamente algumas informações. Em geral, você precisaria abrir seu navegador da Web, o que poderia ser um inconveniente quando o tempo é essencial. Em uma vida perfeita, seria melhor se conectar a um chatbot e usá-lo para obter informações. Com serviços como a API da Twilio para WhatsApp, você pode criar soluções personalizadas como essas para dar um up na sua experiência de bate-papo.

Neste tutorial, criaremos um Chatbot simples do WhatsApp que permite obter informações sobre o perfil do GitHub de um desenvolvedor usando apenas seu nome de usuário.

Depois de concluir este tutorial, você terá aprendido a responder às mensagens do WhatsApp enviadas para seu número de WhatsApp da Twilio e também como enviar mensagens de formato livre usando a API WhatsApp da Twilio.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

Conhecimento básico do Laravel
Laravel instalado no computador local
Composer instalado globalmente
Conta da Twilio
Número da Twilio habilitado para WhatsApp

Primeiros passos

Este tutorial usará Laravel. Primeiro, comece criando um novo projeto Laravel usando o Instalador Laravel. Abra um terminal e execute o seguinte comando para gerar um novo aplicativo Laravel:

$ laravel new whatsapp-chatbot && cd whatsapp-chatbot

Em seguida, você precisará do SDK da Twilio e do cliente HTTP Guzzle para, respectivamente, interagir com a API da Twilio para WhatsApp e fazer solicitações HTTP. Ambos os pacotes podem ser instalados usando o Composer. Abra um terminal que aponte para o diretório whatsapp-chatbot e execute os seguintes comandos para instalá-los:

$ composer require twilio/sdk
$ composer require guzzlehttp/guzzle

Em seguida, vá para o dashboard da Twilio e copie o ACCOUNT SID (SID DA CONTA) e o AUTH TOKEN (TOKEN DE AUTENTICAÇÃO) que serão usados para autenticar suas solicitações com o SDK da Twilio:

Continue atualizando suas variáveis ambientais com essas credenciais. Abra seu arquivo .env e adicione as seguintes variáveis:

TWILIO_SID="ACCOUNT_SID"
TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN"

Configure o WhatsApp Sandbox

Como você já deve ter notado, para permitir que seu chatbot responda às mensagens recebidas, você deve ter uma maneira de enviar mensagens via WhatsApp. Felizmente, a Twilio fornece uma API do WhatsApp muito robusta, que permite enviar e receber mensagens do WhatsApp diretamente em seu aplicativo.

Antes de começar a enviar e receber mensagens usando a API WhatsApp da Twilio em produção, você deve primeiro obter um número de WhatsApp aprovado pela Twilio, que funcionará como seu número do WhatsApp para enviar e receber mensagens. Como a aprovação de um número da Twilio pode levar dias, a Twilio também fornece um sandbox, que pode ser usado para fins de desenvolvimento e teste.

Para começar a usar o Sandbox da Twilio para WhatsApp, vá para a seção WhatsApp em seu painel da Twilio e envie uma mensagem para o número do sandbox fornecido; geralmente +14155238886 com o código fornecido, que está no formato join-(unable word):

Depois de enviar seu código para o número do sandbox, você deverá receber uma resposta como esta:

Em seguida, atualize seu arquivo .env para incluir número WhatsApp, nesse caso, o número do sandbox:

TWILIO_WHATSAPP_NUMBER="+14155238886"

Como criar o Chatbot

A esta altura, você já deve ter a configuração do sandbox da Twilio e também os pacotes necessários para criar o chatbot. Agora, crie um Controlador, que abrigará a lógica do chatbot. Abra um terminal no diretório do projeto e execute o seguinte comando para gerar uma nova classe de Controlador:

$ php artisan make:controller ChatBotController

Abra o arquivo app/HTTP/Controllers/ChatBotController.php gerado recentemente e faça as seguintes alterações:

<?php

namespace App\Http\Controllers;

use GuzzleHttp\Exception\RequestException;
use Illuminate\Http\Request;
use Twilio\Rest\Client;

class ChatBotController extends Controller
{
    public function listenToReplies(Request $request)
    {
        $from = $request->input('From');
        $body = $request->input('Body');

        $client = new \GuzzleHttp\Client();
        try {
            $response = $client->request('GET', "https://api.github.com/users/$body");
            $githubResponse = json_decode($response->getBody());
            if ($response->getStatusCode() == 200) {
                $message = "*Name:* $githubResponse->name\n";
                $message .= "*Bio:* $githubResponse->bio\n";
                $message .= "*Lives in:* $githubResponse->location\n";
                $message .= "*Number of Repos:* $githubResponse->public_repos\n";
                $message .= "*Followers:* $githubResponse->followers devs\n";
                $message .= "*Following:* $githubResponse->following devs\n";
                $message .= "*URL:* $githubResponse->html_url\n";
                $this->sendWhatsAppMessage($message, $from);
            } else {
                $this->sendWhatsAppMessage($githubResponse->message, $from);
            }
        } catch (RequestException $th) {
            $response = json_decode($th->getResponse()->getBody());
            $this->sendWhatsAppMessage($response->message, $from);
        }
        return;
    }

    /**
     * Sends a WhatsApp message  to user using
     * @param string $message Body of sms
     * @param string $recipient Number of recipient
     */
    public function sendWhatsAppMessage(string $message, string $recipient)
    {
        $twilio_whatsapp_number = getenv('TWILIO_WHATSAPP_NUMBER');
        $account_sid = getenv("TWILIO_SID");
        $auth_token = getenv("TWILIO_AUTH_TOKEN");

        $client = new Client($account_sid, $auth_token);
        return $client->messages->create($recipient, array('from' => "whatsapp:$twilio_whatsapp_number", 'body' => $message));
    }
}

Dois novos métodos foram adicionados à classe; listenToReplies() e sendWhatsAppMessage(). Vamos detalhar cada função. O método listenToReplies() é onde as mensagens enviadas para seu número WhatsApp serão processadas. A resposta enviada dependerá do body da mensagem recebida. Sempre que uma nova mensagem for recebida, a Twilio chamará o ponto de extremidade vinculado a esse método, enquanto passa informações sobre a mensagem como o corpo da solicitação. No corpo da solicitação, você pode obter detalhes sobre a mensagem que um usuário enviou para seu número de WhatsApp, que está entre os parâmetros From e Body, que contêm o número de telefone e a mensagem de envio, respectivamente:

$from = $request->input('From');
$body = $request->input('Body');

Em seguida, uma solicitação HTTP é feita para a API do desenvolvedor do GitHub usando a biblioteca HTTP do Guzle (instalada na parte anterior deste tutorial) para obter os detalhes do usuário usando o nome de usuário obtido do corpo da mensagem do WhatsApp. Dependendo da resposta recuperada na solicitação HTTP, uma mensagem do WhatsApp será enviada de volta ao usuário com um resumo do perfil do usuário ou uma mensagem de erro. A função auxiliar sendWhatsAppMessage() é usada para enviar mensagens do WhatsApp. São necessários dois argumentos: $message e $recipient.

O método sendWhatsAppMessage() usa o SDK da Twilio para enviar mensagens do WhatsApp:

public function sendWhatsAppMessage(string $message, string $recipient)
    {
        $twilio_whatsapp_number = getenv('TWILIO_WHATSAPP_NUMBER');
        $account_sid = getenv("TWILIO_SID");
        $auth_token = getenv("TWILIO_AUTH_TOKEN");

        $client = new Client($account_sid, $auth_token);
        return $client->messages->create($recipient, array('from' => "whatsapp:$twilio_whatsapp_number", 'body' => $message));
    }

Primeiro, suas credenciais da Twilio armazenadas no arquivo .env são recuperadas antes de continuar a criar uma nova instância do Twilio Client usando seu account SID (SID de conta) e auth token (token de autenticação). Em seguida, o destinatário e uma matriz de opções são passados para o método messages->create() da instância do cliente para realmente enviar uma solicitação por meio da API da Twilio. O método messages->create() usa dois argumentos; o destinatário, que é o número de telefone habilitado para WhatsApp para o qual você deseja enviar uma mensagem – nesse caso, o remetente do texto inicial – e uma matriz associativa com as chaves: from e body. A propriedade from deve ser seu número de telefone da Twilio para WhatsApp ou número do sandbox (somente para teste) com o texto whatsapp: anexado a ele, enquanto a propriedade body contém $message a ser enviada ao destinatário.

OBSERVAÇÃO: o número do destinatário também deve ter o prefixo de texto whatsapp: anexado a ele, mas nesse caso, o número recuperado do corpo da solicitação já o tem como parte da string retornada para a propriedade From, por isso não o inserimos manualmente.

Configure o Webhook

Para permitir que seu aplicativo receba mensagens enviadas para seu número de WhatsApp, você deve primeiro adicionar um URL do webhook ao seu painel da Twilio. Antes de poder fazer isso, você deve ter configurado sua rota de aplicativo, que servirá como seu URL do webhook. Abra routes/api.php e faça as seguintes alterações para adicionar uma nova rota (/chat-bot) ao seu aplicativo:

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| Here is where you can register API routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| is assigned the "api" middleware group. Enjoy building your API!
|
 */

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

Route::post('/chat-bot', 'ChatBotController@listenToReplies');

OBSERVAÇÃO:

Rotas definidas em rotas/api.php usam o grupo de middleware da API.
As rotas definidas em routes/api.php serão prefixadas com /api.

Como expor o aplicativo à Internet

Para permitir o acesso a seu aplicativo Laravel através de um webhook, o seu aplicativo tem de ser acessível pela Internet. Como ele ainda está sendo criado, você pode fazer uso do ngrok para torná-lo acessível na Internet.

Se você não tiver o ngrok configurado no seu computador, veja como fazê-lo seguindo as instruções na página de downloads oficial da empresa. Em seguida, abra o terminal e execute os seguintes comandos para iniciar o aplicativo Laravel:

$ php artisan serve

Isso mostrará o aplicativo Laravel em execução em sua máquina local em uma porta específica, que será impressa para o terminal após a execução bem-sucedida do comando. Anote a porta, pois ela será usada em breve. Agora, enquanto ainda estiver executando o comando artisan serve, abra outra instância do seu terminal e execute este comando para tornar seu aplicativo publicamente acessível:

$ ngrok http 8000

NOTA: substitua 8000 pela porta em que seu aplicativo está sendo executado.

Após a execução do comando acima, você verá uma tela como esta:

Anote o URL Forwarding, pois o utilizaremos em seguida.

Como atualizar o Webhook do Sandbox

Depois de expor seu aplicativo à Internet, agora você pode usar sua rota de aplicativo como o URL do webhook para seu sandbox do WhatsApp. Acesse as configurações de sandbox do WhatsApp no painel da Twilio e atualize o campo de entrada "WHEN A MESSAGE COMES IN" (QUANDO UMA MENSAGEM ENTRAR) com o URL completo para o caminho do chatbot:

NOTA: o URL do webhook deve estar no formato https://{ngrok-forwarding-url}/api/chat-bot

Teste

Incrível! Você criou seu aplicativo de chatbot. Agora, faça o teste enviando uma mensagem de WhatsApp para o número do sandbox com um nome de usuário do Github. Se tudo funcionar como esperado, você receberá uma resposta com um resumo do perfil da pessoa e um link para visualizar o perfil diretamente:

Conclusão

Agora que você concluiu este tutorial, tem um chatbot simples para WhatsApp para procurar o perfil de um usuário no Github. Com isso, você também aprendeu a enviar mensagens de formato livre usando a API WhatsApp da Twilio e também como responder a mensagens enviadas para o seu número de WhatsApp da Twilio. Se você quiser dar uma olhada no código-fonte completo deste tutorial, ele está disponível no Github.

Esta também é uma ótima introdução para criar o chatbot que você precisa para acalmar as discussões familiares mais tensas. Você pode estender esse chatbot para se comunicar com suas APIs favoritas para que esteja pronto para o próximo debate.

Este artigo foi traduzido do original "Build a WhatsApp Chatbot with Twilio WhatsApp API, PHP, and Laravel". Enquanto melhoramos nossos processos de tradução, adoraríamos receber seus comentários em help@twilio.com - contribuições valiosas podem render brindes da Twilio.

Publicações relacionadas

Recursos relacionados

Twilio Docs

De APIs a SDKs e aplicativos de amostra

Documentação de referência de API, SDKs, bibliotecas auxiliares, guias de início rápido e tutoriais para sua linguagem e plataforma.

Centro de Recursos

Os mais recentes e-books, relatórios do setor e webinars

Aprenda com especialistas em engajamento do cliente para melhorar sua própria comunicação.

Ahoy

Centro da comunidade de desenvolvedores da Twilio

Melhores práticas, exemplos de código e inspiração para criar comunicações e experiências de engajamento digital.