Account and integrations
Connect an external system or assistant
Create a scoped Pro or Agency key, publish fresh content, or connect an assistant.
Before you begin
A webhook receives incoming-message notices from the WhatsApp service. Its server setup belongs to the integration operator. Panel users do not need to change server settings. MCP lets an assistant request account tools.
What to do
- For incoming messages, open Settings and locate the Webhook URL.
- Choose Copy to obtain the exact address for your account’s deployment.
- Ask the operator to configure incoming events for the intended device with that address.
- Arrange an incoming test message from your own number once the operator confirms readiness.
- Check the result you expect, such as a matching automatic reply or a newly recorded group message when Log is enabled.
- For an assistant connection, sign in through the authorization screen opened by your MCP client.
- Review the named application and account before approving access.
- For outbound integration, open Settings → External integrations. Create a named key for one connected account and explicitly selected groups. Save the key immediately; it is shown only once. Copy the API base URL.
- Example: Configure Abacus.AI to generate fresh content at each of eight daily publication times in America/Sao_Paulo. Submit each publication to three allowed groups with a new Idempotency-Key. Reuse the key only to retry the identical request.
- Omit scheduled_at to queue immediately, or use an absolute timestamp with -03:00 or Z (UTC), up to 30 days ahead. The processor checks each minute; scheduled_at is the earliest eligible time, without an exact-second delivery guarantee.
- Check job status and per-group outcomes before retrying. Cancel only sends not yet dispatched. Revoke a compromised key in Settings, then create and save a replacement; old jobs do not resume with a new key.
Worked example
Placeholder requests; replace the IDs and choose a future date before sending. These requests publish real messages. curl '<API_BASE_URL>/v1/groups' -H 'Authorization: Bearer <ZAPBOT_API_KEY>' curl -X POST '<API_BASE_URL>/v1/jobs' -H 'Authorization: Bearer <ZAPBOT_API_KEY>' -H 'Idempotency-Key: publication-2026-10-16-0900' -H 'Content-Type: application/json' --data '{"type":"text","group_ids":["<GROUP_JID_1>","<GROUP_JID_2>","<GROUP_JID_3>"],"text":"Updated publication","scheduled_at":"2026-10-16T09:00:00-03:00"}' curl -X POST '<API_BASE_URL>/v1/jobs' -H 'Authorization: Bearer <ZAPBOT_API_KEY>' -H 'Idempotency-Key: publication-2026-10-16-1200' -F 'payload={"type":"image","group_ids":["<GROUP_JID_1>","<GROUP_JID_2>","<GROUP_JID_3>"],"caption":"Updated caption"}' -F 'image=@publication.png;type=image/png' curl '<API_BASE_URL>/v1/jobs/<JOB_ID>' -H 'Authorization: Bearer <ZAPBOT_API_KEY>' curl -X DELETE '<API_BASE_URL>/v1/jobs/<JOB_ID>' -H 'Authorization: Bearer <ZAPBOT_API_KEY>'
How to check it worked
Job acceptance and accepted group outcomes confirm gateway acceptance. They do not confirm delivery or reading. Scheduled work can be blocked if access, the key, account or group permissions change.
What to know
- Assistants can read exposed records and send text when requested. Review the assistant-tools guide before requesting a send.
- Use the panel for editing actions unavailable through MCP.
- API access includes Pro and Agency monthly or yearly plans. Starter requires an upgrade. Keys permit only their selected account and groups; replacing the WhatsApp account blocks sending. Never share server credentials.
- Text supports 4,096 characters; captions 1,024. Upload JPEG, PNG or WebP up to 5 MiB as multipart fields payload and image. Remote image URLs are not accepted.
- A new job returns HTTP 202. An identical Idempotency-Key retry returns the original job with HTTP 200; different content with the same key returns 409. A timeout after dispatch can be unconfirmed; do not automatically resubmit under another key.
Common problems
- What you see
- No reply or new record appears after the test.
- What to do
- Check the device connection and the relevant rule or Log setting, then ask the operator to verify incoming-event configuration.
- What to expect
- A correctly configured feature can process a new matching event.
- What you see
- The assistant cannot authorize or shows another account.
- What to do
- Return to sign-in and select the intended account; report repeated authorization errors to the operator.
- What to expect
- The authorization screen and returned records belong to the intended account.
Get more help
Give the operator the feature and visible error. Keep server credentials out of assistant conversations.