Composio + WhatsApp
O WhatsApp dos seus usuários, dentro de um agente do Composio
O Composio dá a um agente mais de 1.500 ferramentas em uma só sessão. O Circles soma a isso o WhatsApp da própria pessoa, como toolkit Custom MCP: as conversas que ela abre, prontas para ler, e para escrever onde ela permite.
Para dar a um agente do Composio um WhatsApp pessoal: crie um toolkit Custom MCP com o endereço https://app.usecircles.app/api/mcp e o cabeçalho Authorization: Bearer {{generic_api_key}}, e cada usuário se conecta com o próprio token do Circles. O agente então lê as conversas que esse usuário abriu no Circles: Free para 2 conversas por até 3 meses, Plus por R$ 29,90 e Pro por R$ 59,90 por mês por número, com 14 dias de Pro grátis, em novembro de 2026.
Atualizado em
O toolkit de WhatsApp do Composio, ou o Circles?
O toolkit de WhatsApp do Composio funciona pela API do WhatsApp Business, e a página dele diz que contas pessoais não são suportadas (em novembro de 2026). É a escolha certa para um número de empresa: modelos, mensagens a clientes em escala, a API oficial. O Circles é para o número da própria pessoa: os grupos, as conversas de família e os áudios do celular que ela já usa, entregues ao agente conversa por conversa.
Quatro passos: dois para cada usuário, dois para você
Cada pessoa conecta o WhatsApp no Circles
Seu usuário começa o teste em usecircles.app e conecta o número como aparelho conectado: um código digitado no celular ou um QR no computador. Ele escolhe quais conversas os agentes podem ler, e em quais podem enviar.
Ela cria um token
Na página Agents do Circles: New token, escolha Other, mantenha MCP e escolha o que ele permite. O token começa com
circ_e aparece uma vez só.Você adiciona o Circles como toolkit Custom MCP, uma vez
No seu projeto do Composio, crie um toolkit com o endereço do Circles e o cabeçalho
Authorization: Bearer {{generic_api_key}}, compartilhado comuser_id="all". O Composio coloca o token de cada usuário quando chama o Circles.Cada usuário se conecta, e seu agente pergunta
O Composio pede a cada usuário o token pelo link de conexão, e as ferramentas sincronizam na primeira conexão. Adicione o slug do toolkit a uma sessão; seu agente encontra as ferramentas com
COMPOSIO_SEARCH_TOOLS.
O código
Python, com o SDK do Composio. Em TypeScript as mesmas chamadas ficam em composio.experimental.customToolkits.
Coloque em mcp_url o endereço exato, sem nenhuma chave dentro. O Composio fixa o endereço, o esquema de autenticação e o user_id na criação; para mudar um deles, apague o toolkit e crie de novo. Quando o Circles adicionar uma ferramenta, sincronize o toolkit outra vez.
from composio import Composio
composio = Composio() # reads COMPOSIO_API_KEY
# Once per project: Circles as a shared Custom MCP toolkit
toolkit = composio.experimental.custom_toolkits.create(
name="Circles (personal WhatsApp)",
mcp_url="https://app.usecircles.app/api/mcp",
auth_schemes=[{
"mode": "API_KEY",
"headers": {"Authorization": "Bearer {{generic_api_key}}"},
}],
user_id="all",
)
print(toolkit.slug) # keep it: CUSTOM_CIRCLES...
# Per user: a session with Circles beside your other toolkits
session = composio.sessions.create(user_id="user_123", toolkits=[toolkit.slug])
tools = session.tools()Entrar pelo endereço em vez de um token
O Custom MCP do Composio também aceita OAuth com registro dinâmico de cliente: "mode": "DCR_OAUTH" com "discovery_url": "https://app.usecircles.app/.well-known/oauth-authorization-server". O Circles registra clientes assim, e cada pessoa aprova na página do Circles e escolhe se o agente pode enviar. Essa combinação ainda não foi testada, então use um token por enquanto.
O que seus usuários podem perguntar
Exemplos inventados, formatos reais.
"O que eu perdi no grupo do condomínio?"
catch_up em um grupo desde um horário, com os áudios já em texto.
"Coloque na minha agenda as datas do grupo da escola"
O Circles lê o grupo; seu toolkit do Google Calendar cria os eventos.
"Ache a nota fiscal que o contador mandou e salve no Drive"
documents encontra, get_media busca e outro toolkit salva.
"Avise o grupo da corrida que na quinta eu não vou"
Só se o token permitir envio e o grupo estiver aberto para envio.
O que um agente do Composio pode e não pode fazer aqui
O agente pode:
- Ver quais conversas você abriu, e quais delas tiveram movimento desde um horário, com contagens e sem texto (
allowed_chats,activity). - Ler as novidades e buscar, numa conversa ou em todas, com os remetentes pelo nome (
catch_up,search). - Ver com quem você conversa e quem está num grupo, pelo nome que você salvou, com o número onde o WhatsApp mostra (
people,group_members). - Listar os documentos enviados nas suas conversas e abrir uma foto, um PDF ou um arquivo, até 50 MB (
documents,get_media). O agente abre e lê o arquivo sozinho. - Enviar uma mensagem ou um arquivo nas conversas abertas para envio, que num número novo são todas (
send).
O agente não pode:
- Ver uma conversa oculta. Ela não aparece em listas, não aparece em buscas e nunca é citada, nem numa recusa.
- Enviar numa conversa que você deixou só para leitura, chegar a uma conversa que você ocultou ou ter um envio repetido automaticamente.
- Responder com citação ou reagir com emoji. Isso só existe na API HTTP (em inglês).
- Manter o acesso depois que você o desconectar. Desconectar encerra na hora, e cada pedido que ele fez continua no seu registro de atividade.
Mudar o acesso, planos e convites
Mudar o que seus agentes podem fazer. Cada agente que você conecta lê e escreve por padrão nas conversas que ficam abertas, desde o início. Para limitar, deixe uma conversa só leitura ou oculte-a na página de conversas do app do Circles, ou escreva para o Atendimento ao Cliente do Circles, o serviço virtual no número do Circles: wa.me/972553091640. Escreva pelo seu próprio WhatsApp. Seu agente pode redigir a mensagem. Ele não pode abrir, ler nem enviar nessa conversa, porque ela tem seus links de acesso.
Planos. Todos os planos leem e escrevem e veem todo o histórico disponível: 2 conversas no Free, por até 3 meses a partir da conexão, 10 no Plus e todas as conversas que você permitir no Pro. Todo cadastro começa com 14 dias de Pro, sem cartão. Nada é cobrado sem que você escolha um plano. Planos e preços.
Convites. Um amigo que você convida ganha 28 dias de Pro em vez de 14, a partir do dia em que conecta o WhatsApp. Você ganha 14 dias quando o agente dele lê pela primeira vez pelo Circles, até 10 amigos por semana. Peça seu link de convite ao Atendimento ao Cliente do Circles.
Perguntas e respostas
O Composio tem um toolkit de WhatsApp?
Sim, para contas do WhatsApp Business pela API Business, e a página dele diz que contas pessoais não são suportadas (em novembro de 2026). O Circles adiciona um número pessoal ao Composio como toolkit Custom MCP.
Cada usuário pode conectar o próprio WhatsApp?
Sim. Compartilhe um toolkit do Circles com user_id="all"; cada usuário se conecta com o próprio token do Circles, e o agente dele vê só as conversas que ele abriu no Circles.
O Circles está no catálogo de toolkits do Composio?
Ainda não, em novembro de 2026. Adicione como toolkit Custom MCP; segundo a documentação do Composio, toolkits compartilhados funcionam em todos os planos dele.
Dá para entrar com OAuth em vez de um token?
O Composio aceita OAuth com registro dinâmico, e o Circles também, mas os dois ainda não foram testados juntos. Até lá, use um token.
O agente pode enviar mensagens no WhatsApp?
Só se o token do usuário permitir envio, e só em conversas abertas para envio (todas, por padrão). Um envio nunca é repetido automaticamente.
Quanto custa?
O Circles é cobrado por número de WhatsApp: Free para 2 conversas, sem custo, por até 3 meses; Plus por R$ 29,90 por mês; e Pro por R$ 59,90 por mês, com 14 dias de Pro grátis. O plano do Composio é separado.
Seu e-mail já está com sua IA. Agora conecte o WhatsApp.
14 dias para testar tudo, grátis e sem cartão de crédito. Depois você escolhe um plano pelo que realmente usou.