API reference

Get a conversation

One conversation with its last text, how many texts in are unread, and whether the person is waiting on you.

Open in Claude Open in ChatGPT .md

GET/v1/conversations/{id}

One conversation with its last text, how many texts in are unread, and whether the person is waiting on you.

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

Path parameters

idstringrequired
The conversation’s id.
Starts with conv_.

Example

GET/v1/conversations/conv_1Hq2LxW9cVbN3mKpRtYs0aGet a conversation →

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

Response

200: The conversation.

idstringrequired
A conv_ id.
Starts with conv_.
object"conversation"required
kindstringrequired
person for one person, group for a group chat.
One of person, group.
titlestringrequired
The person’s name, the group’s name, or their numbers, as the inbox shows it.
handlestring or nullrequired
The person’s phone number or email address; null for a group.
contact_idstring or nullrequired
The person, for a one-to-one conversation.
Starts with ct_.
chat_idstring or nullrequired
The group chat, for a group.
Starts with chat_.
participantsarray of stringsrequired
Everyone in it besides you: one handle for a person, the members for a group.
servicestring or nullrequired
The service the last text used, when known.
One of imessage, sms.
last_messageobject or nullrequired
Show its 6 fieldsHide its fields
- idstringrequired
  A msg_ id.
  Starts with msg_.
- directionstringrequired
  One of in, out.
- statestringrequired
  The last text’s state.
- previewstring or nullrequired
  Its first 140 characters, or null when it had no words.
- filesintegerrequired
  How many files it carried.
- attimestamprequired
  When it was sent or arrived.
last_message_attimestamp or nullrequired
When the last text was sent or arrived.
unread_countintegerrequired
Texts in that you haven’t opened in the dashboard.
waitingbooleanrequired
True when the last text is theirs, so they are waiting on you.
archivedbooleanrequired
Marked done. A new text in brings it back.
stoppedbooleanrequired
The person is on your stop list.
created_attimestamprequired
When the conversation started.

Response200

{
  "id": "conv_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "conversation",
  "kind": "person",
  "title": "Maria Alvarez",
  "handle": "+15555550123",
  "contact_id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
  "chat_id": null,
  "participants": [
    "+15555550123"
  ],
  "service": "imessage",
  "last_message": {
    "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
    "direction": "in",
    "state": "received",
    "preview": "Can we move the showing to 4?",
    "files": 0,
    "at": "2026-11-13T19:44:12.000Z"
  },
  "last_message_at": "2026-11-13T19:44:12.000Z",
  "unread_count": 1,
  "waiting": true,
  "archived": false,
  "stopped": false,
  "created_at": "2026-11-02T15:20:00.000Z"
}

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.
`not_found`	404	There is no such thing on this account. Ids are prefixed by kind, so a message id starts with `msg_`.

Try it

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