API reference

API reference

Everything is set up from your dashboard. Work through the steps below; the API base URL for your integration is https://www.wacentraconnectapi.com/api/v1.

Auth#

  1. Create an account. On the website click Get started, register, then enter the code sent to your email.
  2. Sign in. Click Log in, enter your email and password, then the code sent to your email.
  3. Create an API key. In the sidebar open Links, open your link, then open the API or Webhook tab and find API access for this link. Click Generate key and copy it — it is shown only once. Send it as Authorization: Bearer <key>.
  4. Manage keys. Open API in the sidebar to review or revoke tokens.
  5. Forgot your password? On the login page click Forgot password, enter your email, then the emailed code, and set a new password.

Account#

  1. Open your account. Click My account at the bottom of the sidebar (or your avatar in the top bar).
  2. Update your profile. Edit your name and click Save profile. To change your email, click Change email and enter the code sent to the new address.
  3. Change your password. Use Update password (or Set password if you signed up with Google). Confirm the code sent to your email.
  4. Sign-in methods. Link or unlink Google in the Sign-in methods section.
  5. Check your plan. The Subscription and Usage sections show your current package, messages used and API tokens.

Plans#

  1. Open Packages in the sidebar.
  2. Choose Monthly or Yearly, and pick your currency (e.g. KES) if offered.
  3. Pick a package card and click Start free trial or Continue to check out.
  4. The same page shows your current package, message usage and the links included.

Subscriptions#

  1. Open Packages to see your current subscription and its limits.
  2. Choose another package and complete checkout; the new package starts right away and replaces the old one.
  3. Open My account to confirm the active Subscription.
  4. Open Billing for payment history and receipts.

Links#

  1. Open Links in the sidebar.
  2. Click + Create link.
  3. Enter the WhatsApp number, optionally adjust Account protection and Enable Webhook Notifications, then click Create & Connect Link.
  4. The link page opens with tabs: Connection, Credentials, Messages, API, Webhook and Docs.
  5. Use Rotate URL, End link or Delete link on the link page when needed. The Credentials tab shows the link ID (and API URL) you use in your system.

WhatsApp connection#

  1. Open your link and go to the Connection tab.
  2. Click Generate QR Code.
  3. On your phone open WhatsApp → Settings → Linked devices → Link a device, then scan the QR code.
  4. Wait until the link shows Connected / Active. You can now send and receive messages.
  5. Click Disconnect to unlink the device.

