Skip to content
Docs menu

Bots that reach out

Let a bot write to your people while you sleep, as drafts you check in the morning, sent for you through Venom Comms, or sent from your own WhatsApp Web or LinkedIn on the bot's own computer, inside limits you set. It can also keep your People records filled in.

View .md

A bot can work through your contacts while you sleep: decide who to get back to, write each message in your voice from your notes and your history with that person, and either leave it for you to check in the morning or send it for you. It can also fill in what is missing in your People records.

How a bot writes to people is set on its page under Outreach. The limits there hold whatever its instructions say, so a mistake in an instruction can never reach your whole address book.

Three ways to deliver

Delivery What happens What it needs
Leave drafts for me (the default) Nothing is sent. Each message waits in People, Today (/people/today), where you approve, edit or skip it as you do your overnight queue, and in a dated note in your vault, Bots/<bot>/Outreach/<date>, with who, why, the channel and the message. Nothing. Drafts for someone shared with you (not your own contact) go only to the note.
Send from its own computer The bot opens your own logged-in WhatsApp Web or LinkedIn in the browser of its computer and sends from there, a few messages a run. See From the bot's own computer. A computer for the bot (Its own computer under Settings on its page), and you logged in to WhatsApp Web or LinkedIn on it.
Send through Venom Comms The bot sends as you, from your organisation's mailbox (email) or numbers (WhatsApp Business, SMS), or from your own Telegram. Comms' rules still apply: the sender, opt-outs, the mailbox's send slots and warm-up, WhatsApp's 24-hour window and templates, and quiet hours in the recipient's time zone. An admin sets up a Comms mailbox or provider (Settings, Comms). If your role doesn't manage Comms (you aren't an owner or admin), each message also waits in Comms until an owner or admin approves it, and the bot tells you so.

A routine can pick its own delivery mode, which overrides the bot's, under Routines (outreach_mode in the API). For example, a bot can draft every night and send only from a routine you start by hand.

Comms doesn't carry LinkedIn, so through Comms a LinkedIn message is a draft. The bot's own computer sends WhatsApp and LinkedIn only.

The limits

Limit Default What it does
Channels Email The channels it may use: email, WhatsApp, SMS, Telegram, LinkedIn.
Daily cap per channel Email 20, WhatsApp 15, SMS 10, Telegram 15, LinkedIn 10 Messages and drafts a day, counted from midnight in your time zone. At most 200 email, 100 WhatsApp, 100 SMS, 100 Telegram and 40 LinkedIn.
Minutes between sends 3 Each pause varies by up to 40% either way, so a batch never goes out on a fixed beat.
Quiet hours 21:00 to 08:00 In your time zone. Messages written at night wait until morning, then go out paced.
Re-contact after 14 days It won't write to the same person again within this time unless they answered. A message you sent yourself counts too.
Who it may contact Only my own people Narrow it to a saved Reach view, a circle or a tag. Only your own contacts can be reached, since their addresses are private to you.

The bot never:

  • writes to someone tagged do-not-contact (or dnc, no-contact, no-outreach), someone you marked Not yet in People, or someone who opted out in Comms;
  • writes again to someone who replied to it. The conversation is yours from then on. They show under Replied to it on the bot's page, and Let it write again lifts the hold;
  • uses a channel you haven't ticked, or goes past a cap;
  • sends on its own from a run an email or a webhook started, unless that routine trusts what arrives (see below);
  • sends on its own to an address an agent changed in the last day (see Addresses an agent changed);
  • pays for anything.

From the bot's own computer

A bot with a computer of its own can send from your own WhatsApp Web or LinkedIn, logged in in that computer's browser. Nothing goes through the cloud's numbers: the messages come from your account, as if you typed them.

Setting it up

  1. On the bot's page, turn on Its own computer under Settings. The bot gets a browser of its own on your daemon.
  2. Open that computer (Computers) and log in to WhatsApp Web (scan the QR code with your phone) and to LinkedIn. You can also keep a saved login for LinkedIn; WhatsApp Web has no password to save.
  3. Under Outreach, choose Send from its own computer and tick WhatsApp and LinkedIn. The section shows, per channel, when the computer last sent and when it last needed you. The cloud can't see whether the browser is still logged in, so if you skip step 2 the bot asks you to log in the first time it finds a login page (a takeover under Needs you).

How one message goes

  1. The bot reserves a message to one person (people_outreach_reserve). Every rule below is checked here, the same as for Comms, and a cap slot is held for 30 minutes.
  2. It asks to send (people_outreach_send). The cloud answers wait (the pace between messages has not passed: it says how many seconds), a refusal (quiet hours, a pace too long to wait for, or something changed since the reservation, such as a reply or a new do-not-contact tag), or go. Go carries the page to open: the WhatsApp chat for the person's number, or their LinkedIn profile, both taken from the person's record in People, never chosen by the bot. The number must carry its country code (as +65 9123 4567): a number saved the local way, starting with 0, is refused rather than guessed, since it would open a chat with someone in another country. The LinkedIn address must be a personal profile on linkedin.com (linkedin.com/in/…); a company page, a messaging link or another site is refused.
  3. It opens that page, checks that the name on screen is the person's, types the message and sends it once. If the chat shows only a number and no name, or a different name, it types nothing and the message comes to you.
  4. It reports what happened (people_outreach_mark_sent): sent (the message is logged on the person in People and in the dated note), failed with the reason, or needs you (the message becomes a draft in your overnight queue, with why). A message can be marked only once.

A run sends at most 5 messages; the pace and quiet hours apply between them as for Comms, counted from the bot's last send whichever run made it. A reservation never used lapses after 30 minutes and frees its cap slot. A message the bot was told to send but never reported on lapses after 30 minutes too; because it may have gone, it still counts for the daily cap, the run's 5 and the re-contact window.

What it is told, and will never do. Each run that sends from the computer gets short, fixed instructions for the two sites (lib/bots/computer-sites.ts): open only the address it was given; stop if the name doesn't match; never message a group, a channel or a broadcast list; never add a connection, follow, endorse, like, react or accept an invitation unless your own instruction for that run says so (never because something it read asks); never type a password or a code; stop and mark the message for you on a CAPTCHA, a security check, a warning or limit banner, or any page it doesn't recognise; never send a message twice, and when it can't tell whether one went, leave it to you; never read or reply to other conversations.

What the bot's computer can't do as you. The bot's run on its computer calls Venom with a key made for that run alone. Venom knows those calls as the run's, so the run can't answer its own approvals on the computer, approve its own card, change its autonomy, caps or channels, set up routines, or let itself write again to someone who replied: those stay yours, as for a bot's chat.

LinkedIn's risk. LinkedIn restricts automated activity in its terms and can limit or restrict an account that uses it. The bot's LinkedIn cap starts at 10 a day (at most 40) and sends are spaced out, but the risk is to your own account. Keep the cap low, and turn LinkedIn off if that risk isn't worth it to you.

Not tried against the live sites. These steps were built and tested against a simulated computer, not against the real WhatsApp Web and LinkedIn pages, which change often. Watch the bot's first runs on its computer (Computers, watch and control) before you leave it alone.

With Ask me first, a run on the computer doesn't open the sites at all: it writes the messages into the approval card. When you approve them, the cloud starts a short run on the bot's computer that sends exactly the approved messages and nothing else; its plain browser steps on WhatsApp Web and LinkedIn (opening the page, clicking, typing, sending) count as approved by you. Anything else in that run, such as another site, a file or a tool, still asks you.

If you answer one of the bot's asks on its computer with Allow for this site, the computer remembers it, and later runs act on that site without asking, whatever the bot's autonomy. For WhatsApp Web and LinkedIn, answer with Allow once if you want an Ask me first bot's runs to keep asking you there.

Addresses an agent changed

A bot can change a person in People (with people_person_update, or an enrichment it applies), so it could otherwise put a new number or email on someone and message it in the same run. The cloud records who last changed each address, a person's do-not-contact tag and their Not yet: you in the app, or an agent (any chat or bot run, and any agent's run on a computer). A number you removed that an agent puts back counts as the agent's. When the address a message would go to, or the person's do-not-contact tag or Not yet, was changed by an agent in the last 24 hours:

  • Act without asking: the message is refused, and it is listed in the brief as held, so you can check the person in People. Once you save the address yourself, the bot may use it.
  • Ask me first: the message goes to the approval card, marked Address changed by an agent. Approving it is your confirmation of what had changed by then; an agent changing it again after you approved holds the message.

