Ferramentas do MCP - Arara — API de WhatsApp Business

O MCP tem 3 camadas: tools (ações que o agente executa), resources (dados que o cliente lê sem tool call) e prompts (fluxos prontos). Instalação e autenticação: MCP Server. A versão atual é o pacote @ararahq/mcp 6.x; mudanças em relação às versões antigas estão no changelog. São 9 tools de propósito. Agente com painel de controle inteiro erra mais do que agente com poucas ações que aceitam o que uma pessoa sabe de cabeça (um nome, um número em qualquer formato) e resolvem o resto.

Grupo	Ferramentas
Falar com a base	`send_whatsapp` · `broadcast`
Ver o que voltou	`campaign_report` · `check_status` · `read_conversation`
Preparar	`create_template` · `save_contacts` · `opt_out`
Conta	`whoami`

Como um destinatário é resolvido

send_whatsapp, broadcast, check_status e read_conversation aceitam em to um número em qualquer grafia ou o nome de um contato salvo.

Número: o MCP remove pontuação e espaços. Número com + ou com 12 dígitos ou mais é tratado como já tendo DDI; se for brasileiro (55) com 10 dígitos depois do DDI, ganha o nono dígito. Número sem DDI com 10 ou 11 dígitos ganha +55. O resultado precisa ser E.164 válido, senão a tool falha com INVALID_PHONE.
Nome: o MCP busca nos seus contatos salvos. Nenhum resultado dá CONTACT_NOT_FOUND; mais de um dá CONTACT_AMBIGUOUS com os candidatos, em vez de chutar.

Busca por nome, save_contacts e read_conversation usam a base de contatos da Arara, que depende do plano. Em plano sem contatos, a API recusa com PLAN_FEATURE_LOCKED; passe o número direto nas tools de envio.

Falar com a base

send_whatsapp

Manda uma mensagem pra uma pessoa. Texto livre dentro da janela de 24h, ou template aprovado a qualquer hora. Passe exatamente um entre message e templateName.

Parâmetro	Tipo	Descrição
`to`	string	Número em qualquer formato ou nome de contato salvo. Até 255 caracteres.
`message`	string (um dos dois)	Texto livre, até 4.096 caracteres. Só passa com a janela de 24h aberta.
`templateName`	string (um dos dois)	Nome de um template aprovado. Funciona com a janela fechada.
`variables`	string[] (opcional)	Valores posicionais do template, na ordem: `["João", "4412"]` preenche `{{1}}` e `{{2}}`. Até 20 itens, 1.024 caracteres cada.
`from`	string (opcional)	Número de origem em E.164. Omitido, a Arara usa o número padrão da organização.
`idempotencyKey`	UUID (opcional)	Chave de idempotência. Omitida, o MCP gera uma por chamada.

O retorno traz o id da mensagem, o status de aceite e o destinatário resolvido. Aceite quer dizer na fila, não entregue: confira a entrega com check_status. Se você mandou texto livre e a janela estava fechada, o erro CONVERSATION_WINDOW_CLOSED já vem com até 10 templates aprovados pra escolher, ou sugere criar um com create_template se não houver nenhum.

manda um whatsapp pra Renata: seu pedido 4412 saiu pra entrega

manda o template aviso_entrega pro 11 99999-8888 com João e 4412

broadcast

Manda um template aprovado pra várias pessoas de uma vez, como campanha. Disparo em massa é quase sempre fora da janela de 24h, então só aceita template. Teste A/B e agendamento são opções da mesma chamada.

Parâmetro	Tipo	Descrição
`templateName`	string	Nome de um template aprovado (não o ID). Com `abTest`, é a variante A.
`to`	array	De 1 a 1.000 itens. Cada item é um número ou nome (usa as `variables` compartilhadas) ou um objeto `{ to, variables }` com valores só daquela pessoa.
`variables`	string[] (opcional)	Variáveis aplicadas a quem veio como string. Até 20 itens.
`name`	string (opcional)	Nome da campanha no dashboard, até 255 caracteres. Omitido: `Broadcast AAAA-MM-DD HH:MM`.
`from`	string (opcional)	Número de origem em E.164.
`scheduledAt`	string (opcional)	Data e hora ISO-8601 em UTC, ex: `2026-09-20T12:00:00Z`. Presente, a campanha nasce agendada em vez de disparar agora.
`abTest`	objeto (opcional)	Liga o teste A/B. Ver abaixo.
`dryRun`	boolean (opcional)	Default `true`. Passe `false` pra disparar de verdade.
`idempotencyKey`	UUID (opcional)	Chave de idempotência do disparo. Omitida, o MCP gera uma por chamada.

