Crie já

API do WhatsApp com Python: Enviar, Receber e Automatizar Mensagens

API do WhatsApp em PythonPython + API do WhatsApp

API do WhatsApp com Python: Enviar, Receber e Automatizar Mensagens

Tudo o que você precisa para usar o API do WhatsApp em Python: qual biblioteca escolher, como conectar uma conta vinculada com um código QR, como enviar e receber mensagens com solicitações e httpx, e como configurar um webhook do FastAPI para um bot ou agente de IA.
Construa com Python Ver a referência da API
API REST hoje, sem necessidade de verificação do Meta Business
send_whatsapp.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def send_whatsapp(chat_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() send_whatsapp("9f9uio56sopa456s", "Hello from Python!")
200 OK, mensagem enviada
Definição

O que é a API do WhatsApp em Python?

O API do WhatsApp em Python significa chamar o envio de mensagens do WhatsApp Business a partir de código Python em vez de clicar no WhatsApp Web. Um script Python ou serviço de backend envia uma requisição HTTP, geralmente com solicitações ou httpx, para uma API REST que expõe chats, mensagens e webhooks, seja a Cloud API da Meta diretamente ou um provedor unificado como o Unipile, que conecta o WhatsApp junto com LinkedIn, Instagram e Telegram por trás de uma única interface. A Meta não publica um SDK oficial do Python tudo-em-um para o WhatsApp, razão pela qual quase todas as integrações em Python neste guia, e a maior parte do que você encontrará no resto da web, se comunica diretamente com os endpoints REST.
Uma API REST para WhatsApp, LinkedIn, Instagram e Telegram
Vinculado com um código QR ou um código de pareamento, sem verificação do Meta Business
solicitações para scripts simples, httpx para assíncrono em escala
Para a camada de orientação, acesso, custo e limites, comece com o Guia de acesso, custos e limites da API do WhatsApp. Construir em PHP em vez de Python?
Leia a mesma integração em PHP
Antes de construir

O que você precisa antes de começar?

Você não precisa de uma conta do Meta Business ou de aprovação na Plataforma do WhatsApp Business para começar a enviar e receber mensagens a partir do Python. Você precisa de um ambiente Python funcional, um cliente HTTP, um local para receber webhooks e uma conta Unipile.
Python 3.9+
Corresponde à versão mínima exigida pelo próprio SDK Python do Unipile pydantic dependência, e pelo moderno httpx e os lançamentos do FastAPI.
requests ou httpx
pip install requests para chamadas síncronas, ou pip install httpx se você planeja enviar mensagens concorrentemente. Veja o solicitações e httpx documentação.
Um túnel local
Uma ferramenta como ngrok ou cloudflared para expor sua rota de webhook do FastAPI em uma URL HTTPS pública enquanto você desenvolve.
Token de Acesso e DSN
Ambos vêm do painel da Unipile. O DSN é o host que você chama, o Token de Acesso vai no X-API-KEY cabeçalho de cada requisição.
Crie sua primeira integração com o WhatsApp
Comparação de Bibliotecas

Qual biblioteca Python você deve usar para o WhatsApp?

Não há uma única resposta óbvia, e a maioria das postagens de blog sobre este tópico promove o pacote que seu autor mantém. Aqui está uma comparação factual das cinco maneiras pelas quais os desenvolvedores Python realmente chamam o WhatsApp hoje, desde automação de navegador até um provedor unificado, para que você possa escolher com base no que cada opção realmente faz, e não no marketing.
Biblioteca / abordagem
O que ele realmente chama
Verificação da Meta for Business
Mantido
Melhor para
pywhatkit
Controla o WhatsApp Web em uma aba do navegador (automação de teclado), não uma API do lado do servidor
N/A, sem API
Comunidade, esporádico
Scripts e demonstrações pontuais em uma máquina com tela, e não envio de produção
whatsapp-cloud-api
Envoltório Python leve para os endpoints da própria API do WhatsApp Cloud da Meta
Obrigatório
Wrapper da comunidade
Equipes já aprovadas na Cloud API que desejam um cliente em Python
whatsapp-api-client-python
Chama o SaaS da green-api, que por sua vez mantém a sessão do WhatsApp
Não é necessário
Mantido pelo fornecedor
Equipes confortáveis dependendo de um segundo fornecedor de SaaS de propósito único
solicitações, direto para a Meta
Endpoints da API da Nuvem da Meta, sem nenhum wrapper
Obrigatório
Faça você mesmo (DIY)
Equipes já aprovadas para a verificação do Meta Business que desejam controle total
Unipile, requests ou httpx
API de mensagens unificadas da Unipile, WhatsApp junto com LinkedIn, Instagram e Telegram
Não é necessário
Ativamente mantido, SDK em Python em beta
Produtos SaaS que conectam várias contas de WhatsApp de usuários finais em nome de cada usuário
pywhatkit
ChamadasExecuta o WhatsApp Web em uma aba do navegador, não uma API do lado do servidor
Verificação da MetaN/A, sem API
MantidoComunidade, esporádico
Melhor paraScripts avulsos e demos, não para envio em produção
whatsapp-cloud-api
ChamadasInvólucro leve em torno dos próprios endpoints da API Cloud da Meta
Verificação da MetaObrigatório
MantidoWrapper da comunidade
Melhor paraEquipes já aprovadas na Cloud API
whatsapp-api-client-python
ChamadasO SaaS green-api, que mantém a sessão do WhatsApp
Verificação da MetaNão é necessário
MantidoMantido pelo fornecedor
Melhor paraEquipes confortáveis com um segundo fornecedor de SaaS
solicitações, direto para a Meta
ChamadasEndpoints da API da Nuvem da Meta, sem wrapper
Verificação da MetaObrigatório
MantidoFaça você mesmo (DIY)
Melhor paraEquipes já aprovadas para a verificação do Meta Business
Unipile, requests ou httpx
ChamadasAPI de mensagens unificadas, WhatsApp com LinkedIn, Instagram, Telegram
Verificação da MetaNão é necessário
MantidoAtivamente mantido, SDK em Python em beta
Melhor paraProdutos SaaS que conectam muitas contas de usuários finais
Cada opção que mantém Verificação comercial da Meta obrigatória em última análise, conversa com a própria API do WhatsApp Cloud da Meta (veja Documentação da Plataforma do WhatsApp Business da Meta), o que é a escolha certa se você já opera um número comercial verificado. Se você estiver conectando contas do WhatsApp em nome de muitos usuários finais diferentes, por outro lado, um fluxo de código QR ou de pareamento remove essa etapa de verificação por completo, que é o modelo que o resto deste guia utiliza.
Conexão de conta

Como você conecta uma conta do WhatsApp em Python?

Cada chamada neste guia é executada em nome de um usuário autenticado que vinculou a sua própria conta do WhatsApp. Não há etapa de verificação do Meta Business: a partir do Python, você envia um único POST /api/v1/accounts pedido com provider definir para WHATSAPP, e o usuário confirma o link escaneando um código QR ou digitando um código de pareamento em seu telefone.
Opção A: Código QR (padrão)
Sair pareamento_de_numero_de_telefone do corpo da requisição e a Unipile retorna um ponto de controle contendo a carga útil do código QR. Renderize-o com uma biblioteca como QR code e exiba-o para o usuário escanear a partir de WhatsApp > Aparelhos conectados.
connect_qr.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN", "accept": "application/json"} def connect_whatsapp_qr() -> dict: response = requests.post( f"{BASE_URL}/accounts", headers=HEADERS, json={"provider": "WHATSAPP"}, ) response.raise_for_status() return response.json() account = connect_whatsapp_qr() print(account) # account contém um novo account_id e um objeto de ponto de verificação. # Exiba o ponto de verificação como um código QR e peça ao usuário para escaneá-lo # no WhatsApp > Dispositivos vinculados.
Opção B: código de pareamento
Passar pareamento_de_numero_de_telefone em dígitos E.164 apenas, código do país primeiro, sem sinal de mais, sem espaços. O Unipile retorna um ponto de verificação contendo um código curto que o usuário digita no WhatsApp em vez de escanear qualquer coisa, o que é mais adequado para um servidor sem cabeça (headless) sem tela para exibir um código QR.
connect_pairing_code.py
def connect_whatsapp_pairing_code(phone_e164_digits: str) -> dict: response = requests.post( f"{BASE_URL}/accounts", headers=HEADERS, json={ "provider": "WHATSAPP", "pairing_phone_number": phone_e164_digits, }, ) response.raise_for_status() return response.json() # Código do país + número, apenas dígitos, por exemplo, França account = connect_whatsapp_pairing_code("33612345678") # O checkpoint da conta contém o código de emparelhamento a ser exibido na sua interface de usuário. # O usuário o insere no WhatsApp > Dispositivos vinculados > Vincular com número de telefone.
Confirme que a conta está conectada
Assim que o usuário escaneia o código QR ou digita o código de pareamento, você precisa saber quando a conta está realmente pronta para enviar e receber. O Unipile oferece duas opções.
Consultar o status da conta
Chamar GET /api/v1/accounts/{account_id} a cada poucos segundos até que a conta não precise mais do seu ponto de verificação. Simples, mas desperdiça solicitações enquanto você espera.
Webhook de Status da Conta
Registrar um webhook com fonte definir para status_da_conta (mesmo POST /api/v1/webhooks endpoint usado para mensagens) e o Unipile envia {"AccountStatus": {"account_id": "...", "message": "OK"}} no instante em que a conta estiver pronta. É isso que a maioria das integrações de produção usa.
poll_status.py
import time def wait_for_connection(account_id: str, timeout_seconds: int = 120) -> dict: deadline = time.time() + timeout_seconds enquanto time.time() < prazo: resposta = requests.get(f"{BASE_URL}/accounts/{account_id}", cabeçalhos=HEADERS) response.raise_for_status() account = response.json() print(account) # analise a carga útil em tempo real para sua própria verificação de status time.sleep(2) raise TimeoutError("A conta do WhatsApp não confirmou a conexão a tempo")
Construir o fluxo de conexão
Enviar

Como você envia uma mensagem do WhatsApp com Python?

Enviar uma mensagem do WhatsApp a partir do Python é uma única chamada HTTP: POST /api/v1/chats/{chat_id}/messages, com o chat_id você já tem a partir da listagem de chats ou de um webhook de entrada, e um text campo. O endpoint aceita corpos codificados em formulário e em JSON, portanto, um simples requests.post com dados= funciona sem configuração adicional.
Se não houver nenhum existente chat_id, por exemplo, a primeira mensagem para um novo contato, ligar POST /api/v1/chats em vez de com um account_id e o do destinatário attendees_ids; O Unipile cria o chat 1:1 e envia a mensagem na mesma requisição.
send.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def send_message(chat_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() def start_chat(account_id: str, attendee_provider_id: str, text: str) -> dict: response = requests.post( f"{BASE_URL}/chats", headers=HEADERS, data={ "account_id": account_id, "attendees_ids": attendee_provider_id, "text": text, }, ) response.raise_for_status() return response.json()
Os tipos de mensagem (texto, mídia, notas de voz, modelos) e a janela de atendimento ao cliente de 24 horas constituem um tópico próprio, abordado integralmente no guia para tipos de mensagem que a API do WhatsApp suporta. Esta seção aborda apenas a infraestrutura em Python.
A Meta cobra pelas mensagens da API do WhatsApp por mensagem enviada, e não por conversa, desde julho de 2025. Veja Como funciona a precificação da API do WhatsApp por mensagem para as taxas atuais por país.
Concorrência

Como enviar mensagens do WhatsApp de forma assíncrona em Python?

Quando você envia para muitos destinatários de uma só vez, uma transmissão, um esvaziamento de fila, um trabalho de acompanhamento em massa, um loop que aguarda um requests.post por vez é o gargalo, não a API. httpx.AsyncClient combinado com asyncio.gather dispara muitas solicitações simultaneamente a partir de um único loop de eventos, sem necessidade de threads. Um semáforo é o que mantém você sendo um bom cidadão: as contas do WhatsApp ainda estão sujeitas aos próprios limites de taxa da plataforma, portanto, a concorrência sem limites apenas troca um loop lento por uma parede de respostas 429.
send_bulk_async.py
import asyncio import httpx BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} CONCURRENCY_LIMIT = 5 async def send_message_async( client: httpx.AsyncClient, semaphore: asyncio.Semaphore, chat_id: str, text: str, ) -> dict: async with semaphore: response = await client.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json() async def send_bulk(messages: list[tuple[str, str]]) -> list: semaphore = asyncio.Semaphore(CONCURRENCY_LIMIT) async with httpx.AsyncClient(timeout=30) as client: tasks = [ send_message_async(client, semaphore, chat_id, text) for chat_id, text in messages ] return await asyncio.gather(*tasks, return_exceptions=True) messages = [ ("9f9uio56sopa456s", "Your order shipped!"), ("a1b2c3d4e5f6g7h8", "Your order shipped!"), ] results = asyncio.run(send_bulk(messages)) for chat_id_text, result in zip(messages, results): if isinstance(result, Exception): print("failed:", chat_id_text[0], result)
Manter LIMITE_DE_CONCORRÊNCIA conservador e aumente-o apenas após observar as taxas de erro reais. return_exceptions=True o que significa que um envio falhado não cancela o resto do lote, o que importa assim que você estiver disparando centenas de mensagens em uma única execução. A seção de limite de taxa e nova tentativa abaixo se baseia nesse mesmo padrão.
Construa seu pipeline de envio
Webhooks

Como receber mensagens do WhatsApp com um webhook do FastAPI?

Um webhook é a forma como o seu serviço em Python fica sabendo sobre uma nova mensagem do WhatsApp no momento em que ela chega, em vez de fazer polling por ela. Você registra um endpoint no Unipile, e cada evento correspondente é entregue ao seu servidor como JSON. FastAPI combina naturalmente com o lado receptor: um pydantic o modelo valida o payload para você, e Tarefas em Segundo Plano faça sua rota retornar uma resposta imediatamente enquanto o trabalho real, chamando um modelo, escrevendo em um banco de dados, acontece depois.
1. Registre o webhook
Ponto request_url na sua rota FastAPI. Durante o desenvolvimento local, isso significa a URL HTTPS que o seu túnel (da seção de pré-requisitos acima) expõe, não localhost.
register_webhook.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} response = requests.post( f"{BASE_URL}/webhooks", headers=HEADERS, json={ "source": "messaging", "request_url": "https://your-tunnel.example.com/webhooks/whatsapp", "name": "whatsapp-fastapi", "format": "json", "events": ["message_received"], }, ) response.raise_for_status() print(response.json())
2. Receba-o no FastAPI
A carga útil que o Unipile envia transporta o chat, o remetente e o texto da mensagem como campos planos, além de uma lista de anexos quando houver. Modele apenas o que você precisa; o Pydantic ignora campos extras por padrão.
main.py
from typing import List, Optional from fastapi import BackgroundTasks, FastAPI from pydantic import BaseModel app = FastAPI() class Sender(BaseModel): attendee_id: str attendee_name: Optional[str] = None id_do_provedor_do_participante: str class Anexo(BaseModel): id: str tipo: str tipo_MIME: Optional[str] = None indisponível: bool = False class WhatsAppMessageEvent(BaseModel): account_id: str account_type: str event: str chat_id: str message_id: str message: Optional[str] = None timestamp: str webhook_name: Optional[str] = None remetente: Remetente anexos: Lista[Anexo] = [] def processar_mensagem(evento: WhatsAppMessageEvent) -> None: se evento.tipo_da_conta != "WHATSAPP" ou evento.evento != "message_received": retornar # O Unipile inclui mensagens enviadas pela própria conta vinculada, seja # de outro dispositivo ou por meio de suas próprias chamadas de API. Compare o remetente # com o titular da conta que você armazenou no momento da conexão, caso # deseje reagir apenas às mensagens provenientes do outro lado. print(f"Nova mensagem do WhatsApp no chat {event.chat_id}: {event.message}") # encaminhe para sua fila, seu banco de dados ou um agente de IA a partir daqui @app.post("/webhooks/whatsapp") async def whatsapp_webhook( event: WhatsAppMessageEvent, background_tasks: BackgroundTasks, ): background_tasks.add_task(handle_message, event) return {"status": "received"}
Executar com uvicorn main:app --reload, aponte o seu túnel para a porta 8000 e registre essa URL pública como request_url no passo 1. Retornando {"status": "received"} antes de a mensagem ser totalmente processada importa: o Unipile espera uma resposta rápida e Tarefas em Segundo Plano é o que mantém tratar_mensagem de bloqueá-lo.
Mais uma coisa que vale a pena incluir desde o início: armazenar cada processado id_da_mensagem antes de agir com base nela, e ignore tudo o que você já viu. Se a própria conta do WhatsApp vinculada se desconectar e se reconectar, o Unipile entrega as mensagens que chegaram durante essa lacuna assim que ele se atualiza, e um novoimplante ou uma tarefa em segundo plano que sofreu falha pode fazer com que seu próprio manipulador veja o mesmo evento duas vezes separadamente, portanto, tratar id_da_mensagem como uma chave de idempotência evita que um bot do WhatsApp responda duas vezes.
Construa seu webhook FastAPI
Ler