This applies to every delivery that sends (Comms and the bot's computer), and is checked again just before a message goes.

Ask first or act on its own

Sending is something hard to undo, so the bot's setting under When it works on its own decides it:

  • Ask me first (the default): a run doesn't stop at each message. It writes all of them, and they wait for you together under Needs you on the bot's page as one card per run, listing who, the channel, why and the message. Approve all, tick some and Approve the ticked, or Decline all. You get one push notification for the card. Approved messages go out paced and outside your quiet hours. A card you don't answer lapses after three days. The card shows each message in full with the address it goes to (masked); the buttons act on exactly the items you see.
  • Checked again when it goes. A message that waits (approved, or scheduled by pacing or quiet hours) is checked again just before it goes to Comms or the bot's computer is told to send it. It doesn't go if, in the meantime, you turned the bot off, set it back to drafts, took the channel away or lowered today's cap, the person left its scope, was archived or tagged do-not-contact or "not yet", replied to it, you wrote to them yourself, or their address changed. It shows as failed in the ledger, with the reason.
  • One at a time per person. A bot never has two unsent messages to the same person at once, on any channel.
  • Act without asking: messages go out by themselves within the limits above. A run started by an email or a webhook still asks first unless its routine trusts what arrives, as with any destructive tool.

A chat with the bot always asks: each send waits for your confirm in the chat.

Enriching your people

A bot with the People server can enrich, classify and tidy your contacts on its own, as you, within People's AI and enrichment caps. Applying an enrichment follows the same rule as sending: with Ask me first the changes it wants to apply wait in the run's card (with the suggestion lines), and with Act without asking it applies what it is confident of and leaves the rest pending for you. people_enrichment_next gives it the next people to enrich (new this week and never enriched first, then never enriched, then those last enriched over six months ago), so a nightly pass doesn't start over each time.

Ready-made bots

New bot offers four bots that work on their own. Each shows what it will schedule and what it may do before you choose Make bot, and makes the bot and its routines in one step. All of them start with Ask me first and drafts only. You turn either up when you have seen what they do.

Bot When it runs What it does
Contacts keeper Every day at 05:30 Picks who to get back to from your nightly Reach views and due follow-ups, and writes each message in your voice.
People enricher Every day at 02:30 Enriches the next batch, applies what it is sure of, and writes a note of what changed and what it was unsure about.
New contact filer When you add a person Enriches and classifies them, and drafts a first hello.
Deal follow-up When one of your deals moves stage Writes the follow-up the deal's main contact should get next.

While you were away

The bots roster's brief adds a line per bot for what it did to people, for example "8 sent · 3 drafted · 2 replied · 5 enriched · 2 unsure". "Unsure" counts the enrichments it left pending for you. Messages sent from the bot's own computer count with the rest. "Held" counts messages it didn't send on its own because an agent changed the address recently.

Tools and API

The bot writes to people only through five People tools, never through Comms' tools directly:

Tool What it does
people_outreach_reserve Checks every rule for one message to one person on one channel and holds a cap slot for 30 minutes. Answers allowed (with a reservation id and the delivery mode) or refused with the reason.
people_outreach_send Sends a reserved message through Comms, holds it for your approval, or makes it a draft, as the bot's settings say. Email needs a subject; WhatsApp outside the 24-hour window needs an approved template. From the bot's computer it answers go, wait or a refusal instead (the computer sends).
people_outreach_mark_sent From the bot's computer: says how a send went (sent, failed or needs_owner, with a note), once. REST: POST /v1/people/outreach/reservations/{reservation}/outcome.
people_outreach_draft Leaves a message as a draft (with a reservation, or a person, channel and reason).
people_outreach_list What was reserved, drafted and sent.

An intro ask sent with people_introask_send goes through the same reservation and send, so a bot's channels, caps, re-contact window, scope, quiet hours and asking first apply to it too. A bot in note mode does not send intros, and one that sends from its computer does not either.

You can use the same tools yourself, in your own chat or from an MCP client. Then only the fixed rules apply (your own contacts, an address, no opt-out, no do-not-contact), and a send in a chat waits for your confirm.

Only you change a bot's outreach or answer its card: agents_bot_outreach_get, agents_bot_outreach_update, agents_bot_outreach_decide and agents_bot_outreach_release, or GET/PATCH /api/workspace/agents/bots/{id}/outreach, POST …/outreach/decide ({approve, decline, run_id}: lists of ids, or "all" together with run_id for one run's card; "all" without run_id is refused) and POST …/outreach/release ({person_id}). A quick chat acting for you, a bot's own run included, is refused. agents_bot_create with template (contacts, enricher, filer, deals) makes a ready-made bot with its routines. Contacts keeper and Deal follow-up work unchanged in computer mode: the run's instructions gain the steps for the two sites. outreach_mode on a routine also takes computer.

Every reservation, draft and send is kept in a ledger the bot's page lists under Recent drafts and sends, with its state (reserved, waiting for you, scheduled, sending, sent, waiting in Comms, draft, declined, failed, lapsed) and a link to the person. A message that goes out is logged on the person in People as an outbound interaction.