API or dashboard: what an agency uses to manage multiple WhatsApp numbers
A small agency starts with the dashboard and does fine. The problem shows up when onboarding becomes a bottleneck: creating the instance, noting the client, setting up the webhook and checking the cost, all by hand, for the tenth, twentieth, fortieth client. That is the point where the API starts paying back its own development cost. This guide shows what to do in each, the calls that help most and what still belongs to the dashboard. Everything refers to ZapZap, an unofficial API.
Published on · 4 min read
When the dashboard is enough
Up to a few dozen numbers, with few new clients per month, the dashboard handles it: create the instance, connect by QR code, turn on warm-up, set up the AI and the Flow Builder and configure the client portal. Each action takes minutes, and you learn the product before automating it. Automating too early means spending development time on a process that is still going to change.
The dashboard is also the place for everything visual and judgment-based: building flows, tuning the AI's tone, reading conversations, setting the client's brand and the portal sections. None of that is in the management API.
When the API pays off
The API pays off when the same work repeats: each new client requires the same five steps. A clear sign is onboarding competing with delivery for the team's time. Another is already having your own system (CRM, ERP, agency portal) where the client is born, and wanting the instance to be born with it.
The management API creates, lists, looks up and removes instances with a key and secret, returns the cost before creation and lets you store a metadata field on the instance. The authentication docs and the reference list every field.
The calls that help most
The first is checking the cost (GET /instances/cost), so your automation can check the balance before creating. The second is creating the instance (POST /instances), storing the client identifier and plan in metadata. The third is registering the instance webhook (PUT /instances/{id}/webhook), pointing to your system; each event arrives with the metadata, so you know whose it is.
The example below combines the first two. Keep the key and secret in environment variables, never in code or in the front end.
Check cost and create the client instance
# Create a new client instance and store who the client is in metadata
curl -X POST "https://api.zapzapapi.com/api/v1/instances" \
-H "Content-Type: application/json" \
-H "x-api-key: $ZAPZAP_API_KEY" \
-H "x-api-secret: $ZAPZAP_API_SECRET" \
-d '{"name":"cliente-a-loja-centro","metadata":{"customerId":"cli_123","plan":"basico"}}'
# Before that, to see the activation fee and the balance needed:
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
-H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"What stays in the dashboard even with the API
Even a 100% automated agency goes back to the dashboard to: scan the QR code (done by the client, through the connection link), set the client's brand, build and copy flows, tune the AI, open the portal and follow each number's signals. The design that works is hybrid: API for what repeats, dashboard for what takes judgment.
For the client, the portal is the dashboard layer they use. They open it by link or by number and password, see leads and sales and reconnect the QR code, without accessing your account. See the page on resale under the client's brand.
A three-stage path
Stage 1, up to about 10 numbers: everything through the dashboard, with the operations sheet (see how to organize dozens of numbers). Stage 2, from 10 to 30: automate creation and the webhook by API, keeping the rest in the dashboard. Stage 3, above that: connect instance creation to your CRM, receive events at a single endpoint and track number health in a view of your own.
At every stage, the cost is the same per number: R$15 per month, no per-message fee. See how much it costs to run 10, 25 or 50 numbers and the page for agencies.
Cautions when automating
Automation creates numbers fast, and numbers created too fast become chips used for sending too early. Put a brake on bulk creation: your automation should create the instance, but starting to send depends on the warm-up phase. Check idempotency on creation (do not create the same client's instance twice) and log insufficient-balance errors, which should alert a person.
Automating does not reduce the risk of the unofficial channel. WhatsApp may limit or block numbers, and the WhatsApp API does not change that.
Quick summary
- The dashboard is enough for the first clients and for everything visual: flows, AI, branding and portal.
- The API pays off when onboarding repeats and becomes a bottleneck, or when the client is already born in your system.
- Three calls cover most of it: cost, create instance with metadata and register webhook.
- The metadata comes back on every webhook, so you identify the client without a parallel table.
- Automating creation does not replace warm-up: the number's phase is what unlocks sending.
Keep reading
Also read
Frequently asked questions
Can I create instances by API?
Yes. The management API creates, lists, looks up and removes instances with a key and secret, and GET /instances/cost shows the activation fee and the balance required before creation.
What is the metadata field?
It is a free-form field on the instance where you store, for example, the client identifier and plan. It comes back on the instance lookup and on every webhook.
Do I need a developer to use ZapZap at an agency?
Not to start: the dashboard does the essentials without code. The API comes in when repeated onboarding justifies automating.
Does the API cover setting the client's brand?
Not end to end. Name, logo, color and the portal sections are configured in the dashboard, per instance.
Does automating creation increase the risk of a ban?
It can, if the automation unlocks sending right after creating the number. Keep phased warm-up as a condition for sending, and remember the unofficial channel carries risk even with good practices.
Create your first instance by API
Create the account, generate the API key and run the guide's calls. R$15 per active number per month, no per-message fee. Verify your phone and you get a welcome credit, subject to the current campaign.