Como você recupera chats e histórico de mensagens em Python?

Cada endpoint de lista na API da Unipile, chats, mensagens, participantes, é paginado da mesma forma: a resposta traz um itens vetor e um cursor. Passe isso cursor retorne na próxima ligação e pare assim que ela voltar nulo. Do Python enquanto True o loop mapeia diretamente para esse padrão.
Listar todas as conversas do WhatsApp para uma conta
list_chats.py
import requests BASE_URL = "https://{YOUR_DSN}/api/v1" HEADERS = {"X-API-KEY": "YOUR_ACCESS_TOKEN"} def list_all_whatsapp_chats(account_id: str) -> list: chats = [] cursor = None while True: params = {"account_id": account_id, "limit": 100} if cursor: params["cursor"] = cursor response = requests.get(f"{BASE_URL}/chats", headers=HEADERS, params=params) response.raise_for_status() page = response.json() chats.extend(page["items"]) cursor = page["cursor"] if not cursor: break return chats for chat in list_all_whatsapp_chats("Yk08cDzzdsqs9_8ds"): print(chat["id"], chat["name"], chat["unread_count"])
Ler o histórico de mensagens e os participantes de um bate-papo
As mensagens mais recentes aparecem primeiro. Use o mesmo limite e cursor padrão para paginar para trás no histórico mais antigo, e chamar o endpoint de participantes sempre que precisar resolver quem está realmente em um chat, individual ou em grupo.
chat_history.py
def get_chat_history(chat_id: str, limit: int = 100) -> list: response = requests.get( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, params={"limit": limit}, ) response.raise_for_status() return response.json()["items"] def get_chat_attendees(chat_id: str) -> list: response = requests.get( f"{BASE_URL}/chats/{chat_id}/attendees", headers=HEADERS, ) response.raise_for_status() return response.json()["items"] messages = get_chat_history("9f9uio56sopa456s") attendees = get_chat_attendees("9f9uio56sopa456s")
Este também é o caminho de código que uma sincronização de CRM ou uma caixa de entrada de suporte realmente executa em Python: em uma nova conexão, percorra cada chat uma vez com listar_todas_as_conversas_do_whatsapp parapopular o seu banco de dados e, em seguida, contar com o webhook da seção anterior para mantê-lo atualizado, em vez de fazer novas consultas. O GET /chats o endpoint também aceita um Não lida filtro, para que um trabalho mais leve que apenas verifica chats não lidos em uma programação não precise percorrer o histórico completo da conta a cada execução.
Os grupos do WhatsApp também são chats, então o mesmo GET /chats e GET /chats/{chat_id}/attendees chamadas, liste-as e seus membros a partir do Python, sem código extra. Para adicionar ou remover um participante, ou para buscar o link de convite, use PATCH /chats/{chat_id} com um adicionarParticipante, removerParticipanteou obterLinkDeConvite ação. O passo a passo completo, juntamente com os próprios limites de participantes da Meta em sua API nativa de Grupos, encontra-se no guia para adicionar ou remover participantes do grupo do WhatsApp.
Automação

