API reference

List texts

Texts in and out, newest first, including ones typed by hand on your Mac or iPhone (source: "mac").

GET/v1/messages

Texts in and out, newest first, including ones typed by hand on your Mac or iPhone (source: "mac"). Filter by person, chat, state, direction, source or time.

Needs a key with the messages:read scope. Keys and scopes

Query parameters

directionstring
Only texts out, or only texts in.
One of out, in.
statestring
Only texts in this state.
One of scheduled, queued, sending, sent, delivered, read, failed, unconfirmed, expired, canceled, received.
personstring
Only texts with this person (a phone number or an email address).
3 to 320 characters.
contact_idstring
Only texts with this contact.
Starts with ct_.
chat_idstring
Only texts in this group chat.
Starts with chat_.
sourcestring
Only texts from this source.
One of api, zapier, make, n8n, pipedream, cli, mcp, hook, broadcast, sequence, inbox, autopilot, keyword, away, widget, assistant, test, mac.
sincetimestamp
Only texts created at or after this time.
untiltimestamp
Only texts created before this time.
limitinteger
How many to return, 1 to 100. Default 25.
1 to 100.Default 25.
cursorstring
The next_cursor of the page before. Leave it out for the first page.
Up to 200 characters.

Example

GET/v1/messagesList texts →

curl "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Response

200: A page of texts.

object"list"required
dataarray of Messagerequired
Show its 41 fieldsHide its fields
- idstringrequired
  A msg_ id.
  Starts with msg_.
- object"message"required
- directionstringrequired
  out for a text from your number, in for one to it.
  One of out, in.
- statestringrequired
  Out: scheduled, queued, sending, sent, delivered, read, failed, unconfirmed, expired, canceled. In: received.
  One of scheduled, queued, sending, sent, delivered, read, failed, unconfirmed, expired, canceled, received.
- tostring or nullrequired
  Who it went to. For a text in, your own number when the Mac knows it. Null in a group chat.
- fromstring or nullrequired
  Who sent it. For a text out, your own number when the Mac knows it.
- chat_idstring or nullrequired
  The group chat it is in; null for a one-to-one text.
  Starts with chat_.
- contact_idstring or nullrequired
  The person, or for a group text in, the member who sent it.
  Starts with ct_.
- conversation_idstringrequired
  A conv_ id.
  Starts with conv_.
- textstring or nullrequired
  The words. Null for a files-only text, an unsent one, and after 30 days, when BlueBot deletes the words and keeps the facts.
- text_deletedbooleanrequired
  True once the words were deleted after 30 days.
- filesarray of Filerequired
  Pictures and files on the text, in order.
  Show its 12 fieldsHide its fields
  - idstringrequired
    A file_ id.
    Starts with file_.
  - object"file"required
  - namestring or nullrequired
    The file name, as it was uploaded or as Messages named it.
  - content_typestringrequired
    The media type.
  - sizeintegerrequired
    Bytes.
  - kindstringrequired
    What the file is, for showing it: an image, a video, audio, a voice memo, a PDF, a contact card or another file.
    One of image, video, audio, voice_memo, pdf, contact_card, file.
  - statusstringrequired
    ready when BlueBot has the bytes; waiting while the Mac uploads them (usually seconds); too_large for an attachment over 25 MB, which the Mac never uploads; deleted once 30 days have passed.
    One of ready, waiting, too_large, deleted.
  - urlstring or nullrequired
    Reads the file for an hour. Null unless status is ready.
  - url_expires_attimestamp or nullrequired
    When url stops working.
  - transcriptstring or nullrequired
    For a voice memo, the words the Mac transcribed on the device, when the owner turned transcription on.
  - transcript_languagestring or nullrequired
    The transcript’s language, such as en-US.
  - created_attimestamprequired
    When BlueBot first knew of the file.
- service_requestedstringrequired
  What the caller asked for. auto uses the service of the newest chat with the person, else iMessage.
  One of auto, imessage, sms.
- servicestring or nullrequired
  What it went or came through. Null until it is sent.
  One of imessage, sms.
- sms_retrybooleanrequired
  True when an iMessage that never went was sent again once as a regular text.
- sourcestringrequired
  What sent it. Texts read from Messages, including ones you typed by hand, are mac.
  One of api, zapier, make, n8n, pipedream, cli, mcp, hook, broadcast, sequence, inbox, autopilot, keyword, away, widget, assistant, test, mac.
- source_refstring or nullrequired
  The broadcast, sequence, hook, rule or template behind it, as an id. A text sent with template_id carries the template’s tpl_ id here.
- metadatamap of stringrequired
  Your own data, echoed on the message and on every webhook about it: up to 20 keys of up to 40 characters, each a string of up to 500.
- holdHold or nullrequired
  A text that is accepted but can’t go yet carries a hold. Null when nothing holds it.
  Show its 3 fieldsHide its fields
  - reasonstringrequired
    Why the text is waiting, checked in this order: account_held (BlueBot paused the account), platform_stopped (BlueBot stopped all sending), plan_lapsed, paused (you paused sending), device_offline (no check-in from the Mac for 2 minutes), quiet_hours, daily_new_people_limit, platform_daily_limit (1,000 a day) and pacing (its turn in the spacing between texts).
    One of account_held, platform_stopped, plan_lapsed, paused, device_offline, quiet_hours, daily_new_people_limit, platform_daily_limit, pacing.
  - untiltimestamp or nullrequired
    When it should stop waiting, when that is known: the end of quiet hours, the next local midnight, or the estimated slot.
  - descriptionstringrequired
    The hold in words.
