List conversations

Your conversations as the dashboard’s inbox shows them, one per person or group chat, the most recent first. filter narrows to unread, waiting (the last text is theirs) or archived, and q searches names, numbers, group names and the words of texts.

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

Query parameters

• qstring

  Search names, numbers, group names and the words of texts.

  Up to 100 characters.

• filterstring

  all (not archived), unread, waiting (the last text is theirs) or archived.

  One of all, unread, waiting, archived.Default "all".

• 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/conversations" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Response

200: A page of conversations.

• object"list"required
• dataarray of Conversationrequired
  Show its 16 fieldsHide its fields

  • 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.

• 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": "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"
    }
  ],
  "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