BotPenguin
MessagingSearch and import BotPenguin inbox contacts, read bot chats, update captured leads, and send WhatsApp Cloud messages. Agents keep chatbot-captured leads flowing into the systems that act on them.
What This Integration Enables
BotPenguin is lead-shaped. Its centre of gravity is the inbox contact and the conversation that produced it, not the flow builder. The operations reflect that: search the contact database across bots and channels, read the chat threads split into lead and non-lead conversations, enrich a captured lead, and reach a person on WhatsApp Cloud. It is the connector you reach for when the problem is that a chatbot is capturing good leads and nothing downstream knows about them.
FlowRunner agents resolve saved segments into the IDs the search expects, then search the account-wide contact database with filters for free text, tags, lifecycle status, assigned agents, segments, per-platform bots, online state, and last-seen or creation date ranges. They read a single bot's chat threads. They bulk-import contacts into the inbox, mark contacts deleted by record ID, and apply partial updates to a captured lead. On WhatsApp they list every registered template with its approval status, type, category, and component tree, send a free-form message inside the 24-hour customer service window, and send an approved template outside it with variables supplied as Meta component objects. Two wiring details matter enough to design around: the dial code is written without a leading plus on import and with one on update, and on a lead update the notes and attributes lists replace what was there rather than appending to it.
Without FlowRunner
With FlowRunner
Use Case Scenarios
Captured Leads Into the CRM on a Schedule
Every hour the agent resolves the target segment with List Segments, runs Search Contacts filtered to that segment and to contacts created since the last run, and pages through the matches. Each one is upserted into HubSpot with the channel it came from, its lifecycle status, and the assigned agent. Because BotPenguin ignores a filter unless its key also appears in the request's applicable filter list, and this connector assembles that list automatically from whichever filters are supplied, the result set is the one the flow actually asked for rather than a silently unfiltered dump.
Enriching a Lead Without Erasing the Rep's Work
An account gets qualified in the CRM and the agent wants that reflected on the BotPenguin lead. It calls Update Lead with the conversation UUID, bot ID, and customer ID, sending only the status and owner. It deliberately does not send notes or attributes, because those lists replace rather than append, and the notes on that lead were written by a person. When the flow genuinely does need to add a note, it reads the current list first and sends the union.
Reopening a Conversation After the Window Closes
A prospect went quiet four days ago, which puts them outside WhatsApp's 24-hour customer service window where free-form messages are not delivered. The agent lists templates, filters to the approved ones in the utility category, and sends the appropriate template with its header and body components filled from the deal record, optionally routing the reply to a named agent by email. When the person answers, the window reopens and the conversation continues as free-form text.
Human-in-Loop Highlight
Import Contacts is where a person belongs, because importing is not a data operation here. It is a reachability operation. Writing a list into the BotPenguin inbox makes every one of those people addressable by the WhatsApp step that runs next, and the list usually came from somewhere that collected consent for a different channel. The undo is also asymmetric in a way that punishes a bad import: Delete Contacts accepts only the contact record IDs returned by a search, and BotPenguin explicitly does not support subscriber IDs there, so an ID of the wrong kind silently matches nothing and the contacts stay. FlowRunner makes the import a human-in-the-loop step rather than a scheduled job. The agent does the whole preparation: dedupes against Search Contacts, normalizes each dial code to the plus-free form this endpoint requires, drops entries missing a mandatory field before the API rejects the batch, and counts how many people are genuinely new. Then it asks the owner in Slack: "Import 318 contacts into the WhatsApp inbox. 94 already exist and will be skipped, 224 are new and become reachable by template send. Consent source recorded as the June webinar opt-in. Import, import the opted-in subset only, or cancel?" A person answers before anybody's number enters the sending surface.
Agent Capabilities
9 actionsContacts
5- List Segments Returns every contact segment defined in the account with its saved filter definition, current contact count, and active state. Segment IDs are what the contact search expects, so this turns a segment name into the ID a filter needs.
- Search Contacts Searches the account-wide contact database with filters for free text, tags, lifecycle status, assigned agents, segments, per-platform bots, online state, and last-seen or creation date ranges. BotPenguin ignores a filter unless its key also appears in the request's applicable filter array, and this action builds that array automatically from whichever filters are supplied.
- Import Contacts Bulk-imports contacts into the inbox. Every field of every entry is required: name, email, phone number, dial code, tags, and custom attributes. The dial code is supplied without a leading plus here, the opposite of the lead update, and a single contact is accepted as a one-element list.
- Delete Contacts Deletes one or more contacts by marking them with the deleted status, the only status this endpoint accepts. It takes the contact record IDs returned by the search; subscriber IDs are not supported and silently match nothing.
- Update Lead Updates a lead captured by a bot, identified by its conversation UUID together with the bot and customer IDs. Only the supplied fields change, but notes and attributes replace the existing lists rather than appending, and the dial code here must include the leading plus.
Conversations
1- List Bot Chats Returns the chat threads handled by a single bot, split into lead and non-lead conversations. This is the only operation that authenticates with the per-bot token rather than the inbox token, so that token must be configured on the connection.
- List WhatsApp Templates Returns every WhatsApp template registered on the account with its approval status, template type, category, and the component tree of header, body, footer, buttons, and carousel parts. An approved template is required to message outside the 24-hour customer service window.
- Send WhatsApp Message Sends a free-form message through the connected WhatsApp Cloud number, either plain text or an image from a publicly reachable URL with an optional label. Free-form messages are delivered only inside the 24-hour customer service window, and the recipient number carries the country code without a leading plus.
- Send WhatsApp Template Sends an approved template, which is the only way to start a conversation outside the 24-hour window. Variables are supplied as Meta component objects in the structure the WhatsApp Cloud API documents, and the conversation can optionally be routed to a specific agent by email.
Frequently Asked Questions
What can FlowRunner do with BotPenguin?
FlowRunner agents can run List Segments, Search Contacts, and List Bot Chats in BotPenguin, plus 6 more actions.
Does connecting BotPenguin to FlowRunner require OAuth?
No. BotPenguin connects to FlowRunner with an API key, no OAuth flow required.
Can BotPenguin trigger a FlowRunner workflow automatically?
BotPenguin doesn't currently expose triggers in FlowRunner. It connects as an action step inside workflows started by another trigger.
Start building with BotPenguin
$100 in credits. No card required. Connect in minutes.