- send_attimestamp or nullrequired
  For a scheduled text, when it goes.
- expires_attimestamp or nullrequired
  A text still queued at this time expires.
- failureobject or nullrequired
  Why a failed text didn’t go. Also set on a sent text when the words went and a file didn’t.
  Show its 2 fieldsHide its fields
  - reasonstringrequired
    One of messages_refused, not_on_imessage, file_unavailable.
  - detailstring or nullrequired
    What the Mac saw, in words.
- cancel_reasonstring or nullrequired
  Why it was canceled: requested, opted_out (the person texted a stop word), sequence_stopped, broadcast_canceled or staff.
  One of requested, opted_out, sequence_stopped, broadcast_canceled, staff.
- resolutionstring or nullrequired
  How an unconfirmed text was settled: marked sent, or sent again as a new text.
  One of marked_sent, resent.
- resolved_attimestamp or nullrequired
  When it was settled.
- resent_message_idstring or nullrequired
  The new text, when this one was sent again.
  Starts with msg_.
- reply_to_idstring or nullrequired
  The text this one answers inline, when Messages recorded one.
  Starts with msg_.
- reactionsarray of Reactionrequired
  Tapbacks on this text that are still there.
  Show its 6 fieldsHide its fields
  - idstringrequired
    A rxn_ id.
    Starts with rxn_.
  - kindstringrequired
    The tapback: love, like, dislike, laugh, emphasize, question, or a custom emoji.
    One of love, like, dislike, laugh, emphasize, question, emoji.
  - emojistring or nullrequired
    The emoji, for kind: "emoji".
  - fromstring or nullrequired
    Who reacted; null when it was you, on your Mac or iPhone.
  - directionstringrequired
    in from the other person, out from you.
    One of in, out.
  - added_attimestamprequired
    When the tapback was added.
- edited_attimestamp or nullrequired
  When it was last edited in Messages.
- unsent_attimestamp or nullrequired
  When it was unsent in Messages.
- created_attimestamprequired
  When BlueBot accepted or first saw it.
- queued_attimestamp or nullrequired
  When it became due.
- sending_attimestamp or nullrequired
  When the Mac took it.
- sent_attimestamp or nullrequired
  When Messages showed it sent.
- delivered_attimestamp or nullrequired
  When iMessage showed it delivered. Regular texts are never delivered.
- read_attimestamp or nullrequired
  When it was read, where the person shares read receipts.
- failed_attimestamp or nullrequired
  When it failed.
- unconfirmed_attimestamp or nullrequired
  When the Mac’s lease lapsed without saying whether it went.
- expired_attimestamp or nullrequired
  When it expired.
- canceled_attimestamp or nullrequired
  When it was canceled.
- received_attimestamp or nullrequired
  For a text in, when it arrived.
has_morebooleanrequired
Whether another page follows.
next_cursorstring or nullrequired
Send as cursor for the next page; null on the last.

Response200

{
  "object": "list",
  "data": [
    {
      "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
      "object": "message",
      "direction": "out",
      "state": "sent",
      "to": "+15555550123",
      "from": "+15555550100",
      "chat_id": null,
      "contact_id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
      "conversation_id": "conv_1Hq2LxW9cVbN3mKpRtYs0a",
      "text": "Hi Maria, the showing at 412 Oak St is confirmed for 3 PM.",
      "text_deleted": false,
      "files": [],
      "service_requested": "auto",
      "service": "imessage",
      "sms_retry": false,
      "source": "api",
      "source_ref": null,
      "metadata": {
        "crm_id": "48213"
      },
      "hold": null,
      "send_at": null,
      "expires_at": "2026-11-14T19:41:00.000Z",
      "failure": null,
      "cancel_reason": null,
      "resolution": null,
      "resolved_at": null,
      "resent_message_id": null,
      "reply_to_id": null,
      "reactions": [],
      "edited_at": null,
      "unsent_at": null,
      "created_at": "2026-11-13T19:41:00.000Z",
      "queued_at": "2026-11-13T19:41:00.000Z",
      "sending_at": "2026-11-13T19:41:02.000Z",
      "sent_at": "2026-11-13T19:41:05.000Z",
      "delivered_at": null,
      "read_at": null,
      "failed_at": null,
      "unconfirmed_at": null,
      "expired_at": null,
      "canceled_at": null,
      "received_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

Code	Status	What it means
`unauthorized`	401	The request carried no key, or a key BlueBot doesn’t know: mistyped, revoked, or a test key sent to the live API.
`insufficient_scope`	403	The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.
`rate_limited`	429	Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait.
`internal`	500	Something went wrong on BlueBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.
`invalid_request`	400	Something in the request doesn’t fit: a missing or malformed field, a bad id, or a combination the endpoint refuses. `details` names each field.

Try it

Call this operation from the page with your own key. The key stays in this tab and is forgotten when you leave.