Por padrão é uma prévia. Com dryRun omitido ou true, o MCP resolve a audiência, renderiza o corpo do template com as variáveis do primeiro destinatário, lista os botões e chama o estimador de custo da Arara. Nada é enviado. A resposta traz a mensagem renderizada, quantos destinatários resolveram, quais não resolveram, custo unitário e total, a configuração de A/B e o agendamento. Com dryRun: false, a campanha é criada e a resposta traz o ID, o status, o total de mensagens e o custo total. Pra disparar, a organização precisa ter um número dedicado conectado. Números ou nomes que não resolverem vêm listados na resposta, sem derrubar o disparo. Se nenhum resolver, a tool falha com NO_VALID_RECIPIENTS. abTest: a Arara manda as duas variantes pra uma fatia da base, meio a meio, mede a melhor na janela de decisão e dispara o resto pela vencedora.

Campo de `abTest`	Tipo	Descrição
`variantBTemplateName`	string	Template da variante B (obrigatório).
`metric`	enum (opcional)	`DELIVERED`, `READ`, `CLICKED` ou `CONVERTED`. Default `CLICKED`.
`samplePct`	inteiro (opcional)	% da base que entra no teste, de 1 a 99. Default `20`.
`decisionWindowMinutes`	inteiro (opcional)	Minutos até decidir. Default `240` (4h).
`autopilot`	boolean (opcional)	Dispara o resto pela vencedora sozinho. Default `true`.

dispara o template promo_setembro pra lista de clientes VIP com a variável "20% off"

testa a copy acad_v1 contra a acad_v2 nesses 300 leads: 20% no teste, decide em 4h por clique

Ver o que voltou

campaign_report

Sem campaignId, lista as campanhas recentes, mais novas primeiro, com status, template, enviados, entregues, lidos, falhas e custo. Com campaignId, devolve o relatório completo: enviados, entregues, lidos, cliques, respostas, conversões (com valor), contatos segurados pelo A/B, bloqueados (com o motivo de cada grupo), estornos (quantidade e valor) e custo. A mensagem de texto já traz cada etapa em percentual da base.

Parâmetro	Tipo	Descrição
`campaignId`	UUID (opcional)	ID da campanha, do `broadcast` ou da própria listagem.
`status`	string (opcional)	Filtro da listagem, ex: `COMPLETED`, `COMPLETED_WITH_ERRORS`, `AB_TESTING`, `SCHEDULED`, `CANCELED`, `FAILED`.
`page`	inteiro (opcional)	Página da listagem. Default `0`.
`size`	inteiro (opcional)	Itens por página, de 1 a 100. Default `20`.

me mostra o relatório da campanha promo_setembro: quantos clicaram e quantos responderam?

check_status

Responde “chegou?”, “posso falar agora?” e “o template aprovou?”. Passe exatamente um dos três.

Parâmetro	Tipo	Descrição
`to`	string	Pessoa (número ou nome). Diz se a janela de 24h está aberta e quantas horas restam.
`messageId`	string	O `id` devolvido pelo `send_whatsapp`. Status de entrega, custo e motivo se falhou.
`templateId`	UUID	O `id` devolvido pelo `create_template`. Status de aprovação da Meta (`APPROVED`, `PENDING`, `REJECTED` e afins), com o motivo quando reprovado.

posso mandar texto livre pro +5511999998888 agora?

read_conversation

Lê o conteúdo das mensagens trocadas com uma pessoa, direto da timeline: direção (cliente ou você), status, template usado, texto e data de cada uma. É como você separa interesse real de resposta automática antes de responder com send_whatsapp.

Parâmetro	Tipo	Descrição
`to`	string	Número (qualquer formato) ou nome de contato salvo.
`limit`	inteiro (opcional)	Quantas mensagens trazer, de 1 a 100. Default `30`.

Preparar

create_template

Submete um template novo pra aprovação da Meta. Você precisa de um pra qualquer broadcast e pra falar com quem está fora da janela de 24h. A aprovação costuma levar minutos; acompanhe com check_status passando o templateId que volta na resposta.

