Adicionando o WhatsApp Flows à experiência do seu chatbot
Mais empresas do que nunca usam chatbots via WhatsApp para interagir com clientes, entender suas necessidades e reunir dados essenciais. No entanto, esse processo de coletar e organizar dados pode apresentar desafios em termos de eficiência. Conheça o WhatsApp Flows.
Integrar chatbots ao WhatsApp Flows permite que as empresas interpretem as informações recebidas do cliente de forma mais eficaz. Os chatbots podem iniciar fluxos específicos personalizados para a coleta de dados, dependendo do contexto dessa conversa.
Neste tutorial, você criará um chatbot usando Llama 2 e Python, conectando-o ao WhatsApp Flows para melhorar seus recursos de coleta de dados. Dessa forma, você verá como o WhatsApp Flows facilita ainda mais para o usuário a experiência do chatbot e aprimora a precisão e a eficiência da coleta de dados do cliente.
Melhorando a experiência do chatbot com o WhatsApp Flows
Seu chatbot responderá às solicitações e aos comandos do usuário com o WhatsApp Flows para a coleta de dados. Mais especificamente, ele permitirá que os usuários conversem com o chatbot, pesquisem informações sobre serviços oferecidos por um hotel fictício na Espanha e entrem em contato com a empresa para suporte.
O chatbot usará instruções if simples juntamente com o modelo padrão Llama 2 para fornecer acesso a uma base de conhecimento geral suficiente.
Etapas para seguir
Parte 1:
Crie fluxos usando o configurador de fluxos do Gerenciador do WhatsApp.
Parte 2:
Faça a conversão do modelo Llama 2 de GGML para GGUF.
- Escreva o código Python para integrar o Flows e o chatbot.
- Crie um webhook para ouvir as mensagens.
- Execute o app.
Parte 1: como criar fluxos
Aqui, você usará o Configurador de fluxo para criar fluxos. Como alternativa, você pode usar a API de Fluxos. No entanto, não falaremos dela neste artigo.
Pré-requisitos para a parte 1
Para conseguir acompanhar o tutorial, você deve ter:
O ngrok instalado.
Uma conta de desenvolvedor verificada no Meta for Developers e conhecer a API de Nuvem hospedada pela Meta.
Por fim, você deve concluir as etapas necessárias para usar os fluxos. Também é possível ver uma prévia do código do projeto concluído.
Começar
Para começar, navegue até a página Fluxos na sua conta do WhatsApp Business. Se essa for a sua primeira interação com os fluxos, você verá o botão Começar a criar fluxos. Caso contrário, haverá um botão Criar fluxo à direita da página.
Clique no botão exibido para abrir uma caixa de diálogo onde você pode inserir mais detalhes sobre seu fluxo:
O fluxo de dúvidas sobre serviços
Primeiro, você criará um fluxo que permite que o usuário busque informações sobre serviços oferecidos pela empresa de hotéis.
Insira um nome no campo Nome. Depois, no menu Categorias, escolha Cadastrar-se e deixe o menu Modelo definido para Nenhum. Clique em Enviar.
A próxima página exibirá um editor à esquerda e uma prévia à direita.
Substitua o conteúdo do editor pela marcação JSON para seu fluxo. (Você pode saber mais sobre o JSON de fluxo na documentação do desenvolvedor.)
Salve o fluxo. Sua prévia deve ser semelhante à imagem abaixo:
O fluxo contém uma tela que permite que o usuário insira suas informações, selecione os serviços de interesse e uma mensagem adicional opcional. Quando o usuário clica em Enviar, o fluxo fecha e envia os dados coletados para sua empresa para tratamento. Um método de transmitir esses dados envolve o uso de pontos de extremidade. No entanto, esse projeto não precisa de um ponto de extremidade. Os dados serão transmitidos para o mesmo webhook que alimenta o chatbot.
Essa transferência pode ser realizada usando ações. Você pode definir os dados para que eles sejam movidos para a próxima tela usando o objeto payload:
...
"on-click-action": {
"name": "complete",
"payload": {
"firstname": "${form.first_name}",
"secondname": "${form.second_name}",
"services_interested": "${form.services_interested}",
"additional_info": "${form.additional_info}",
"flow_key": "agentconnect"
}
}
...
No trecho, a ação do usuário de clicar no botão aciona o on-click-action, coletando os dados na carga. Depois, ela envia a carga ao servidor do seu webhook e fecha o fluxo via ação complete.
Você pode atribuir as chaves payload como faria com qualquer variável. Os valores correspondentes podem representar objetos de dados ou nomes de componentes de fluxo (semelhante a um atributo de nome para o formulário HTML).
Agora, você pode ver o fluxo em ação e simular uma experiência de usuário real usando o botão Prévia interativa:
Depois de testar, você pode publicar o fluxo, pois no momento ele está no estado de rascunho. Para isso, abra o menu à direita de Salvar e clique em Publicar. O fluxo agora está pronto e pode ser usado.
O fluxo de fale conosco
Agora, criará um fluxo "fale conosco".
Comece repetindo o mesmo processo de criação inicial do fluxo. Para a categoria, escolha Fale conosco. Substitua o conteúdo do editor pela marcação JSON para renderizar o seguinte:
Publique o fluxo e avance para a próxima seção para configurar um chatbot. A seção apresenta três funções (send_message, flow_details, e flow_reply_processor) que contêm lógica vital para enviar os fluxos aos usuários. A seção também inclui a lógica para processar cargas recebidas de fluxo. Portanto, recomendamos analisá-la mesmo se já tiver criado um chatbot.
Parte 2: como configurar o chatbot
Depois, você configurará o chatbot e o integrará aos seus fluxos.
Pré-requisitos para a parte 2
Antes de continuar, você deve ter:
Conhecimento básico e uma versão recente do Python
A versão HuggingFace do Llama 2 baixada. O modelo HuggingFace Llama 2 não requer ferramentas adicionais nem hardware especializado. Você também pode usar a versão oficial, mas ela necessita de configuração adicional.
O token de acesso à sua conta e a identificação do seu número de telefone
Um editor de código
Usando Python para integrar fluxos e chatbot
O chatbot vai operar por meio de um script predefinido criado para ajudar usuários com base nos dados inseridos por eles. Na interação inicial, ele oferece um texto de saudação personalizado e um menu baseado em texto dependendo da mensagem do usuário. Essas opções atendem a necessidades específicas: fazer perguntas sobre os serviços oferecidos pelo hotel, entrar em contato com um dos agentes ou interagir com chatbot com tecnologia da Llama.
Responder a um caractere alfanumérico conectará o usuário ao serviço ou ação correspondente. No entanto, qualquer outra resposta aciona a funcionalidade padrão do chatbot, que ajuda com perguntas gerais ou guia o usuário quanto aos serviços disponíveis com base em mais conversas.
Para começar, crie um ambiente virtual executando o comando abaixo no seu terminal:
python -m venv venv
Ative-o:
source venv/bin/activate
Depois, instale os pacotes obrigatórios:
pip install requests flask llama-cpp-python python-dotenv
Use Flask para criar rotas e interagir com a API, requests para enviar solicitações da internet, llama-cpp-python para interagir com o modelo e python-dotenv para carregar variáveis de ambiente.
Depois, crie um arquivo de ambiente chamado .env e o conteúdo a seguir, atribuindo os valores de forma adequada. (Você pode usar qualquer cadeia de caracteres para o TOKEN.)
TOKEN =
ACCESS_TOKEN =
PHONE_NUMBER_ID =
No mesmo diretório, crie um arquivo chamado main.py e comece adicionando os pacotes que você usará:
import os
import re
import time
import uuid
import requests
from dotenv import load_dotenv
from flask import Flask, request, make_response, json
from llama_cpp import Llama
Agora, inicialize as variáveis e as classes. O trecho também inicia o Flask e chama o método load_dotenv() para ajudar a carregar as variáveis:
app = Flask(__name__)
load_dotenv()
PHONE_NUMBER_ID = os.getenv('PHONE_NUMBER_ID')
url = f"https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}/messages"
TOKEN = os.getenv('TOKEN')
ACCESS_TOKEN = os.getenv('ACCESS_TOKEN')
code_prompt_texts = ["Contact us", "Chat with our chatbot", "YES", "NO"]
service_list = [
"Accommodation Services",
"Spa Services",
"Dining Services",
"Recreational Facilities",
"Business & Conference Services",
"Transportation Services",
"Accessibility Services",
"Pet-Friendly Services"
]A lista de serviços service_list armazena os serviços oferecidos pelo hotel. A lista code_prompt_texts contém as opções correspondentes às escolhas do usuário, que são 1, 2, Y e N usando a função abaixo. A função abaixo ajudará a mapear as respostas do usuário de acordo com a opção correspondente.
def extract_string_from_reply(user_input):
match user_input:
case "1":
user_prompt = code_prompt_texts[0].lower()
case "2":
user_prompt = code_prompt_texts[1].lower()
case "Y":
user_prompt = code_prompt_texts[2].lower()
case "N":
user_prompt = code_prompt_texts[3].lower()
case _:
user_prompt = str(user_input).lower()
return user_prompt
O código converte as cadeias de caracteres para letras minúsculas a fim de evitar correspondências erradas ao executar a lógica condicional. A estrutura match…case corresponde o comando inserido pelo usuário às ações resultantes. Por exemplo, se o usuário digitar "1", isso acionará a funcionalidade "Contact us".
Depois, a função seguinte contém uma instrução if que usa o pacote Python RegEx, re, para pesquisar certos termos de uma mensagem do cliente a fim de decidir qual tipo de resposta enviar ao usuário:
def user_message_processor(message, phonenumber, name):
user_prompt = extract_string_from_reply(message)
if user_prompt == "yes":
send_message(message, phonenumber, "TALK_TO_AN_AGENT", name)
elif user_prompt == "no":
print("Chat terminated")
else:
if re.search("service", user_prompt):
send_message(message, phonenumber, "SERVICE_INTRO_TEXT", name)
elif re.search(
"help|contact|reach|email|problem|issue|more|information", user_prompt
):
send_message(message, phonenumber, "CONTACT_US", name)
elif re.search("hello|hi|greetings", user_prompt):
if re.search("this", user_prompt):
send_message(message, phonenumber, "CHATBOT", name)
else:
send_message(message, phonenumber, "SEND_GREETINGS_AND_PROMPT", name)
else:
send_message(message, phonenumber, "CHATBOT", name)
Agora, uma mensagem como "Hello there" vai disparar o método send_message com SEND_GREETINGS_AND_PROMPT como segundo argumento. Abaixo, confira o método send_message. Substitua o conteúdo entre <xxx> adequadamente.
def send_message(message, phone_number, message_option, name):
greetings_text_body = (
"\nHello "
+ name
+ ". Welcome to our hotel. What would you like us to help you with?\nPlease respond with a numeral between 1 and 2.\n\n1. "
+ code_prompt_texts[0]
+ "\n2. "
+ code_prompt_texts[1]
+ "\n\nAny other reply will connect you with our chatbot."
)
# loading the list's entries into a string for display to the user
services_list_text = ""
for i in range(len(service_list)):
item_position = i + 1
services_list_text = (
f"{services_list_text} {item_position}. {service_list[i]} \n"
)
service_intro_text = f"We offer a range of services to ensure a comfortable stay, including but not limited to:\n\n{services_list_text}\n\nWould you like to connect with an agent to get more information about the services?\n\nY: Yes\nN: No"
contact_flow_payload = flow_details(
flow_header="Contact Us",
flow_body="You have indicated that you would like to contact us.",
flow_footer="Click the button below to proceed",
flow_id=str("<FLOW-ID>"),
flow_cta="Proceed",
recipient_phone_number=phone_number,
screen_id="CONTACT_US",
)
agent_flow_payload = flow_details(
flow_header="Talk to an Agent",
flow_body="You have indicated that you would like to talk to an agent to get more information about the services that we offer.",
flow_footer="Click the button below to proceed",
flow_id=str("<FLOW-ID>"),
flow_cta="Proceed",
recipient_phone_number=phone_number,
screen_id="TALK_TO_AN_AGENT",
)
match message_option:
case "SEND_GREETINGS_AND_PROMPT":
payload = json.dumps(
{
"messaging_product": "whatsapp",
"to": str(phone_number),
"type": "text",
"text": {"preview_url": False, "body": greetings_text_body},
}
)
case "SERVICE_INTRO_TEXT":
payload = json.dumps(
{
"messaging_product": "whatsapp",
"to": str(phone_number),
"type": "text",
"text": {"preview_url": False, "body": service_intro_text},
}
)
case "CHATBOT":
LLM = Llama(
model_path="/home/incognito/Downloads/llama-2-7b-chat.ggmlv3.q8_0.gguf.bin",
n_ctx=2048,
)
# create a text prompt
prompt = message
# generate a response (takes several seconds)
output = LLM(prompt)
payload = json.dumps(
{
"messaging_product": "whatsapp",
"to": str(phone_number),
"type": "text",
"text": {
"preview_url": False,
"body": output["choices"][0]["text"],
},
}
)
case "CONTACT_US":
payload = contact_flow_payload
case "TALK_TO_AN_AGENT":
payload = agent_flow_payload
case "FLOW_RESPONSE":
payload = json.dumps(
{
"messaging_product": "whatsapp",
"to": str(phone_number),
"type": "text",
"text": {"preview_url": False, "body": message},
}
)
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer " + ACCESS_TOKEN,
}
requests.request("POST", url, headers=headers, data=payload)
print("MESSAGE SENT")Se a mensagem for uma simples saudação (SEND_GREETINGS_AND_PROMPT), a resposta vai conter comandos adicionais (greetings_text_body).
Da mesma forma, quando um usuário faz uma pergunta sobre os serviços oferecidos, uma mensagem de texto (service_intro_text) contendo os serviços é enviada ao usuário. Além dos serviços, ela também contém um comando para o usuário escolher se deseja falar com um agente.
Se a entrada requer uma resposta do chatbot (CHATBOT), você inicializa o modelo, alimenta-o com o conteúdo da mensagem e processa a resposta para enviar de volta ao usuário. FLOW_RESPONSE exibe uma resposta capturada do fluxo.
As outras opções, CONTACT_US e TALK_TO_AN_AGENT, enviam as cargas de fluxo para o usuário. As cargas do fluxo se originam da função flow_details, cujo corpo é mostrado abaixo. A carga incorpora detalhes essenciais do fluxo, incluindo o FLOW_ID, que você pode recuperar da página Fluxos da sua conta do WhatsApp Business. Também é possível definir essas identificações nas variáveis do ambiente.
def flow_details(flow_header,
flow_body,
flow_footer,
flow_id,
flow_cta,
recipient_phone_number,
screen_id
):
# Generate a random UUID for the flow token
flow_token = str(uuid.uuid4())
flow_payload = json.dumps({
"type": "flow",
"header": {
"type": "text",
"text": flow_header
},
"body": {
"text": flow_body
},
"footer": {
"text": flow_footer
},
"action": {
"name": "flow",
"parameters": {
"flow_message_version": "3",
"flow_token": flow_token,
"flow_id": flow_id,
"flow_cta": flow_cta,
"flow_action": "navigate",
"flow_action_payload": {
"screen": screen_id
}
}
}
})
payload = json.dumps({
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": str(recipient_phone_number),
"type": "interactive",
"interactive": json.loads(flow_payload)
})
return payload
Esse método cria a action.parameters.flow_token gerando um UUID aleatório. O action.parameters.flow_action_payload.screen é transmitido como parâmetro (screen_id). Idealmente, ele deve representar a identificação da tela inicial que você pretende mostrar para o usuário quando action.parameters.flow_cta é executado.
Por fim, adicione as rotas do webhook. A solicitação GET do webhook é iniciada ao adicionar o webhook ao app no Meta for Developers. Ela retorna o hub.challenge da solicitação quando bem-sucedida.
@app.route("/webhook", methods=["GET"])
def webhook_get():
if request.method == "GET":
if (
request.args.get("hub.mode") == "subscribe"
and request.args.get("hub.verify_token") == TOKEN
):
return make_response(request.args.get("hub.challenge"), 200)
else:
return make_response("Success", 403)
A solicitação POST extrai e processa a carga da mensagem usando o método user_message_processor introduzido anteriormente. Como o código só atende à carga da mensagem, ele vai gerar erros ao capturar qualquer outra carga. Por esse motivo, você pode usar uma instrução if para verificar se há um corpo messages.
@app.route("/webhook", methods=["POST"])
def webhook_post():
if request.method == "POST":
request_data = json.loads(request.get_data())
if (
request_data["entry"][0]["changes"][0]["value"].get("messages")
) is not None:
name = request_data["entry"][0]["changes"][0]["value"]["contacts"][0][
"profile"
]["name"]
if (
request_data["entry"][0]["changes"][0]["value"]["messages"][0].get(
"text"
)
) is not None:
message = request_data["entry"][0]["changes"][0]["value"]["messages"][
0
]["text"]["body"]
user_phone_number = request_data["entry"][0]["changes"][0]["value"][
"contacts"
][0]["wa_id"]
user_message_processor(message, user_phone_number, name)
else:
# checking that there is data in a flow's response object before processing it
if (
request_data["entry"][0]["changes"][0]["value"]["messages"][0][
"interactive"
]["nfm_reply"]["response_json"]
) is not None:
flow_reply_processor(request)
return make_response("PROCESSED", 200)
Além disso, você pode usar uma função auxiliar chamada flow_reply_processor para extrair uma resposta do fluxo e enviá-la para o usuário:
def flow_reply_processor(request):
request_data = json.loads(request.get_data())
name = request_data["entry"][0]["changes"][0]["value"]["contacts"][0]["profile"]["name"]
message = request_data["entry"][0]["changes"][0]["value"]["messages"][0]["interactive"]["nfm_reply"][
"response_json"]
flow_message = json.loads(message)
flow_key = flow_message["flow_key"]
if flow_key == "agentconnect":
firstname = flow_message["firstname"]
reply = f"Thank you for reaching out {firstname}. An agent will reach out to you the soonest"
else:
firstname = flow_message["firstname"]
secondname = flow_message["secondname"]
issue = flow_message["issue"]
reply = f"Your response has been recorded. This is what we received:\n\n*NAME*: {firstname} {secondname}\n*YOUR MESSAGE*: {issue}"
user_phone_number = request_data["entry"][0]["changes"][0]["value"]["contacts"][0][
"wa_id"]
send_message(reply, user_phone_number, "FLOW_RESPONSE", name)
Ela usa uma chave (flow_key) para diferenciar entre os dois fluxos e, assim, extrair as respostas adequadamente ao transmitir as primeiras identificações de tela corretas.
Antes de executar o código, compare-o com a versão completa e confirme se há correspondência entre tudo.
Como configurar o webhook
Antes de continuar, execute este comando do seu terminal:
flask --app main run --port 5000
Se tiver sucesso, você poderá usar a seguinte mensagem:
* Running on http://127.0.0.1:5000
Em seguida, execute ngrok http 5000 para obter um URL que mapeia seu app. Copie o link.
Depois, na conta de desenvolvedor do Meta for Developers, clique no menu Configuração sob WhatsApp no painel de navegação esquerdo:
No cartão Webhook, clique em Editar.
Depois, no campo URL de retorno na caixa de diálogo aberta, adicione o URL copiado e anexe o /webhook a ele.
Adicione a variável TOKEN do arquivo .env ao campo Verificar token. Clique em Verificar e salvar para fechar a caixa de diálogo.
Agora, no mesmo cartão, clique em Gerenciar e marque o campo mensagens. O cartão deve aparecer conforme segue:
Agora, o webhook está pronto.
Executando o app
Você pode enviar uma mensagem como "Olá" ao número da sua conta. Você receberá a resposta correspondente. Tente responder com um comando mostrado no menu para testar os fluxos:
Abaixo está outra captura de tela mostrando a resposta do chatbot. O usuário pede uma tradução rápida, que o bot pode fornecer.
Conclusão
O WhatsApp Flows é uma ferramenta poderosa para empresas coletarem informações estruturadas, melhorando as integrações do cliente e simplificando a comunicação entre empresas e consumidores. Uma das formas de criar fluxos é com o Configurador do fluxo do Gerenciador do WhatsApp, que oferece uma interface fácil de usar para a criação de fluxos.
Esse app de demonstração oferece um vislumbre de como você pode usar o WhatsApp Flows para melhorar o engajamento do cliente e a análise baseada em dados. Para usos mais especializados, você também pode configurar o Llama 2 e o WhatsApp Flows para conectar seu chatbot a um modelo personalizado ou treiná-lo em relação a fontes de dados proprietários, permitindo que ele responda a perguntas sobre seus produtos e outras funcionalidades usando uma linguagem natural.
Use o WhatsApp Flows para melhorar as integrações com seus clientes e simplifique a coleta de dados nos seus apps hoje mesmo. Experimente já.
Como reservar uma hora marcada com o WhatsApp Flows: criando um backend Node.js
Enabling developers to create innovative AIs on Messenger and WhatsApp