Como construir um bot do WhatsApp ou agente de IA em Python?

Todo bot de WhatsApp ou agente de IA segue os mesmos três passos: receber uma mensagem através do webhook, decidir o que fazer com ela e enviar uma resposta na mesma chat_id. Nada sobre os passos um e três muda quando você coloca um LLM no meio, razão pela qual o manipulador do FastAPI e o enviar_mensagem As funções das seções anteriores já são a maior parte do código de que você precisa.
agent.py
from openai import OpenAI # ou qualquer cliente LLM que você utilize llm = OpenAI() _recent_bot_replies: dict = {} def generate_reply(incoming_text: str) -> str: completion = llm.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "Você é um agente de suporte útil do WhatsApp."}, {"role": "user", "content": incoming_text}, ], ) return completion.choices[0].message.content def handle_message(event: WhatsAppMessageEvent) -> None: se event.account_type != "WHATSAPP" ou event.event != "message_received": retorne se não houver mensagem no event: retorne se _recent_bot_replies.get(event.chat_id) == event.message: return # — eco da nossa última resposta; ignore-a reply_text = generate_reply(event.message) _recent_bot_replies[event.chat_id] = reply_text send_message(event.chat_id, reply_text)
O _respostas_recentes_do_bot a proteção importa mais do que parece: a da Unipile message_received o evento é disparado para mensagens que a conta vinculada envia também, a partir de outro dispositivo ou das suas próprias chamadas de API, portanto, sem uma proteção, um agente pode acabar respondendo à sua própria resposta. Um dicionário é aceitável para uma demonstração; um agente de produção deve manter esse estado no Redis ou em um banco de dados junto com o histórico de conversas e uma chave de idempotência.
O payload do webhook e o enviar_mensagem As chamadas têm o mesmo formato no WhatsApp, LinkedIn, Instagram e Telegram, apenas tipo de conta mudanças, para que o mesmo manipulador do FastAPI possa direcionar as respostas de um agente por todos os canais aos quais um usuário se conectou. Manter o tom, a formatação e os limites de taxa específicos de cada canal corretos ao fazer isso é abordado no guia para o API multicanal para agentes de IA.
Construa seu agente de IA para o WhatsApp
Confiabilidade