Parâmetro	Tipo	Descrição
`name`	string	Nome único: só letras minúsculas, dígitos e underscore (`aviso_entrega`). Até 512 caracteres.
`category`	enum	`MARKETING`, `UTILITY` ou `AUTHENTICATION`.
`body`	string	Corpo com placeholders posicionais, até 4.096 caracteres: `Oi {{1}}, seu pedido {{2}} saiu`.
`language`	string (opcional)	Default `pt_BR`.
`header`	string (opcional)	Texto do cabeçalho ou URL de mídia.
`headerType`	enum (opcional)	`text`, `media` ou `document`. Quando há `header` sem `headerType`, vale `text`.
`footer`	string (opcional)	Rodapé, até 60 caracteres.
`samples`	objeto (opcional)	Exemplo por variável: `{"1": "João"}`. Ajuda a Meta a entender o template.
`buttons`	array (opcional)	Até 2 botões `{ type, text, url?, phone? }`. Tipos: `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `SMART_LINK`, `COPY_CODE`. `url` precisa ser URL válida; `phone`, E.164.

A Meta reprova template que é só variável ({{1}} sem texto fixo). Escreva o texto real da mensagem; variável é pra nome, número de pedido, valor, não pro corpo inteiro.

Botão SMART_LINK: passe em url o destino real (ex: https://wa.me/5511999999999?text=Quero%20saber%20mais). A Arara encurta e conta cada clique, que aparece como cliques no campaign_report. É assim que você descobre qual copy converteu num teste A/B.

save_contacts

Salva (cria ou atualiza) contatos pra você mandar mensagem por nome em vez de decorar número. De 1 a 1.000 por chamada.

Parâmetro	Tipo	Descrição
`contacts`	array	Lista de `{ name, phone, email?, attributes? }`. `name` até 255 caracteres; `phone` obrigatoriamente em E.164 (`+5511999998888`), sem normalização; `email` válido; `attributes` é um objeto livre de valores JSON.

Devolve quantos foram criados, atualizados e ignorados, com a lista de erros por índice quando alguma linha não passa.

salva esses contatos da planilha: João +5511988887777, Renata +5521977776666

opt_out

Registra que uma pessoa não quer mais receber mensagens da sua organização, na lista de opt-out da organização. Idempotente: registrar duas vezes é seguro.

Parâmetro	Tipo	Descrição
`phone`	string	E.164 (`+5511999998888`). Aqui não há normalização nem busca por nome.
`reason`	string (opcional)	Até 80 caracteres. Ex: `"respondeu PARAR"`, `"pediu no suporte"`.

Pela LGPD, pedido de saída precisa ser respeitado. Registre sempre que a pessoa responder PARAR/STOP, pedir no suporte ou por escrito.

Conta

whoami

Sem parâmetros. Mostra quem está autenticado (nome e e-mail), o plano atual e o saldo da carteira. Chame antes do primeiro disparo da sessão pra conferir em qual conta o agente vai operar.

Formato de resposta e erros

Toda tool devolve um texto curto pro modelo e um structuredContent estável:

{ "ok": true, "data": { } }

{ "ok": false, "error": { "code": "CONTACT_AMBIGUOUS", "message": "...", "retryable": false } }

Em erro de limite (429) ou de servidor, retryable vem true e, quando a API manda Retry-After, o campo retryAfterSeconds vem junto. Os códigos do próprio MCP:

Código	Quando
`INVALID_INPUT`	Combinação de parâmetros inválida (ex: `message` e `templateName` juntos).
`INVALID_PHONE`	O número não vira E.164 válido.
`CONTACT_NOT_FOUND`	Nenhum contato salvo com esse nome.
`CONTACT_AMBIGUOUS`	Mais de um contato com esse nome; a mensagem lista os candidatos.
`CONVERSATION_WINDOW_CLOSED`	Texto livre com a janela de 24h fechada; a mensagem lista templates aprovados.
`NO_VALID_RECIPIENTS`	Nenhum destinatário do `broadcast` resolveu.
`INVALID_API_RESPONSE`	A API respondeu num formato inesperado.
`OPERATOR_NOT_CONFIGURED` / `OPERATOR_NOT_ALLOWED`	Chamada a uma tool de operação interna da AraraHQ.

Os demais códigos vêm da própria API da Arara e passam sem alteração. Veja Erros.

Painéis interativos

Em clientes com suporte a MCP Apps, quatro tools abrem um painel dentro do chat em vez de só texto. O texto continua vindo junto, então clientes sem painel não perdem nada.

Tool	Painel
`campaign_report`	Lista de campanhas ou funil da campanha com números grandes, motivos de bloqueio e atualização ao vivo enquanto dispara. Botões Ver quem respondeu, Reenviar aos não lidos e Atualizar.
`broadcast`	Celular com a mensagem renderizada, audiência, custo estimado e A/B. Aprovar e disparar chama o `broadcast` com `dryRun: false` e passa a mostrar a entrega em tempo real.
`check_status`	Pra `messageId`, linha do tempo da mensagem (aceita, enviada, entregue, lida) que acompanha sozinha até o status final. Pra `to`, se a janela está aberta ou fechada. Pra `templateId`, se o template foi aprovado ou reprovado, com o motivo.
`read_conversation`	Thread da conversa com campo de resposta que envia texto livre pelo `send_whatsapp`, e botões Sugerir resposta e Pediu pra sair.

Os botões que não executam direto viram uma mensagem no chat pro agente continuar (por exemplo, “Reenviar aos não lidos” pede um reenvio com outro template). Os painéis são servidos como resources ui://arara/campaign.html, ui://arara/broadcast.html, ui://arara/status.html e ui://arara/conversation.html, e nunca recebem credencial.

Resources

Dados que o agente lê sem gastar tool call. Todos voltam em JSON; se a leitura falhar, o conteúdo traz RESOURCE_UNAVAILABLE.

Resource	URI	O que devolve
Organização	`arara://organization`	Quem está autenticado, plano atual e saldo da carteira.
Templates aprovados	`arara://templates/approved`	Templates aprovados e disponíveis pra envio (até 100), prontos pra `broadcast` e `send_whatsapp`.
Campanhas recentes	`arara://campaigns/recent`	As 10 últimas campanhas com status, contagens e custo.
Números	`arara://channels`	Seus números de WhatsApp e o estado do slot do plano.

