Z-API
MessagingConnect AI agents to Z-API, a Brazilian REST API that connects a WhatsApp account to your automations. Agents send text, media, and interactive messages, manage chats, contacts, groups, and communities, and administer the WhatsApp Business profile and catalog so WhatsApp operations run programmatically.
What This Integration Enables
Z-API is a Brazilian REST API that links a WhatsApp account to your automations, and it is the broadest WhatsApp surface in FlowRunner's catalog. Two hundred and ten actions cover sending in every message shape WhatsApp supports, the session and its QR or pairing-code connection, chats, contacts, groups, communities, broadcast lists and channels. They also cover status posts, calls, privacy settings, and the WhatsApp Business profile, catalog, collections and chat labels. Access is outside Meta's official Cloud API, and connected accounts remain subject to WhatsApp's terms. Credentials are per instance, so one FlowRunner connection addresses exactly one WhatsApp number, and the instance identifier and token together are effectively a password for that number.
The design detail worth building your flows around is the queue. Z-API deliberately spaces outbound messages behind the paired handset to look like a person rather than a burst, with a random gap by default that individual messages can extend. If the handset goes offline, messages do not fail. They accumulate up to a vendor-stated ceiling and are flushed automatically when it reconnects. The vendor's own guidance is to check the queue before reconnecting, and the connector exposes exactly the actions that make that possible. List Queued Messages and Search Queued Messages read it, the latter with cursor paging built for a long backlog. Delete Queued Message and Clear Message Queue prune it, and Update Queue Settings can block queueing entirely while an instance is disconnected. There are no triggers here, and the reason is stated plainly rather than hidden: each event type has one URL slot per instance with no route to read the current value back, so registering a FlowRunner callback would silently overwrite an endpoint the customer already depends on. The nine webhook routes ship as actions instead, so you point Z-API at an endpoint you control.
Without FlowRunner
With FlowRunner
Use Case Scenarios
An agency running one WhatsApp number per client
An agency operates a number for each client, each with its own instance credentials and its own FlowRunner connection. A nightly flow sweeps Get Instance Status across all of them, reports any instance where the handset has dropped, and holds the queue rather than restarting. Order confirmations come in from WooCommerce, go out with Send Text and Send Image, and are recorded against the customer in Google Sheets. Where a client's number sends catalog links, Search Products and Send Product put the right item in the thread instead of a URL the customer has to interpret.
An order thread that stays in one place
A customer places an order in the WhatsApp Business catalog. The order reference arrives on the customer's own webhook endpoint, which the agency points Z-API at using Set Received Message Webhook. The agent picks it up, calls Send Order to confirm the line items, moves it along with Update Order Status as fulfilment progresses, and marks payment with Update Order Payment when Stripe settles. If payment is due, Send PIX Button attaches the payment key directly to the thread so the customer never leaves the conversation. Every state change is written back to the order record, so the WhatsApp thread and the system of record never diverge.
Community and group hygiene at scale
A customer community runs across several linked groups. The agent keeps the roster current with Add Group Participants and Remove Group Participants against the subscriber list. It reads membership with Get Group Metadata Light rather than the full metadata call, so a large group does not stall the flow, and rotates invite links with Reset Group Invitation Link on a schedule. Join requests are read with the group metadata and resolved by Approve Group Participants for numbers already on the subscriber list, while unknown numbers are posted to Slack for a human call. Update Group Settings is used carefully and rarely, because it replaces all four permission flags at once, and the connector refuses the call rather than letting an omitted flag silently reset a permission.
Human-in-Loop Highlight
The gate on Z-API is the reconnect, and it is a gate precisely because it does not look like one. When a paired handset drops, outbound messages do not error. They queue, up to a vendor-stated ceiling, and the moment the session is restored the queue flushes automatically. An agent watching a disconnected instance has an obvious remedy in front of it, Restart Instance, and calling it would be the single most destructive thing this connector can do. An entire day of appointment reminders, delivery notices and payment requests lands at once, in an order and at a time that made sense yesterday, on people who have since arrived, rescheduled or paid.
So the agent does not restart. It reads. Search Queued Messages walks the backlog with cursor paging built for exactly this, and the agent resolves every queued recipient against the record that generated the message: this reminder is for an appointment that already happened, this delivery notice is for an order already collected, these forty are still accurate. Then it stops and posts to the operations channel: "Instance cliente-norte has been offline 14 hours with 212 messages queued. 71 are appointment reminders for slots that have now passed, 18 are delivery notices for orders already marked collected, 123 still hold. Restarting the instance sends all 212. Clear the 89 stale entries first and then reconnect, or clear the whole queue?" A person answers, the agent removes exactly what it was told to remove with Delete Queued Message, and only then restores the session. This is what an automation exception looks like when the platform is doing something reasonable and the situation is not: nothing failed, no error was raised, and the only thing standing between a working queue and two hundred wrong messages is somebody who knows which of them are still true.
Agent Capabilities
210 actionsInstance and Session
19- Get Instance Status Reports whether the instance is connected and whether the paired handset is reachable. The first read of any health sweep.
- Get Connected Device Returns the physical handset behind the instance, including its model and whether the account is a WhatsApp Business account.
- Get Instance Settings Returns the instance's current configuration.
- Get QR Code Returns the pairing QR code as data. Only meaningful while the instance is waiting to pair.
- Get QR Code Image Returns the pairing QR code as an image a flow can display to whoever holds the phone.
- Get Pairing Code Returns a pairing code as an alternative to scanning.
- Disconnect Instance Ends the live WhatsApp session. The number stops sending and receiving until someone pairs it again.
- Restart Instance Restarts the instance without unlinking it. Note that restoring a session flushes whatever accumulated in the message queue while it was down.
- Rename Instance Renames the instance inside the Z-API panel.
- Update Profile Name Changes the display name customers see on the WhatsApp account.
- Update Profile Description Changes the About text.
- Update Profile Picture Changes the profile image.
- Update Auto Read Messages Controls whether incoming messages are automatically marked as read.
- Update Auto Read Status Controls whether contacts' status posts are automatically marked as viewed.
- Update Auto Reject Calls Controls whether incoming calls are rejected automatically, which is how a messaging number stops ringing.
- Update Call Reject Message Sets the message sent when a call is auto-rejected, so a caller gets an answer rather than silence.
- Get Extension Token Returns the token used by the vendor's browser extension.
- Reset Passkey Challenge Resets a pending passkey challenge on the account.
- Complete Passkey Challenge Completes a passkey challenge.
Sending Messages
19- Send Text Sends a text message. It can also edit a message already sent, which requires the webhook to be configured first.
- Reply To Message Sends a message as a threaded reply to a specific earlier one.
- Send Image Sends an image with an optional caption, from a public URL or a base64 payload.
- Send Video Sends a video with an optional caption.
- Send Audio Sends an audio file.
- Send Document Sends a document such as an invoice, a boleto or a shipping label.
- Send GIF Sends an animated GIF.
- Send Sticker Sends a sticker.
- Send Video Note Sends a circular video note.
- Send Link Preview Sends a link with its preview card rendered.
- Send Location Sends a coordinate with an optional name and address.
- Send Contact Sends a single contact card.
- Send Multiple Contacts Sends several contact cards in one message.
- Send Reaction Adds an emoji reaction to a message.
- Remove Reaction Removes a reaction previously added.
- Forward Message Forwards an existing message to another chat.
- Mark Message As Read Marks a message as read, which is what tells the customer the thread has been picked up.
- Delete Message Deletes a message. It defaults to deleting for everyone, and the delete-for-me toggle limits it to the connected account.
- Pin Message Pins a message in a chat so the current instruction stays at the top.
Interactive Messages
10- Send Action Buttons Sends a message with action buttons attached.
- Send Reply Buttons Sends quick reply buttons. Selections arrive on the received-message webhook.
- Send Option List Sends a selectable option list, which suits more choices than buttons allow.
- Send Carousel Sends a carousel of cards.
- Send OTP Button Sends a one-time-code button.
- Send PIX Button Attaches a Brazilian PIX payment key to the thread so a customer can pay without leaving the conversation.
- Reply To Button Acknowledges a button selection that arrived on the webhook.
- Reply To Template Button Acknowledges a template button selection.
- Send Poll Sends a poll with selectable options.
- Send Poll Vote Casts a vote in a poll from the connected account.
Events
3- Send Event Sends a WhatsApp event invitation to a chat or group.
- Edit Event Edits an event already sent.
- Respond To Event Responds to an event invitation from the connected account.
Orders and Products
5- Send Order Sends an order to a customer. Order references arrive on the received-message webhook when a customer places one from the catalog.
- Update Order Status Moves an order through its fulfilment states in the thread the customer is already reading.
- Update Order Payment Records payment against an order.
- Send Product Sends a single catalog product into a chat.
- Send Catalog Sends the business catalog.
Mentions
4- Mention All In Group Mentions every participant in a group. Use it deliberately, because it notifies everyone at once.
- Mention Participants In Group Mentions named participants in a group message.
- Mention Groups In Group Mentions linked groups in a group message.
- Message Meta AI Sends a message to Meta AI, either in a private chat or as a mention when a group is supplied.
Chats
9- List Chats Lists the chats on the instance.
- Get Chat Returns one chat with its metadata.
- Archive Chat Archives a chat.
- Pin Chat Pins a chat to the top of the list.
- Mute Chat Mutes a chat's notifications.
- Mark Chat Read Marks a chat as read.
- Clear Chat Clears the messages in a chat. Irreversible.
- Delete Chat Deletes the chat entirely. Irreversible.
- Set Chat Expiration Configures disappearing messages for a single chat. The account-wide default lives under privacy settings.
Contacts
9- List Contacts Lists the contacts on the paired phone.
- Get Contact Returns one contact.
- Get Profile Picture Returns a contact's profile image. The phone number is required, because omitting it produces a server error rather than an empty result.
- Check Number Has WhatsApp Confirms one number has a WhatsApp account.
- Check Numbers Have WhatsApp Validates a batch in one call and returns both the number you supplied and the number as WhatsApp normalized it, which matters where a leading digit was added or dropped.
- Add Contacts Writes contacts into the address book of the phone paired to the instance.
- Remove Contacts Removes contacts from that address book.
- Block Contact Blocks a number on the connected account, after which their messages no longer arrive.
- Report Contact Reports a contact to WhatsApp.
Groups
19- List Groups Lists the groups the instance belongs to.
- Get Group Metadata Returns a group with its full participant list.
- Get Group Metadata Light Returns a group without the participant list, which is much faster on a large group.
- Create Group Creates a group seeded with participants.
- Add Group Participants Adds participants to a group.
- Remove Group Participants Removes participants.
- Promote Group Admins Promotes participants to admin.
- Demote Group Admins Demotes admins back to participants.
- Approve Group Participants Approves pending join requests.
- Reject Group Participants Rejects pending join requests.
- Update Group Name Changes the group subject.
- Update Group Description Changes the group description.
- Update Group Photo Changes the group image.
- Update Group Settings Sets the group's permission flags. It replaces all four at once, so the full intended state has to be supplied and the connector refuses the call rather than letting an omitted flag reset a permission.
- Leave Group Leaves a group from the connected account.
- Get Group Invitation Link Returns the current invite link.
- Reset Group Invitation Link Invalidates the current link and issues a new one.
- Get Group Invitation Metadata Reads a group's details from an invite link before joining.
- Accept Group Invitation Joins a group from an invitation.
Communities
13- List Communities Lists the communities the account belongs to.
- Get Community Metadata Returns one community with its linked groups.
- Create Community Creates a community.
- Deactivate Community Deactivates a community.
- Update Community Description Changes the community description.
- Update Community Settings Changes community settings.
- Add Community Participants Adds members to a community.
- Remove Community Participants Removes members from a community.
- Promote Community Admins Promotes community members to admin.
- Demote Community Admins Demotes community admins.
- Link Groups To Community Links existing groups into a community.
- Unlink Groups From Community Unlinks groups from a community.
- Reset Community Invitation Link Invalidates the community's invite link and issues a new one.
Broadcast Lists
4- List Broadcast Lists Lists the broadcast lists on the account.
- Create Broadcast List Creates a broadcast list.
- Update Broadcast List Updates a broadcast list. It replaces the entire membership rather than merging additions, so supply the full intended list.
- Delete Broadcast List Deletes a broadcast list.
Channels
18- Send Channel Admin Invite Invites someone to administer a WhatsApp channel.
- List Channels Lists the channels the account follows or administers.
- Get Channel Metadata Returns one channel.
- Search Channels Queries WhatsApp's public channel directory, filtered by country code.
- Create Channel Creates a channel.
- Delete Channel Deletes a channel.
- Update Channel Name Changes a channel's name.
- Update Channel Description Changes a channel's description.
- Update Channel Picture Changes a channel's image.
- Update Channel Settings Changes a channel's settings.
- Follow Channel Follows a channel from the connected account.
- Unfollow Channel Unfollows a channel.
- Mute Channel Mutes a channel.
- Unmute Channel Unmutes a channel.
- Accept Channel Admin Invite Accepts an invitation to administer a channel.
- Revoke Channel Admin Invite Revokes an outstanding admin invitation.
- Remove Channel Admin Removes an existing channel admin.
- Transfer Channel Ownership Transfers ownership of a channel to another account.
Status
6- Post Text Status Posts a text status from the connected account. It reaches the account's contacts rather than an addressee.
- Post Image Status Posts an image status.
- Post Video Status Posts a video status.
- Reply To Status With Text Replies privately to someone's status with text.
- Reply To Status With GIF Replies to a status with a GIF.
- Reply To Status With Sticker Replies to a status with a sticker.
Message Queue
5- List Queued Messages Lists messages waiting behind the paired handset. The read that turns an invisible backlog into something a person can judge.
- Search Queued Messages Walks the queue with cursor paging, which is the reliable way through a long one. Its page size is capped and the cap is enforced before the request.
- Delete Queued Message Removes one message from the queue before it can be sent.
- Clear Message Queue Empties the queue entirely.
- Update Queue Settings Controls queueing behavior, including blocking queueing altogether while the instance is disconnected.
Calls
4- Send Call Places a WhatsApp call from the connected account. It rings for a documented maximum that is enforced before the request, and playing audio on answer needs an account with the calling feature enabled.
- Get Call Token Returns a call token.
- Get SIP Info Returns SIP connection details.
- Generate SIP Token Generates a SIP token.
Webhook Configuration
9- Set Received Message Webhook Points the received-message event at an endpoint you control. There is one slot per event type, so this replaces whatever was there.
- Set Delivery Webhook Points the delivery event at an endpoint.
- Set Message Status Webhook Points the message-status event at an endpoint.
- Set Connected Webhook Points the connected event at an endpoint.
- Set Disconnected Webhook Points the disconnected event at an endpoint. Worth wiring, because a disconnection is what starts the queue filling.
- Set Chat Presence Webhook Points the chat presence event at an endpoint.
- Set All Webhooks Sets every event slot to the same endpoint in one call.
- Set Notify Sent By Me Controls whether the account's own outbound messages are delivered to the webhook.
- Set Webhook Filters Sets the exclusion list. Anything listed is not delivered, and sending empty lists clears all filtering.
Privacy
8- Get Privacy Exceptions Returns the per-setting exception lists behind the contacts-except option.
- Set Last Seen Privacy Controls who sees the account's last seen.
- Set Profile Photo Privacy Controls who sees the profile photo.
- Set About Privacy Controls who sees the About text.
- Set Group Add Privacy Controls who may add the account to groups.
- Set Online Privacy Controls who sees the account online.
- Set Read Receipts Turns read receipts on or off for the account.
- Set Default Message Duration Sets the account-wide disappearing message default.
Business Profile
8- Get Business Profile Returns the WhatsApp Business profile. Requires a Business account.
- List Business Categories Lists the categories the profile can declare.
- Set Business Categories Sets the profile's categories.
- Set Business Description Sets the business description.
- Set Business Address Sets the business address.
- Set Business Email Sets the business email.
- Set Business Websites Sets the business websites.
- Set Business Hours Sets opening hours, which is what customers see before they decide whether to expect an answer.
Catalog
8- List Products Lists catalog products.
- List Products By Phone Lists another business's catalog products by number.
- Search Products Searches the catalog using the request-body pagination form, which suits the long cursors this endpoint issues.
- Search Products By Phone Searches another business's catalog.
- Get Product Returns one product.
- Create Or Update Product Creates a product, or updates it in place when an existing retailer identifier is supplied.
- Delete Product Removes a product from the catalog.
- Update Catalog Settings Changes catalog behavior, including whether the cart is enabled.
Collections
7- List Collections Lists catalog collections.
- List Collection Products Lists the products in a collection.
- Create Collection Creates a collection.
- Rename Collection Renames a collection.
- Delete Collection Deletes a collection.
- Add Products To Collection Adds products to a collection.
- Remove Products From Collection Removes products from a collection.
Chat Tags and Notes
8- List Tags Lists the WhatsApp Business chat labels on the account.
- List Tag Colors Returns the color palette, since tag colors are indexes into it rather than free values.
- Create Tag Creates a label.
- Update Tag Updates a label.
- Delete Tag Deletes a label and its associations.
- Add Tag To Chat Applies a label to a chat, which is how an agent writes its state into the view the team already uses.
- Remove Tag From Chat Removes one label from a chat.
- Set Chat Notes Writes a note on a chat for whoever opens it next.
Mobile Registration
8- Check Registration Availability Checks whether a number can be registered as a primary WhatsApp device. These actions cover mobile instances, where the number is registered as the primary device rather than as a linked companion, which unlinks it from the physical handset.
- Request Registration Code Requests a registration code. This dispatches a real SMS or voice call to the number.
- Confirm Registration Code Confirms the registration code.
- Respond To Captcha Answers a captcha raised during registration.
- Confirm Security PIN Confirms the account's security PIN.
- Recover Security PIN Starts PIN recovery.
- Check Device Transfer Confirmed Checks whether a device transfer completed.
- Request Unbanning Submits an unbanning request for the number.
Account Security
7- Get Account Email Returns the email registered on the WhatsApp account.
- Set Account Email Sets the account email.
- Verify Account Email Verifies the account email.
- Remove Account Email Removes the account email.
- Get Security Code Status Reports whether two-step verification is enabled.
- Set Security Code Sets the two-step verification code.
- Remove Security Code Removes two-step verification. Worth treating as a security change rather than a settings change.
Frequently Asked Questions
What can FlowRunner do with Z-API?
FlowRunner agents can run Get Instance Status, Get Connected Device, and Get Instance Settings in Z-API, plus 207 more actions.
Does connecting Z-API to FlowRunner require OAuth?
No. Z-API connects to FlowRunner with an API key, no OAuth flow required.
Can Z-API trigger a FlowRunner workflow automatically?
Z-API doesn't currently expose triggers in FlowRunner. It connects as an action step inside workflows started by another trigger.
Start building with Z-API
$100 in credits. No card required. Connect in minutes.