Como você lida com limites de taxa (rate limits) e tentativas (retries) em Python?

O Unipile retorna um corpo JSON com um tipo campo, como erros/credenciais_invalidas ou erros/conta_desconectada, sempre que uma solicitação falha. Algumas delas vale a pena tentar novamente, como uma conexão caiu ou uma instabilidade temporária do provedor; outras, como credenciais inválidas, não se consertam sozinhas, não importa quantas vezes você tente de novo. A velocidade e o volume de envio a partir de uma única conta do WhatsApp continuam sendo uma decisão do cliente, moldados pelos limites de taxa que o próprio WhatsApp impõe a essa conta, e não por um número fixo que a Unipile impõe adicionalmente.
O tenacidade empacote isso transformando em um decorador em vez de um loop manual. Envolva o mesmo enviar_mensagem função da seção de envio com espera exponencial e um limite de tentativas:
retry.py
# pip install tenacity import requests from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type @retry( stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=2, max=30), retry=retry_if_exception_type(requests.exceptions.HTTPError), ) def enviar_mensagem_com_retenta(id_do_chat: str, texto: str) -> dict: response = requests.post( f"{BASE_URL}/chats/{chat_id}/messages", headers=HEADERS, data={"text": text}, ) response.raise_for_status() return response.json()
Cinco tentativas com um intervalo exponencial de 2 a 30 segundos são um padrão razoável para um job em segundo plano; reduza o número de tentativas para qualquer coisa executada no caminho de uma requisição voltada para o usuário, já que tenacidade continuará mantendo a requisição aberta enquanto tenta novamente. O mesmo decorador envolve a versão assíncrona da seção de concorrência, basta adicionar await onde tenacidade apoia através AsyncRetrying.
SDK

