Automatização do WhatsApp com Python
- Como trabalhar com a API do WhatsApp usando Python;
- Integração com o Whapi.Cloud para automatizar diversas tarefas;
- Uso de webhooks para lidar com mensagens e responder automaticamente;
- Conectando seu bot do WhatsApp ao ChatGPT para conversas com inteligência artificial;

Para facilitar, você pode usar nossos scripts prontos de bots em Python, que publicamos no GitHub. Esses projetos explicam detalhadamente o processo de configuração e teste, com comentários úteis dentro do código. É um excelente ponto de partida para desenvolvedores iniciantes.
Preparação para o desenvolvimento do bot
- Python. Instale o Python, se ainda não estiver instalado. Baixe a versão mais recente (recomendada 3.6 ou superior) do site oficial e siga as instruções.
- Flask. Flask é um framework leve para Python que usaremos para configurar o servidor e processar webhooks. Você pode instalar o Flask com o seguinte comando: pip install Flask
- Token da API. Registre-se no Whapi.Cloud para obter um token da API. Esse token permitirá que seu bot interaja com o WhatsApp por meio da API. Após o registro, você receberá um canal gratuito com alguns limites, suficiente para testar seu desenvolvimento. O Whapi.Cloud se destaca por sua estabilidade, baixo custo e ampla funcionalidade. As instruções para obter o token estão descritas abaixo.
- Webhook configurado. Para que o bot processe mensagens recebidas e eventos do WhatsApp, você precisará de um URL do servidor (local ou externo) para lidar com notificações do WhatsApp. O artigo explica em detalhes como fazer isso e onde obter esse link.
Obtendo o token para a API do WhatsApp
Registro e conexão de número
- 1. Acesse o painel de controle e abra a página do canal Default Channel, que já foi criado para você.
- 2. No primeiro passo, você verá um QR Code com instruções.
- 3. Abra o WhatsApp no seu dispositivo, vá para Configurações → Dispositivos conectados → Conectar dispositivo → Escanear QR Code.
- 4. Após a conexão bem-sucedida, atribua um nome ao canal (por exemplo, "Meu Chatbot") para facilitar o trabalho no futuro.




Obtendo o token da API

Ferramentas para trabalhar com a API
- Hub amigável para desenvolvedores: Plataforma especializada com documentação e exemplos que fornecem trechos de código para todos os endpoints em diferentes linguagens de programação.
- Coleção Postman: Solicitações prontas para testar a API usando o Postman.
- Arquivo Swagger: Descrição detalhada de todos os métodos da API, com a possibilidade de testar diretamente na página do canal.
O que é um Webhook e como configurá-lo?
O que é um webhook?
- Notificações instantâneas. Todos os eventos são processados praticamente em tempo real.
- Alta capacidade. A velocidade de recebimento das notificações é limitada apenas pelo desempenho do seu servidor.
- Flexibilidade. Você pode receber apenas os eventos que realmente precisa, como: Mensagens privadas; Mensagens em grupos; Mudanças nos status das mensagens; Alterações de participantes em grupos; Notificações de chamadas perdidas; Status de canais e muito mais.
Como e onde obter o URL para o webhook?
- 1) Baixe o Ngrok do site oficial e descompacte-o. Agora, abra o terminal e navegue até a pasta onde o Ngrok está armazenado.
- 2) Execute ./ngrok http PORTA, substituindo PORTA pela porta em que seu servidor Flask está rodando localmente (por exemplo, 80).
- 3) Agora você terá um URL público que poderá usar como URL para o webhook. Este é o link que você deve copiar para uso posterior.


