BoaVoz
Documentação · Integrações

MCP para agentes de IA

Conecte o BoaVoz a apps de agentes de IA, como o agentes.chat, e a qualquer cliente de MCP. O agente lê as conversas, os contatos e os leads, responde, pausa a IA numa conversa, manda campanhas e cuida da base, com as mesmas regras da API.

Endereço

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.

Duas formas de conectar

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.

Comece pelo whoami

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"
}

Ferramentas

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_).

Conversas e pausa

FerramentaO que fazTipo
list_conversationsAs 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_messagesAs 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_aiPausa a IA numa conversa para o seu sistema (ou você) responder por send_message.muda · conversations
resume_conversation_aiTira a pausa da IA na conversa na hora; a IA responde a última mensagem do contato se ela ficou sem resposta.muda · conversations
get_mediaO 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

Mensagens

FerramentaO que fazTipo
send_messageEnvia 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_messageUma mensagem (msg_…) com o status: received, pending, sent, delivered, read, failed (com error.code) ou uncertain.só lê · messages
list_templatesOs 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

Contatos e leads

FerramentaO que fazTipo
list_contactsOs 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_contactGrava 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_tagsTroca todas as etiquetas do contato pela lista (lista vazia apaga todas).muda · contacts
set_contact_ageA empresa informa a idade que conferiu (para bebida alcoólica e remédio, só para quem tem 18 anos).muda · contacts
delete_contactPedido 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_leadsUm lead por contato em cada chatbot: nome, telefone, e-mail, o pedido mais recente e o histórico de pedidos.só lê · contacts

Campanhas e aceite

FerramentaO que fazTipo
send_campaignCampanha 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_campaignO 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_consentGrava o aceite (ou a retirada) de novidades no WhatsApp com a prova: onde, o texto aceito e quando.muda · campaigns

Pareamento

FerramentaO que fazTipo
create_pairingGera 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_linksOs vínculos ativos do contato com contas do seu sistema (pelo código ou lembrados pelo roteiro).só lê · pairing
delete_contact_linkDesfaz o vínculo do contato com a conta do seu sistema (sai o webhook contact.unlinked).apaga, cobra ou tem custo · pairing

Fontes e aviso do momento

FerramentaO que fazTipo
add_sourceGrava 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_sourcesAs fontes do chatbot, as mais novas primeiro.só lê · sources
delete_sourceTira a fonte (src_…) e os trechos dela da base do chatbot.apaga, cobra ou tem custo · sources
get_noticeO 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_noticePõ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_noticeTira o aviso do momento do chatbot antes do prazo.muda · sources ou provisioning

Lojas pela API

FerramentaO que fazTipo
create_clientCria o cliente (a loja).muda · provisioning
get_clientOs dados do cliente (cli_…), os chatbots dele com os canais conectados e a conformidade.só lê · provisioning
create_chatbotCria 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_chatbotMuda 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_linkO 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_channelsOs 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_channelDesconecta 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_chatbotA 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_chatbotTira a pausa do dono (feita pelo painel ou pela API).muda · provisioning
get_account_usageO uso de um mês por cliente e chatbot: atendimentos (a unidade da cota), mensagens e envios de campanha.só lê · provisioning
list_client_membersAs pessoas da equipe do cliente no portal (gestor ou atendente) e quem convidou cada uma.só lê · members
invite_client_memberConvida 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_memberTira o acesso da pessoa ao portal do cliente na hora.apaga, cobra ou tem custo · members

Cobrança

FerramentaO que fazTipo
update_chatbot_sizeTroca 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_usageTamanho, 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_creditO 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_creditCompra 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

Agenda

FerramentaO que fazTipo
get_agendaOs 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_availabilityOs 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_appointmentsOs 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_appointmentMarca um horário livre (veja get_availability antes) para um contato do chatbot ou um número de WhatsApp novo.muda · agenda
update_appointmentRemarca 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_appointmentCancela o horário (ou recusa o pedido que esperava a equipe) e libera a vaga.apaga, cobra ou tem custo · agenda

Regras que valem igual à API

  • 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:….