Existe um SDK Python oficial da Unipile?

Sim. unipile/unipile-python é real e ativamente mantido, com um commit enviado recentemente em 11 de agosto de 2026. Duas coisas valem a pena saber antes de você recorrer a ele: ele ainda não foi publicado no PyPI e é voltado para a API v2 do Unipile, que ainda está em beta, enquanto cada endpoint usado ao longo deste guia é a v1.
Ativamente mantido, apenas no GitHub
Python 3.9+, pydantic 2.11+
Não está no PyPI, instale do GitHub
Visa a API v2 beta, não a v1
install_sdk.sh
pip install git+https://github.com/unipile/unipile-python.git
sdk_usage.py
import unipile configuration = unipile.Configuration() configuration.api_key["apiKey"] = "YOUR_ACCESS_TOKEN" api_client = unipile.ApiClient(configuration) messaging_api = unipile.MessagingApi(api_client)
Para tudo o que este guia abrange hoje, complemente os endpoints REST da v1 com solicitações ou httpxeles são estáveis, documentados e é neles que cada exemplo de código acima realmente é executado. Assim que o SDK do Python sair da versão beta e for publicado no PyPI, migrar significará principalmente substituir chamadas HTTP por métodos de cliente tipados; os endpoints e o modelo de conta conectada subjacentes não mudam. Em comparação, o SDK do Node.js é o atualmente referenciado em todo o índice principal da documentação da Unipile, e o SDK mais antigo em PHP foi arquivado desde outubro de 2023.
Construindo o mesmo tipo de integração para outro canal? O API do Instagram com Python o guia segue o padrão idêntico de conectar, enviar, recuperar e webhook mostrado neste artigo.
Construa com a API REST hoje