Configuração do webhook no canal
- Vá para as configurações do canal. Na página do canal, clique no botão de configurações (no canto superior direito).
- Configure o webhook. Insira seu URL na seção de webhooks, usando as configurações pré-selecionadas. Você pode configurar vários webhooks para eventos diferentes, se necessário. Além disso, essas configurações podem ser alteradas via API.
- Salve as alterações. Após isso, todas as notificações de eventos do WhatsApp serão enviadas para o servidor especificado.
Criando a base para o bot do WhatsApp em Python
Flask==3.0.0
requests==2.27.1
requests-toolbelt==0.9.1
python-dotenv==0.20.0
pip install -r requirements.txt
API_TOKEN=8FjpwmyFUulh7emXOprrET3xKrwJ984O # API token from your channel
API_URL=https://gate.whapi.cloud # API endpoint URL
PORT=80 # example, 80 or 443
#URL_LINK= The Webhook link to your server {link to server}/hook.
from dotenv import load_dotenv
import os
load_dotenv()
api_token = os.getenv("API_TOKEN")
Envio de uma mensagem de texto
import requests
# URL for sending text messages. Can be pulled from .env
url = "https://gate.whapi.cloud/messages/text"
# Data for sending a message
payload = {
"to": "919984351847", # Enter the recipient's number in international format
"body": "Hello! This is a test message." # Text of message
}
# Headers, including authorization token
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": f"Bearer {api_token}" # Use the token from the .env file
}
# Sending a POST request
response = requests.post(url, json=payload, headers=headers)
# Output server response
print(response.status_code)
print(response.text)
Recebendo mensagens por meio do Flask Webhook
from flask import Flask, request, jsonify
app = Flask(__name__)
# Route for processing incoming messages
@app.route('/hook', methods=['POST'])
def webhook():
# Retrieving data from a request
data = request.json
# Logging an incoming message
print("Received message:", data)
# Example of incoming message processing
if "messages" in data:
for message in data["messages"]:
sender = message["from"] # Sender's number
text = message.get("body", "") # Text of message
print(f"Message from {sender}: {text}")
# Logic for replying to a message
# Check out our examples on GitHub, where we use more branching on commands for the bot
if text.lower() == "hello":
send_response(sender, "Hi there! How can I help you?")
elif text.lower() == "bye":
send_response(sender, "Goodbye!")
return jsonify({"status": "success"}), 200
# Function for sending a reply
def send_response(to, body):
import requests
url = "https://gate.whapi.cloud/messages/text"
payload = {
"to": to,
"body": body
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": f"Bearer {api_token}" # Use the token from the .env file
}
response = requests.post(url, json=payload, headers=headers)
print(f"Response to {to}: {response.status_code}, {response.text}")
if __name__ == '__main__':
app.run(host='0.0.0.0', port=80)
Funcionalidades avançadas
Envio de imagens
import requests
url = "https://gate.whapi.cloud/messages/image"
payload = {
"to": "919984351847",
"media": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg",
"caption": "An example image"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Envio de arquivos
import requests
url = "https://gate.whapi.cloud/messages/document"
payload = {
"to": "919984351847",
"media": "data:application/pdf;base64,JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVGVybXMgb2YgU2VydmljZSBXaGFwaS5DbG91ZCkKL0NyZWF0b3IgKE1vemlsbGEvNS4wIFwoV2luZG93cyBOVCAxMC4wOyBXaW42NDsgeDY0XCkgQXBwbGVXZWJLaXQvNTM3LjM2IFwoS0h............",
"filename": "Terms of Service Whapi.Cloud.pdf",
"caption": "Hello, I am attaching an important file to my message"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Criação de um grupo do WhatsApp em Python
import requests
url = "https://gate.whapi.cloud/groups"
payload = {
"participants": ["919984351847", "919984351848", "919984351849"],
"subject": "Group Subject 3"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Integração com o ChatGPT: IA para o seu bot do WhatsApp
Etapa 1: Adicionar dependências do ChatGPT
openai>=1.91.0,<2.0.0
httpx>=0.28.1,<1.0.0
httpcore>=1.0.9,<2.0.0
- openai - SDK oficial para enviar requisições à OpenAI e obter respostas do ChatGPT.
- httpx - uma biblioteca HTTP moderna e assíncrona da qual o openai depende internamente para fazer chamadas à API.
- httpcore - uma biblioteca de transporte de rede de baixo nível usada pelo httpx. Precisa ser fixada explicitamente para evitar conflitos de versão.
pip install -r requirements.txt
Etapa 2: Obtenha sua chave da API da OpenAI
OPENAI_API_KEY=your_api_key_here
Etapa 3: Adicione a lógica de IA ao seu bot
- - recebe eventos de webhook recebidos do Whapi.Cloud,
- - detecta se a mensagem começa com /ai,
- - envia a solicitação do usuário ao ChatGPT via API da OpenAI,
- - retorna a resposta gerada pela IA ao usuário no WhatsApp.
# Import necessary libraries for web server, HTTP requests, OpenAI API, environment variables, and .env file loading
from flask import Flask, request, jsonify # Flask is used to create the web server and handle HTTP requests
import requests # Used to send HTTP requests to the WhatsApp API
from openai import OpenAI # OpenAI client for interacting with ChatGPT
import os # For accessing environment variables
from dotenv import load_dotenv # For loading variables from a .env file
# Load environment variables from a .env file into the environment
load_dotenv()
# Create a Flask web application instance
app = Flask(__name__)
# Retrieve required configuration values from environment variables
API_TOKEN = os.getenv("API_TOKEN") # Token for authenticating with WhatsApp API
API_URL = os.getenv("API_URL") # Base URL for WhatsApp API
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") # API key for OpenAI
# Ensure all required environment variables are set, otherwise stop the program with an error
if not API_TOKEN or not API_URL or not OPENAI_API_KEY:
raise RuntimeError("Missing required environment variables: API_TOKEN, API_URL, or OPENAI_API_KEY")
# Initialize the OpenAI client with the provided API key
openai_client = OpenAI(api_key=OPENAI_API_KEY)
# Function to send a prompt to ChatGPT and get a response
# Takes a string prompt and returns the model's reply as a string
def ask_openai(prompt):
response = openai_client.chat.completions.create(
model="gpt-3.5-turbo", # Specify which OpenAI model to use
messages=[{"role": "user", "content": prompt}] # Provide the user's message to the model
)
# Extract and return the text of the model's reply
return response.choices[0].message.content.strip()
# Function to send a text message to a WhatsApp user via the WhatsApp API
# 'to' is the recipient's chat ID, 'body' is the message text
def send_message(to, body):
headers = {
"Authorization": f"Bearer {API_TOKEN}", # Add authentication token to the request
"Content-Type": "application/json" # Specify that we're sending JSON data
}
payload = {"to": to, "body": body} # Prepare the message data
# Send the message to the WhatsApp API endpoint
response = requests.post(f"{API_URL}/messages/text", json=payload, headers=headers)
print("Whapi response:", response.status_code, response.text) # Log the API response for debugging
# Define a webhook endpoint to receive incoming WhatsApp messages
@app.route("/hook/messages", methods=["POST"])
def webhook():
data = request.json # Parse the incoming JSON data
print("Incoming:", data) # Log the incoming data for debugging
# Loop through all received messages (could be more than one in a single webhook call)
for msg in data.get("messages", []):
if msg.get("from_me"):
continue # Skip messages sent by the bot itself
sender = msg.get("chat_id") # Get the sender's chat ID
# Safely extract the message text, handling cases where 'text' might be missing
text = (msg.get("text") or {}).get("body", "").strip()
# If the message starts with '/ai ', treat it as a prompt for ChatGPT
if text.lower().startswith("/ai "):
prompt = text[4:].strip() # Extract the user's prompt after '/ai '
if not prompt:
send_message(sender, "Please provide a prompt after /ai.") # Ask user to provide a prompt
else:
try:
reply = ask_openai(prompt) # Get response from ChatGPT
send_message(sender, reply) # Send the response back to the user
except Exception as e:
send_message(sender, f"Error: {e}") # Inform user if something went wrong
else:
# If the message doesn't start with '/ai ', send instructions to the user
send_message(sender, "Hi! To ask me something, type:\n/ai your question")
# Respond to WhatsApp API to confirm receipt of the webhook
return jsonify({"status": "received"})
# Optional: health check endpoint to verify the bot is running
@app.route("/", methods=["GET"])
def index():
return "Bot is running"
# Function to register the webhook URL with the WhatsApp API
def register_webhook():
if os.getenv("BOT_URL"):
headers = {"Authorization": f"Bearer {API_TOKEN}"}
payload = {
"webhooks": [
{
"url": os.getenv("BOT_URL"), # The public URL where Whapi should send messages
"events": [{"type": "messages", "method": "post"}], # Listen for message events
"mode": "method"
}
]
}
# Register the webhook
response = requests.patch(f"{API_URL}/settings", json=payload, headers=headers)
print("Webhook setup:", response.status_code, response.text) # Log the result
# If this script is run directly (not imported), start the bot
if __name__ == "__main__":
register_webhook() # Optionally register the webhook on startup
port = int(os.getenv("PORT", 80)) # Use the PORT environment variable or default to 80
app.run(host="0.0.0.0", port=port) # Start the Flask web server, accessible from any network interface
Resolução de problemas
Bot não responde a mensagens recebidas
- Certifique-se de que você está enviando mensagens para o número em que o bot está ativo, de outro telefone. O bot não poderá responder mensagens enviadas do mesmo número.
- Se o bot não responder a mensagens de outros números, verifique o funcionamento dos webhooks. Use serviços de simulação de webhooks, como o Webhook.site, para confirmar como as solicitações de callback estão chegando. Depois, verifique se o caminho corresponde ao configurado por você. Além disso, certifique-se de que seu servidor responde com 200Ok.
Bot envia mensagens sem parar
Bot funciona em alguns chats, mas não em outros
Deploy e uso de servidores
Firebase
- Crie um projeto no Firebase Console;
- Instale o Firebase CLI, seguindo as instruções;
- Initialize o Firebase no diretório do seu projeto usando o comando firebase init;
- Implante seu bot usando o comando firebase deploy --only functions.
AWS (Amazon Web Services)
- Registre-se ou entre no Console de Gerenciamento da AWS;
- Crie uma nova função Lambda através do console da AWS, escolhendo o API Gateway como gatilho;
- Carregue o código do seu bot na função Lambda;
- Configure o API Gateway para interação do seu bot com o mundo externo.
Heroku
- Crie uma conta no Heroku;
- Instale o Heroku CLI e faça login;
- Crie um novo aplicativo no Heroku através do console ou usando o comando heroku create;
- Associe seu repositório Git ao Heroku e faça o deploy usando os comandos git push heroku master;
- Configure o URL do webhook fornecido pelo Heroku.