https://www.boavoz.com/mcp, no transporte HTTP do MCP (Streamable HTTP), sem estado: cada pedido é um POST com JSON-RPC, e a resposta vem em JSON. Use sempre o endereço com www.
Com o login do BoaVoz (OAuth)
É o clique no app: ele abre a tela do BoaVoz, você entra, escolhe o escopo (a conta inteira, um cliente ou alguns chatbots) e o que o app pode fazer, e autoriza. O app cadastra a si mesmo, sem nada para criar no painel (OAuth 2.1 com o cadastro automático de apps e o PKCE). Quem chama o servidor sem login recebe 401 com o endereço dos metadados, e o app acha o resto por eles:
http
WWW-Authenticate: Bearer realm="boavoz", resource_metadata="https://www.boavoz.com/.well-known/oauth-protected-resource/mcp"
- Quem autoriza é o dono ou um administrador da conta, com o segundo fator, como ao criar uma chave da API. A permissão de cobrança vem desligada, e só o dono pode dar.
- Quem ainda não tem conta entra ou cria a conta pela própria tela e volta para ela com o mesmo pedido. A conta nova começa no teste grátis, cadastra o app autenticador ali mesmo e conecta o app; os chatbots se montam depois, no painel. Enquanto o BoaVoz abre por convite, quem não tem o convite entra na lista de espera.
- A conexão aparece em Integrações → Chaves de API como app conectado, com o escopo, as permissões e o último uso. Desconectar ali tira o acesso na hora. Quem sai da conta, ou deixa de ser dono ou administrador, leva as conexões que autorizou junto.
- Autorizar o mesmo app de novo atualiza a mesma conexão, com o escopo e as permissões novos.
json
{
"mcpServers": {
"boavoz": {
"url": "https://www.boavoz.com/mcp"
}
}
}
Com uma chave da API
Para o cliente de MCP que não faz login: a mesma chave da API (bv_live_…) no cabeçalho, com o escopo e as permissões dela.
json
{
"mcpServers": {
"boavoz": {
"url": "https://www.boavoz.com/mcp",
"headers": { "Authorization": "Bearer bv_live_SUA_CHAVE" }
}
}
}
O pacote
O MCP usa a conta pela API: é do pacote Integrações, como ela (no teste grátis, enquanto houver respostas de teste, também funciona). Sem o pacote, cada ferramenta responde o erro
403 plan_not_allowed.
A ferramenta whoami diz a conta, o nome, as permissões e o escopo da conexão, e os chatbots que ela alcança, com o bot_id que as outras ferramentas pedem.
json
{
"account": { "id": "8b1f…", "name": "Agência Exemplo" },
"connection": {
"name": "agentes.chat",
"kind": "oauth",
"permissions": ["messages", "conversations", "contacts"],
"scope": "account"
},
"chatbots": [
{ "bot_id": "bot_7c9e6679-…", "name": "Loja do Zé", "client_id": "cli_…", "client_name": "Loja do Zé", "status": "live" }
],
"docs": "https://www.boavoz.com/docs/api"
}
Uma por operação da API, com o mesmo nome dos campos, as mesmas regras e os mesmos erros (o resultado traz o JSON da API; o erro vem marcado, com o status e o error.code). A conexão vê só as ferramentas das permissões dela. As que só leem vêm marcadas como leitura; as que apagam, cobram ou têm custo da Meta, como destrutivas. Os apps pedem a sua aprovação para enviar, apagar e cobrar (o agentes.chat pede pelo verbo: send_, delete_, remove_ e pay_).
| Ferramenta | O que faz | Tipo |
|---|
list_conversations | As conversas dos chatbots da conexão, a mais recente primeiro, com o status (ai, ai_paused, waiting_human, human), o setor, o chamado e quem atende. | só lê · conversations |
list_conversation_messages | As mensagens de uma conversa, da mais antiga para a mais nova: direção, origem (contato, IA, equipe, API, campanha), quem mandou, status, citação, reações e o arquivo (com a transcrição do áudio e a leitura da foto). | só lê · conversations |
pause_conversation_ai | Pausa a IA numa conversa para o seu sistema (ou você) responder por send_message. | muda · conversations |
resume_conversation_ai | Tira a pausa da IA na conversa na hora; a IA responde a última mensagem do contato se ela ficou sem resposta. | muda · conversations |
get_media | O arquivo de uma mensagem (med_…): a imagem vem como imagem; os outros tipos vêm com o tipo e o tamanho (o texto do áudio já vem na mensagem, em transcript). | só lê · conversations |
| Ferramenta | O que faz | Tipo |
|---|
send_message | Envia texto, modelo aprovado, imagem ou documento para um contato no WhatsApp ou no Instagram (bot_id e to) ou numa conversa do chat do site (conversation_id). | muda · messages |
get_message | Uma mensagem (msg_…) com o status: received, pending, sent, delivered, read, failed (com error.code) ou uncertain. | só lê · messages |
list_templates | Os modelos do número do WhatsApp do chatbot: categoria, status da Meta, texto, número de variáveis e se dá para enviar pela API (sendable). | só lê · messages |
| Ferramenta | O que faz | Tipo |
|---|
list_contacts | Os contatos, na ordem da última alteração: canal, nome, telefone, etiquetas, aceite de novidades, 18+, as datas das réguas e o Chamar a equipe. | só lê · contacts |
update_contact | Grava as datas das réguas (aniversário, última visita, próximo horário e as datas das réguas personalizadas), o Chamar a equipe e a conversa privada do contato. | muda · contacts |
set_contact_tags | Troca todas as etiquetas do contato pela lista (lista vazia apaga todas). | muda · contacts |
set_contact_age | A empresa informa a idade que conferiu (para bebida alcoólica e remédio, só para quem tem 18 anos). | muda · contacts |
delete_contact | Pedido do titular (LGPD) já confirmado: apaga as conversas, os arquivos, os leads e a ficha do contato e põe o número na lista de supressão. | apaga, cobra ou tem custo · contacts |
list_leads | Um lead por contato em cada chatbot: nome, telefone, e-mail, o pedido mais recente e o histórico de pedidos. | só lê · contacts |
| Ferramenta | O que faz | Tipo |
|---|
send_campaign | Campanha de novidades (kind marketing: um modelo de marketing para um público por etiquetas, contatos ou ids externos; só recebe quem aceitou) ou lote de lembretes (kind utility_reminder: um modelo de utilidade com uma linha por envio, em sends). | apaga, cobra ou tem custo · campaigns |
get_campaign | O status da campanha (scheduled, sending, paused, finished, canceled) e os totais: enviadas, entregues, lidas, respondidas, falhas, retidas pela Meta (held), puladas por motivo e descadastros. | só lê · campaigns |
set_marketing_consent | Grava o aceite (ou a retirada) de novidades no WhatsApp com a prova: onde, o texto aceito e quando. | muda · campaigns |
| Ferramenta | O que faz | Tipo |
|---|
create_pairing | Gera o código (6 caracteres, uso único, 10 minutos) e o link que a pessoa abre no celular para ligar o contato à conta dela no seu sistema. | muda · pairing |
list_contact_links | Os vínculos ativos do contato com contas do seu sistema (pelo código ou lembrados pelo roteiro). | só lê · pairing |
delete_contact_link | Desfaz o vínculo do contato com a conta do seu sistema (sai o webhook contact.unlinked). | apaga, cobra ou tem custo · pairing |
| Ferramenta | O que faz | Tipo |
|---|
add_source | Grava uma fonte de conhecimento no chatbot e lê na hora: texto, perguntas frequentes, planilha CSV, uma página ou um PDF por URL. | muda · sources |
list_sources | As fontes do chatbot, as mais novas primeiro. | só lê · sources |
delete_source | Tira a fonte (src_…) e os trechos dela da base do chatbot. | apaga, cobra ou tem custo · sources |
get_notice | O aviso do momento do chatbot que vale agora (um texto com prazo, como uma queda ou manutenção), ou null. | só lê · sources ou provisioning |
set_notice | Põe ou troca o aviso do momento: um texto com prazo que a IA usa quando perguntam ou quando o assunto tem a ver (nunca como instrução). | muda · sources ou provisioning |
clear_notice | Tira o aviso do momento do chatbot antes do prazo. | muda · sources ou provisioning |
| Ferramenta | O que faz | Tipo |
|---|
create_client | Cria o cliente (a loja). | muda · provisioning |
get_client | Os dados do cliente (cli_…), os chatbots dele com os canais conectados e a conformidade. | só lê · provisioning |
create_chatbot | Cria o chatbot do cliente a partir de um modelo publicado (personalidade, ações, roteiros e base do modelo), com o contexto, os dados da loja e os valores próprios. | muda · provisioning |
update_chatbot | Muda os dados da loja (display), os valores próprios, o horário do atendimento humano e os outros jeitos de falar com a equipe. | muda · provisioning |
create_connect_link | O link para o cliente conectar o WhatsApp ou o Instagram dele ao chatbot (vale 7 dias e serve para uma conexão; rotate cria outro). | muda · provisioning |
list_chatbot_channels | Os canais da Meta do chatbot (WhatsApp e Instagram), com o número ou o @, o status e o problema em aberto. | só lê · provisioning |
disconnect_channel | Desconecta de vez o WhatsApp ou o Instagram do chatbot: o BoaVoz deixa de receber as mensagens dessa conta e apaga o acesso. | apaga, cobra ou tem custo · provisioning |
pause_chatbot | A pausa de emergência: a IA e os envios param em todos os canais; os canais seguem conectados e a equipe responde pelo painel. | muda · provisioning |
resume_chatbot | Tira a pausa do dono (feita pelo painel ou pela API). | muda · provisioning |
get_account_usage | O uso de um mês por cliente e chatbot: atendimentos (a unidade da cota), mensagens e envios de campanha. | só lê · provisioning |
list_client_members | As pessoas da equipe do cliente no portal (gestor ou atendente) e quem convidou cada uma. | só lê · members |
invite_client_member | Convida uma pessoa da equipe do cliente para o portal (manager: tudo o que a agência liberou; agent: só as conversas). | muda · members |
remove_client_member | Tira o acesso da pessoa ao portal do cliente na hora. | apaga, cobra ou tem custo · members |
| Ferramenta | O que faz | Tipo |
|---|
update_chatbot_size | Troca o tamanho do chatbot (atendimento, P, M, G, volume ou null) e liga, desliga ou muda o teto do excedente. | apaga, cobra ou tem custo · billing |
get_chatbot_usage | Tamanho, cota e uso do mês do chatbot, a fase (cota, excedente ou parado), a projeção, o tamanho sugerido, a troca agendada e o excedente. | só lê · billing |
get_credit | O saldo de crédito da conta (paga o excedente dos chatbots), os lotes que ainda valem e a recarga automática. | só lê · billing |
pay_for_credit | Compra crédito para a conta, de R$ 50 a R$ 50.000, cobrado na hora no cartão da assinatura. | apaga, cobra ou tem custo · billing |
| Ferramenta | O que faz | Tipo |
|---|
get_agenda | Os serviços (com a duração, o preço e quem faz), os profissionais, as regras (antecedência, dias à frente, até quando remarcar) e o horário da agenda do chatbot. | só lê · agenda |
get_availability | Os horários livres de um serviço num dia (no fuso do chatbot), com as mesmas regras que a IA segue: o serviço inteiro cabe, sem bater com outro horário, folga ou vaga cheia. | só lê · agenda |
list_appointments | Os horários da agenda, por começo: de hoje até 30 dias à frente, ou o período pedido (até 92 dias). | só lê · agenda |
create_appointment | Marca um horário livre (veja get_availability antes) para um contato do chatbot ou um número de WhatsApp novo. | muda · agenda |
update_appointment | Remarca o horário (start_at e, se quiser, professional_id) ou muda a situação (status: booked aprova o pedido que esperava a equipe; attended, compareceu; no_show, faltou, só depois do começo do horário). | muda · agenda |
cancel_appointment | Cancela o horário (ou recusa o pedido que esperava a equipe) e libera a vaga. | apaga, cobra ou tem custo · agenda |
- O ritmo: 10 pedidos por segundo, com rajada de 50, por chave ou conexão. Cada ferramenta é um pedido.
- O registro: cada chamada fica 30 dias em Integrações → Registros, com o nome da conexão.
- A
idempotency_key é a Idempotency-Key da API: obrigatória em send_campaign, create_chatbot e pay_for_credit (e em update_chatbot_size com size), opcional nos envios. Repetir com a mesma chave em 24 horas não faz de novo. - O endereço do contato é o da API:
ctc_…, phone:55…, wa:…, ig:… ou ext:….