API do WhatsApp em Python: Perguntas Frequentes

Respostas diretas sobre bibliotecas, conexão, SDKs e webhooks para construir a API do WhatsApp em Python.

Não existe uma única melhor biblioteca, depende do que você já tem. Se você já foi aprovado na API Cloud da Meta, whatsapp-cloud-api fornece um wrapper em Python ao seu redor. Se você quiser ignorar completamente a verificação do Meta Business e, em vez disso, conectar contas do WhatsApp em nome de seus usuários, a API REST do Unipile chamada com solicitações ou httpx cobre o WhatsApp junto com o LinkedIn, Instagram e Telegram a partir de uma única interface. pywhatkit vale a pena descartar logo: ele controla o WhatsApp Web em um navegador, e não uma API do lado do servidor, portanto não se encaixa em um backend de produção.
Enviar um POST pedido para /api/v1/chats/{chat_id}/mensagens with a text campo e seu X-API-KEY cabeçalho, por exemplo requests.post(url, headers=headers, data={"text": "Hello"}). Se você não tiver um chat_id ainda, POST /api/v1/chats com um account_id e o do destinatário attendees_ids cria o chat e envia a primeira mensagem na mesma chamada.
Sim. Conectar uma conta do WhatsApp através do Unipile requer apenas que o proprietário da conta escaneie um código QR ou insira um código de pareamento, da mesma forma que o WhatsApp Web funciona. Não há aplicativo da Meta Business Platform e nenhuma verificação de número de telefone com a Meta, porque a integração é executada em nome do usuário autenticado em vez de por meio de um número do WhatsApp Business registrado.
Sim, unipile/unipile-python é um SDK oficial ativamente mantido, mas ainda não está no PyPI: instale-o com pip install git+https://github.com/unipile/unipile-python.git. Ela também tem como alvo a API v2 da Unipile, que está em beta, enquanto cada endpoint deste guia usa a API v1 estável, portanto, a maioria das integrações em Python hoje ainda é construída diretamente sobre solicitações ou httpx em vez do SDK.
solicitações é mais simples e suficiente para scripts, cron jobs e envio de baixo volume. httpx vale a pena a mudança assim que você estiver enviando para muitos destinatários de uma vez ou construindo um serviço FastAPI assíncrono, porque ele AsyncClient permite disparar várias requisições concorrentemente a partir do mesmo *event loop* em vez de bloquear em cada uma.
Execute um aplicativo FastAPI localmente, exponha-o com um túnel como ngrok ou cloudflared para obter uma URL pública HTTPS e registrar essa URL como request_url quando você cria um webhook com fonte definir para messaging. A Unipile envia cada nova mensagem para essa URL de túnel, que a encaminha diretamente para a sua rota FastAPI local enquanto você desenvolve.
Sim. Os grupos do WhatsApp aparecem como conversas normais, então GET /chats e GET /chats/{chat_id}/attendees liste-os e seus membros sem distinção de maiúsculas e minúsculas. Para adicionar um participante, remover um ou obter o link de convite do grupo, envie um PATCH /chats/{chat_id} pedido com um adicionarParticipante, removerParticipanteou obterLinkDeConvite ação, detalhada no guia para adicionando e removendo participantes de grupos do WhatsApp.
Os endpoints subjacentes são idênticos, a diferença é o ambiente de execução (runtime) e seu ecossistema: o Python favorece solicitações ou httpx com asyncio para concorrência e FastAPI para webhooks, enquanto integrações em PHP normalmente usam Guzzle e se encaixam em uma aplicação Laravel com jobs em fila. Se a sua stack for PHP, a mesma integração em PHP percorre cada etapa equivalente.

Ainda tem dúvidas? Nossa equipe está aqui para ajudar.

Fale com um especialista
pt_BRBR
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT nl_NLNL pl_PLPL tr_TRTR pt_BRBR