Reference — AI connector tools
This page is generated from the server's catalog (apps/api/internal/mcp). To connect and learn the rules, see the AI connector guide.
whoami — Who am I
Start here. Returns the bZapper projects this connection reaches with the rail of each (unofficial = WhatsApp by QR code, official = Meta WhatsApp Cloud API), your role and permissions, the plan with its monthly quota and current usage, and the tools available to you.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
list_numbers — List WhatsApp numbers
Lists the project's WhatsApp numbers with their connection status and health. On the official rail it also shows Meta's quality rating and messaging limit for each number.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
get_number_health — Check a number's health
One number in depth. QR rail: current status, since when, the share of time connected in the last 24h, 7d and 30d, and the latest drops and recoveries. Official rail: Meta's quality rating, messaging limit tier and the account status.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
list_conversations — List inbox conversations
Lists the most recent WhatsApp conversations of the project (newest first) with the contact name, a preview of the last message, unread count and, on the official rail, when the contact last wrote (the 24-hour window).
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
get_conversation — Read a conversation
Returns the message history of one WhatsApp conversation, newest first. Page back with before.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
mark_conversation_read — Mark a conversation as read
Marks the contact's latest messages in a conversation as read. The contact sees the read receipt.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Send messages (bzapper:send) | admin and agent | idempotent openWorld |
send_message — Send a WhatsApp message
Sends a WhatsApp message to ONE recipient on your behalf: text, optionally with an image or document. Respects opt-outs and the plan quota. On the official rail, free text only works within 24 hours of the contact's last message; otherwise use send_template. To reach many consented contacts, prepare a campaign instead.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Send messages (bzapper:send) | admin and agent | destructive openWorld |
send_template — Send a message template
Official rail. Sends an approved WhatsApp template to ONE recipient, with its variables. This is how to start a conversation, or reply after the 24-hour window closed. Meta bills the conversation directly to the customer.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| Official | Send messages (bzapper:send) | admin and agent | destructive openWorld |
send_otp — Send a verification code
Sends a one-time verification code to ONE recipient: the text in the account's language plus the code. The code is never stored nor shown back, not even in this tool's result.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Send messages (bzapper:send) | admin and agent | destructive openWorld |
search_contacts — Search contacts
Searches the project's contacts by name, phone, email, tags or consent status. Returns each contact with tags and consent status, plus the total that matched.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
get_contact — Get a contact
Returns one contact in full: tags, groups, notes, consent with its source and date, suppression with its reason, and the latest events of its history.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
save_contact — Create or update a contact
Creates a contact (with phone) or updates one (with id): name, email, document. Fields left out are kept. bZapper links the contact to projects and numbers by itself as conversations happen.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Manage contacts (bzapper:contacts) | admin and agent | idempotent |
import_contacts — Import contacts
Imports up to 1000 contacts who agreed to be contacted, upserting by phone. consent_source is required and becomes the tag origem-<source> on every row, so the origin of each contact stays visible. People who opted out or were blocked are skipped and never brought back. Use dry_run first to check.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Manage contacts (bzapper:contacts) | admin | — |
tag_contacts — Tag contacts
Adds or removes tags on up to 100 contacts. Tags are how audiences for campaigns are picked.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Manage contacts (bzapper:contacts) | admin and agent | idempotent |
block_contact — Stop messaging a contact
Records that a contact asked to stop receiving messages (opt_out), or blocks them (manual). From then on nothing is sent to them, campaigns included. Undoing it requires the bZapper app, where consent can be proven.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Manage contacts (bzapper:contacts) | admin and agent | destructive idempotent |
estimate_campaign — Estimate a campaign
Estimates a campaign for consented contacts before anything is created: how many recipients, which numbers can send and at what daily limit, and how long it takes. On the official rail, with a template, also Meta's estimated cost (billed by Meta directly to the customer). Sends nothing.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin | readOnly idempotent |
create_campaign — Prepare a campaign
Prepares a campaign as a DRAFT for contacts from the bZapper base who gave consent (by tags or ids; opted-out and blocked people are never included) and runs the simulation: recipients, numbers available, duration and warnings. It never starts the campaign: show the simulation to the person, and only if they agree call start_campaign with the confirmation returned here.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Campaigns and templates (bzapper:campaigns) | admin | — |
start_campaign — Start a campaign
Starts a draft prepared with create_campaign, after the person saw the simulation and agreed. Requires the confirmation from create_campaign; if the draft changed since then (recipients or message), prepare it again. Messages then go out at the numbers' pace, with opt-out on every one.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Campaigns and templates (bzapper:campaigns) | admin | destructive openWorld |
get_campaign — Get campaigns
Without id, lists the latest campaigns with their status. With id, returns one campaign: status, sent, delivered, read, failures by reason and opt-outs.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin | readOnly idempotent |
pause_campaign — Pause a campaign
Pauses a running campaign right away. Messages already sent stay sent; the rest waits until it is resumed in the bZapper app.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Campaigns and templates (bzapper:campaigns) | admin | idempotent |
list_templates — List message templates
Official rail. Lists the project's WhatsApp message templates with their review status at Meta and, when rejected, the reason. With id, returns one template in full.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
validate_template — Check a template draft
Official rail. Checks a template draft against Meta's rules before it is submitted and lists what would get it rejected. Creates nothing and submits nothing.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| Official | Read (bzapper:read) | admin and agent | readOnly idempotent |
create_template — Create a message template
Official rail. Creates a WhatsApp message template and submits it to Meta's review — written from scratch or from Meta's ready-made library. Check the draft with validate_template first. Review takes from minutes to a day; list_templates shows the status.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| Official | Campaigns and templates (bzapper:campaigns) | admin | openWorld |
search_help — Search the bZapper help
Searches the bZapper app's built-in help (in Portuguese) and returns the matching sections: the steps, the screen and the messages the person will see. Use it to explain how to do something in the bZapper app, such as connecting a number or importing contacts.
| Rail | Permission | Role | Annotations |
|---|---|---|---|
| QR, Official | Read (bzapper:read) | admin and agent | readOnly idempotent |