Cada cliente expõe resources de um jeito. Se o seu não mostrar, peça ao agente pra ler a URI, por exemplo arara://templates/approved.

Prompts

Fluxos prontos que o cliente MCP expõe como atalhos. Nenhum recebe argumento, e todos param pra pedir aprovação antes de enviar.

Prompt	O que faz
`plan_broadcast`	Chama `whoami` pra conferir conta e saldo, lê os templates aprovados e escolhe o que serve (ou propõe um novo com `create_template`), roda `broadcast` em prévia e só dispara com `dryRun: false` depois da sua aprovação explícita.
`campaign_review`	Acha a campanha com `campaign_report`, abre o relatório completo, resume entrega, leitura, cliques, respostas e conversões em percentual da base, explica bloqueados e estornos, e recomenda um próximo passo: responder quem respondeu, reenviar pra quem não leu com outro template, ou parar.
`reply_to_responses`	Lê o que a pessoa escreveu com `read_conversation` e rascunha uma resposta curta. Se ela pediu pra sair, chama `opt_out` em vez de responder. Não envia sem você aprovar o texto exato.

Automações (em preparação)

Esta seção descreve tools que ainda não estão no pacote publicado. Elas chegam numa próxima versão do @ararahq/mcp; os nomes abaixo podem mudar até o lançamento.

Sete tools para montar e acompanhar automações em linguagem natural, sobre a mesma API de automações:

Tool	O que faz
`list_automations`	Lista as automações da organização, com status e custo por execução.
`get_automation`	Traz uma automação inteira: gatilho, passos, ramos e estatísticas.
`create_automation`	Cria uma automação nova, com passos e ramificações. Nasce sempre desligada.
`update_automation`	Substitui nome, gatilho e passos de uma automação existente.
`set_automation_active`	Liga ou desliga uma automação.
`delete_automation`	Apaga uma automação e as execuções ligadas a ela.
`list_automation_runs`	Lista execuções de uma automação, com status e onde cada contato parou.

Vale a mesma nota de permissão da API: escrita exige AUTOMATIONS_MANAGE, leitura exige READ. Sem a permissão, a tool falha com o error.code que a API devolveu.

create_automation e update_automation nunca ligam a automação sozinhos: ela sai desligada ou do jeito que já estava. Ligar uma automação com set_automation_active manda mensagens reais para clientes reais a partir daquele momento; confirme com a pessoa antes de chamar. O link de uma automação com gatilho webhook é uma credencial: nunca cole nem repita esse link na conversa.

monta uma automação que pergunta se o cliente quer pagar por Pix ou cartão e etiqueta cada resposta

me mostra quem parou na pergunta ontem

Próximos passos

Instalar o MCP

Erros

Códigos que a API devolve e passam sem alteração pelo MCP.

​Como um destinatário é resolvido

​Falar com a base

​send_whatsapp

​broadcast

​Ver o que voltou

​campaign_report

​check_status

​read_conversation

​Preparar

​create_template

​save_contacts

​opt_out

​Conta

​whoami

​Formato de resposta e erros

​Painéis interativos

​Resources

​Prompts

​Automações (em preparação)

​Próximos passos

Instalar o MCP

Erros

Como um destinatário é resolvido

Falar com a base

send_whatsapp

broadcast

Ver o que voltou

campaign_report

check_status

read_conversation

Preparar

create_template

save_contacts

opt_out

Conta

whoami

Formato de resposta e erros

Painéis interativos

Resources

Prompts

Automações (em preparação)

Próximos passos