Messages#

  1. Make sure the link is connected (Connection tab shows Active).
  2. Open the Messages tab to see incoming and outgoing messages and their status.
  3. Use Refresh to reload and Reveal contacts to show phone numbers.
  4. To send from your own system, copy the API key (Auth steps) and the link ID from the API tab, then call the send endpoint shown there.
  5. Send media as base64 JSON to /whatsapp/images (JPEG, PNG or WebP, max 5 MB), /whatsapp/videos (MP4 or 3GP, max 16 MB), or /whatsapp/documents (PDF, max 5 MB). Include filename, mime_type, and an optional caption.
  6. Send audio or voice notes to /whatsapp/audio (base64, max 16 MB, set voice_note: true for a voice note), stickers to /whatsapp/stickers (WebP, max 1 MB), contact cards to /whatsapp/contacts, locations to /whatsapp/locations, and polls to /whatsapp/polls. Send a video with gif: true to deliver it as a GIF. Add reply_to to text and media sends to quote an earlier message.
  7. Send a view-once message to /whatsapp/view-once with type set to image, video or audio, plus filename, mime_type, data and an optional caption. The recipient can open the media only once.
  8. Message operations: POST /whatsapp/reactions (send an emoji, or an empty one to remove it), POST /whatsapp/messages/{wa_message_id}/edit, DELETE /whatsapp/messages/{wa_message_id} (revoke for everyone), POST /whatsapp/messages/read, and POST /whatsapp/typing / /whatsapp/presence. These operations do not consume the message allowance.
  9. Groups: list with GET /whatsapp/groups, create with POST /whatsapp/groups, and read with GET /whatsapp/groups/{jid}. List participants with GET /whatsapp/groups/{jid}/participants, add or remove them with /participants/add and /participants/remove, or use POST /whatsapp/groups/{jid}/participants with action set to add, remove, promote or demote. Read the profile picture with GET /whatsapp/groups/{jid}/picture, update the subject, description, announce or restrict settings with PUT /whatsapp/groups/{jid}/settings, and leave with POST /whatsapp/groups/{jid}/leave. Get the invite link with GET /whatsapp/groups/{jid}/invite-link. Reset it with POST /whatsapp/groups/{jid}/reset, which revokes the current link so existing links stop working (it does not clear encryption keys); inspect or accept an invite code with GET /whatsapp/groups/invite/{code} and POST /whatsapp/groups/invite/accept. To send to a group, pass its @g.us JID as to to any send endpoint; add mentions to a text message to notify selected members. WhatsApp only highlights a mention when the text also contains @ followed by that number. Check whether numbers have WhatsApp with POST /whatsapp/contacts/validate.
  10. Communities and channels: list with GET /whatsapp/communities, create with POST /whatsapp/communities, and read metadata with GET /whatsapp/communities/{jid}. List linked groups with GET /whatsapp/communities/{jid}/groups, link an existing group with POST /whatsapp/communities/{jid}/groups, unlink with DELETE .../groups/{group}, and create a group inside the community with POST .../groups/create. Update the subject or announce/restrict settings with PUT .../settings, leave with POST .../leave, and inspect an invite with GET /whatsapp/communities/invite/{code}. Send to a community announcement group or a newsletter channel by passing its @g.us or @newsletter JID as to to any send endpoint.
  11. Contacts: list synced contacts with GET /whatsapp/contacts (page with limit and cursor; check sync.complete before treating an empty list as "no contacts"), read one with GET /whatsapp/contacts/{contact}, and get its profile picture with GET /whatsapp/contacts/{contact}/picture. Block or unblock with POST .../block and POST .../unblock, and create or update an address-book entry with PUT /whatsapp/contacts using phone plus first_name, last_name or full_name. Resolve LIDs with GET /whatsapp/lid-from-pn/{phone} and GET /whatsapp/pn-from-lid/{lid}.
  12. Incoming images, videos, audio, stickers and PDFs are relayed to your webhook as base64 in data.media.data, with the filename, MIME type and size alongside. WaCentra Connect API keeps the file only until your endpoint accepts it or the retries run out. Then the bytes are removed and the filename, MIME type and size stay in the delivery log. Inbound files up to 16 MB are relayed.
  13. Base64 adds about one third to the payload. Set PHP's post_max_size and upload_max_filesize to at least 24M to send or receive 16 MB videos.
  14. Status flow: Pending → Sent → Delivered → Read (or Failed). Messages over the rate limit are queued automatically.
  15. List messages with GET /whatsapp/messages (cursor paginated, newest first) and filter by direction, type, status, wa_message_id, since and until. Fetch one with GET /whatsapp/messages/{wa_message_id}; the same WhatsApp id is used by edit, delete and reactions.
  16. For testing, open Developer, turn on Sandbox mode for the link and click Test message.

Webhooks#

  1. Open your link and go to the Webhook tab, then click Configure webhook.
  2. Turn on Enable webhook and enter a public https payload URL.
  3. Choose the events to send (e.g. messages.received) and click Save Changes.
  4. Copy the Webhook Secret; click Rotate to replace it later.
  5. Incoming events are signed with X-Webhook-Signature-V2. See Events for payloads.
Webhooks are locked while Sandbox mode is on. Turn it off on the Developer page to manage them.

© 2026 WaCentra Connect API. All rights reserved.