List chats

The chats the Mac has seen, newest first, with their participants. A group chat’s id is what chat_id takes on a send.

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

Query parameters

• is_groupstring

  true for only group chats, false for only one-to-one chats.

  One of true, false.

• personstring

  Only chats this person is in.

  3 to 320 characters.

• 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

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

Response

200: A page of chats.

• object"list"required
• dataarray of Chatrequired
  Show its 8 fieldsHide its fields

  • idstringrequired

    A chat_ id.

    Starts with chat_.

  • object"chat"required
  • namestring or nullrequired

    The group’s name, when it has one.

  • is_groupbooleanrequired
  • participantsarray of stringsrequired

    The other people in the chat.

  • servicestring or nullrequired

    The chat’s service.

    One of imessage, sms.

  • last_message_attimestamp or nullrequired

    The newest text in the chat.

  • created_attimestamprequired

    When BlueBot first saw the chat.

• has_morebooleanrequired

  Whether another page follows.

• next_cursorstring or nullrequired

  Send as cursor for the next page; null on the last.

{
  "object": "list",
  "data": [
    {
      "id": "chat_1Hq2LxW9cVbN3mKpRtYs0a",
      "object": "chat",
      "name": "Oak St closing",
      "is_group": true,
      "participants": [
        "+15555550123",
        "+15555550187"
      ],
      "service": "imessage",
      "last_message_at": "2026-11-13T19:41:00.000Z",
      "created_at": "2026-11-02T14:00:00.000Z"
    }
  ],
  "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.

Try it