Receive texts

Your Mac also reads Messages and copies texts to BlueBot: the replies people send you, the texts you type by hand on your Mac or iPhone, tapbacks, edits and unsends. Each text that comes in becomes a message with "direction": "in" and "state": "received", and BlueBot tells your webhooks with message.received.

Nothing changes on your phone. Replies still arrive in Messages on your iPhone and Mac the way they always have, and you can answer them there. BlueBot sees your answer too.

Which chats are copied

Your Mac copies some chats and leaves the rest alone. Which ones is the Which chats to copy setting: People BlueBot has texted or Everything in Settings → Sending rules, the same choice in the Mac app’s own settings, and inbound_mode in the API:

“Texted through BlueBot” means any text BlueBot sent for you: from the API, the dashboard, Zapier, a sequence or anywhere else. A chat counts from the first text BlueBot sends into it, so the first reply to that text is copied.

Under replies, somebody who texts you first is not copied. If people find your number on a sign, an ad or your website and text you before you’ve ever texted them, set Which chats to copy to Everything, or BlueBot never hears from them. Under everything your personal chats are copied as well. BlueBot deletes the words of every text after 30 days, but think about whose chats are on that Mac before you choose it.

In either mode, the Mac never copies chats with short codes (the 5- and 6-digit numbers banks and airlines text from) or business chats, since those aren’t a phone number or an email address.

Change it under Settings → Sending rules in the dashboard, in BlueBot’s window on the Mac, or with the API:

curl -X PATCH "https://usebluebot.com/api/v1/settings" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_mode": "everything"
  }'

The Mac picks up the change at its next check-in, within 10 seconds. When you first connect a Mac, it copies the chats it should from the 7 days before, so a fresh account starts with recent history.

What a text in looks like

{
  "id": "msg_3Lp3VsC7hGqE5tZyKbWn2d",
  "object": "message",
  "direction": "in",
  "state": "received",
  "to": "+15555550100",
  "from": "+15555550123",
  "chat_id": null,
  "contact_id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
  "conversation_id": "conv_1Hq2LxW9cVbN3mKpRtYs0a",
  "text": "Perfect, see you there at 3",
  "files": [],
  "service": "imessage",
  "source": "mac",
  "metadata": {},
  "reply_to_id": null,
  "reactions": [],
  "edited_at": null,
  "unsent_at": null,
  "received_at": "2026-11-13T19:44:10.000Z"
}

Hear about each one

Point a webhook at your server for message.received, and BlueBot posts each text that comes in, signed so you can check it came from BlueBot:

curl -X POST "https://usebluebot.com/api/v1/webhooks" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-replies-webhook" \
  -d '{
    "url": "https://example.com/webhooks/bluebot",
    "events": [
      "message.received"
    ],
    "description": "Replies into the CRM"
  }'

Each delivery is the event, with the message in data:

{
  "id": "evt_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "event",
  "type": "message.received",
  "api_version": "2026-11-13",
  "timestamp": "2026-11-13T19:44:12.000Z",
  "data": {
    "id": "msg_3Lp3VsC7hGqE5tZyKbWn2d",
    "object": "message",
    "direction": "in",
    "state": "received",
    "from": "+15555550123",
    "text": "Perfect, see you there at 3"
  }
}

A handler only has to check the signature, look at type, and answer 200 quickly:

import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

export async function POST(request: Request) {
    const payload = await request.text();
    // Throws WebhookVerificationError when the signature doesn't match.
    const event = client.webhooks.verify(payload, request.headers, process.env.BLUEBOT_WEBHOOK_SECRET!);

    if (event.type === 'message.received') {
        const message = event.data;
        await saveReply({ from: message.from, text: message.text, contactId: message.contactId });
    }
    return new Response(null, { status: 200 });
}

import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])


def handle(payload: bytes, headers: dict) -> int:
    # Raises bluebot.WebhookVerificationError when the signature doesn't match.
    event = client.webhooks.verify(payload, headers, os.environ["BLUEBOT_WEBHOOK_SECRET"])
    if event.type == "message.received":
        message = event.data
        save_reply(from_=message.from_, text=message.text, contact_id=message.contact_id)
    return 200

Webhooks covers setting one up, Verify signatures the check in every language, and Test webhooks locally how to run a handler on your laptop with bluebot listen.

When message.received fires

BlueBot waits until the Mac has uploaded the text’s pictures and files, which usually takes seconds, so the event carries files you can download. If they haven’t come after 2 minutes, the event goes anyway with those files’ status set to waiting; read the message again later for them.

A text arrives on your Mac when Messages gets it, and the Mac copies new texts at each check-in, every 10 seconds. A reply usually reaches your webhook within 10 to 20 seconds of reaching your phone. While the Mac is asleep or off, nothing is copied. When it comes back, it copies everything it missed, in order, and each text fires its event then. received_at is when the text really arrived, so use that rather than the time your webhook was called.

List incoming texts

To read texts in rather than be told, list them. Lists are newest first:

curl "https://usebluebot.com/api/v1/messages?direction=in&since=2026-11-13T00%3A00%3A00Z" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Narrow it with person (a number or an address), contact_id, chat_id or until, and page through with cursor. Pagination

To catch up on what a webhook missed, read the event feed, which keeps 30 days of events in the shape a webhook gets them:

curl "https://usebluebot.com/api/v1/events?type=message.received&since=2026-11-13T00%3A00%3A00Z" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Texts you type by hand

The Mac copies both directions of every chat it copies, so a text you type on your Mac or iPhone shows up too, as "direction": "out" with "source": "mac". It fires message.sent like a text BlueBot sent. Your code can tell the two apart by source, and the dashboard shows the whole conversation the way your phone does.

Texts you type by hand don’t count against your daily limits and aren’t paced: BlueBot only records them.

Tapbacks

When somebody loves, likes or laughs at a text (a tapback), BlueBot records it on that text’s reactions and fires reaction.added. Taking one back fires reaction.removed.

{
  "id": "rxn_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "reaction",
  "kind": "love",
  "emoji": null,
  "from": "+15555550123",
  "direction": "in",
  "added_at": "2026-11-13T19:45:00.000Z",
  "message_id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "conversation_id": "conv_1Hq2LxW9cVbN3mKpRtYs0a",
  "chat_id": null,
  "contact_id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
  "removed_at": null
}

kind is love, like, dislike, laugh, emphasize, question, or emoji with the emoji in emoji. direction is in for the other person’s and out for one you added on your own phone. BlueBot can read tapbacks but can’t send them. Capabilities

A tapback is not a text, so it doesn’t fire message.received and isn’t in GET /v1/messages.

Edits and unsends

On macOS 13 or later, when somebody edits a text, BlueBot updates its text, sets edited_at and fires message.edited. When somebody unsends one, BlueBot clears its words, sets unsent_at and fires message.unsent. Both work for your own texts too. If your app showed the old words somewhere, update or remove them when these events come.

Stop words

When somebody texts you one-to-one with only a stop word, such as STOP or Unsubscribe, BlueBot still copies the text and fires message.received. While stop words are on (the default), it also puts them on your stop list, cancels any texts still waiting for them and fires contact.stopped. A reply of START, UNSTOP or YES takes them off again. Stop words in a group chat do nothing, since BlueBot can’t leave one person out of a group. Stop words

What BlueBot keeps

BlueBot keeps the words of a text, and the files on it, for 30 days. After that the message stays with its facts (who, when, which service, the tapbacks) and "text_deleted": true. If you need the words for longer, copy them into your own system when message.received comes. Data retention