Agency client WhatsApp onboarding in 15 minutes: schedule and script

Have the account balance ready (the agency pays, the client needs no account), the naming standard and your system's webhook address. If the balance falls short of the activation fee, creation fails and the call stalls. Check GET /instances/cost beforehand, which reports the activation fee, the prorated amount and the balance needed.

In the meeting confirmation, set a single requirement: the client must be holding the phone that has the number, with WhatsApp open. That avoids the worst onboarding delay, the client who is 'right back' with the device.

Create the instance by API, with a standard name and the client identifier in the metadata field, which comes back when you look up the instance. The example below shows the cost, the creation and the status check. The metadata field is JSON text, hence the escaping in the example.

Then, in the instance panel, generate the connection link. In the product's code the link has an expiry and can be revoked, and it opens a page where the client scans the QR code, with no account. Set the client's brand (name, logo and color) before sending, so they see their own identity on the page.

# Minute 3: check cost, then create the client's instance
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

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":"clinica-sol-vendas","systemName":"Clinica Sol","metadata":"{\"clientId\":\"cli_042\",\"owner\":\"ana\"}"}'

# Minute 10: confirm the number is connected before the first real message
curl "https://api.zapzapapi.com/api/v1/INSTANCE_ID/instance/status" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

Send the link in the meeting chat and ask: open it on the phone that has the number, tap to connect and scan the QR code from WhatsApp (linked devices). Stay quiet at this point: the QR expires and the client makes more mistakes when interrupted. If it expires, generate it again and resend.

Message ready to paste: "Hi! Here is the link to connect [Company]'s WhatsApp to the platform. Open it on the phone that has the number, scan the QR code and that is it. It takes about a minute. If the code expires, tell me and I will generate another." Confirm in the instance status that the number is connected before moving on.

Set the instance webhook to your system and use the API's webhook test (POST /instances/{id}/webhook/test), which sends a test event signed with the instance secret. Check that your endpoint validated the signature and answered 200. To do this safely, see the guide on idempotent webhooks.

Then ask the client to send a message from another phone to the connected number and watch the event arrive in your system. Reply with a short send/text. That round-trip test is worth more than any verbal guarantee.

Hand over access to the client portal (by link, or by number and password, sent through different channels) with the sections you decided to show. Say what they will see and when: leads, sales and performance for the period. Agree on who reconnects the QR if the number drops, and set the date of the first review.

Close with the risk alignment, in one sentence: it is an unofficial solution, WhatsApp may limit or block the number, and that is why a new number starts slowly. Point to chip warm-up and, if the client runs ads, to the flow for leads per client. The full checklist is in the onboarding checklist.