Skip to content
Rigel docs
Open Rigel

Messages in a conversation or thread

chat.message.list

GET/api/v1/households/{household_id}/queries/chat.message.list

  • Query
  • Rigel runs it

A page of a conversation's own messages (not those inside threads; each message says how many replies its thread has), or of one thread's messages, oldest first within the page. Pages go back in time: send next_cursor as before for the page before. Errors: conversation_not_found, message_not_found.

Parameters#

Messages in a conversation or thread: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

conversation_idquerystringoptional

List this conversation's messages.

thread_root_message_idquerystringoptional

Or the thread under this message.

beforequerystringoptional

The next_cursor of the previous answer, for older messages; left out, the newest.

pattern ^(\d+)\.(msg_[0-9A-HJKMNP-TV-Z]{26})$
limitqueryintegeroptional

Up to how many messages, 1–200, 50 by default.

1 to 200Default 50

Response#

200 The answer.

Messages in a conversation or thread: response fields
FieldDescription
itemsarray of objectsrequired
items[].idstringrequired

A message ID, such as msg_01JC0000000000000000000000.

items[].conversation_idstringrequired

A conversation ID, such as cnv_01JC0000000000000000000000.

items[].thread_root_message_idstring or nullrequired

The message whose thread this is in, or null.

items[].authorobjectrequired
items[].author.kindone of: person, rigelrequired

person (a member of the family) or rigel.

items[].author.person_idstring or nullrequired

The person who wrote it, or null for Rigel or someone since removed.

items[].author.namestringrequired

Who wrote it, as shown: the person's name, "Rigel", or "Someone" for a removed person.

items[].formatone of: markdown, plainrequired

How to read body: markdown (a CommonMark subset: emphasis, links, lists, quotes and code; raw HTML is shown as text) or plain (shown exactly as written).

items[].bodystringrequired

The text as written; empty for a deleted message.

items[].stateone of: sent, deletedrequired

sent, or deleted (it keeps its place, with nothing in it).

items[].sent_atstring (date-time)requiredNo description.
items[].edited_atstring (date-time) or nullrequired

When it was last edited, or null.

items[].reply_toobject or nullrequired

The message this one quotes, or null.

items[].reply_to.message_idstringrequired

A message ID, such as msg_01JC0000000000000000000000.

items[].reply_to.author_namestringrequiredNo description.
items[].reply_to.excerptstringrequired

The quoted message as plain text, shortened, or "Message deleted".

items[].attachmentsarray of objectsrequired
items[].attachments[].file_idstringrequired

A file ID, such as fil_01JC0000000000000000000000.

items[].attachments[].namestringrequired

The file's name.

items[].attachments[].kindone of: image, video, audio, pdf, otherrequired

What kind of file it is.

items[].stickerobject or nullrequired

The sticker this message is, or null.

items[].sticker.alt_textstringrequired

What the sticker shows.

items[].sticker.file_idstringrequired

A file ID, such as fil_01JC0000000000000000000000.

items[].reactionsarray of objectsrequired

Reactions, grouped by emoji, in the order first used.

items[].reactions[].emojistringrequired

The emoji: a Unicode emoji, or ":name:" for a custom one.

items[].reactions[].countintegerrequiredNo description.
items[].reactions[].byarray of stringsrequired

Who reacted, by name ("Rigel" for Rigel).

items[].mentionsarray of objectsrequired

Who it mentions.

items[].mentions[].person_idstring or nullrequired

Null for Rigel.

items[].mentions[].namestringrequiredNo description.
items[].threadobject or nullrequired

The thread under this message, or null when it has none (and for messages inside a thread).

items[].thread.reply_countintegerrequiredNo description.
items[].thread.last_reply_atstring (date-time)requiredNo description.
items[].moved_toobject or nullrequired

Set only on the line left where messages were moved out, shown as "Moved 3 messages to Summer trip".

items[].moved_to.conversation_idstring or nullrequired

The topic they went to, or null if it's gone.

items[].moved_to.titlestring or nullrequired

Its title now, or null if it's gone.

items[].moved_to.message_countintegerrequired

How many messages moved, not counting their threads.

items[].linksarray of objectsrequired

Records of any app the message links to, from its text, with each one's web route.

items[].links[].record_idstringrequiredNo description.
items[].links[].addressstring or nullrequiredNo description.
items[].addressstringrequired

The web route that opens this message.

next_cursorstring or nullrequired

Send as before for older messages; null at the start.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Messages in a conversation or thread: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404conversation_not_foundThe conversation doesn't exist in this household.
404message_not_foundThe message doesn't exist in this household.
404not_foundThe household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Read the main conversation

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?conversation_id=cnv_00000000000000000000000000' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?conversation_id=cnv_00000000000000000000000000", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?conversation_id=cnv_00000000000000000000000000 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSNHJK40EQ145MG7YFM3

{
  "items": [
    {
      "id": "msg_01M6V9CSMQRZ6GEQ67CPHFX844",
      "conversation_id": "cnv_00000000000000000000000000",
      "thread_root_message_id": null,
      "author": {
        "kind": "person",
        "person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
        "name": "Ada Okafor"
      },
      "format": "markdown",
      "body": "Dinner on Monday is the orzo. Make extra for lunches.",
      "state": "sent",
      "sent_at": "2026-11-07T15:17:52.407Z",
      "edited_at": null,
      "reply_to": null,
      "attachments": [],
      "sticker": null,
      "reactions": [],
      "mentions": [],
      "thread": null,
      "moved_to": null,
      "links": [],
      "address": "/chat/message/msg_01M6V9CSMQRZ6GEQ67CPHFX844"
    },
    {
      "id": "msg_01M6V9CSMTRMX2BPZ3MJTKGREF",
      "conversation_id": "cnv_00000000000000000000000000",
      "thread_root_message_id": null,
      "author": {
        "kind": "person",
        "person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
        "name": "Ada Okafor"
      },
      "format": "markdown",
      "body": "@Ben can you pick Theo up from soccer on Tuesday at 5? I have a late meeting.",
      "state": "sent",
      "sent_at": "2026-11-07T15:17:52.410Z",
      "edited_at": "2026-11-07T15:17:52.430Z",
      "reply_to": null,
      "attachments": [],
      "sticker": null,
      "reactions": [],
      "mentions": [],
      "thread": null,
      "moved_to": null,
      "links": [],
      "address": "/chat/message/msg_01M6V9CSMTRMX2BPZ3MJTKGREF"
    },
    {
      "id": "msg_01M6V9CSMWTTAMGZS9MTJ8YK65",
      "conversation_id": "cnv_00000000000000000000000000",
      "thread_root_message_id": null,
      "author": {
        "kind": "person",
        "person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
        "name": "Ada Okafor"
      },
      "format": "markdown",
      "body": "Practice is at 5:00 pm, so leave by 4:40.",
      "state": "sent",
      "sent_at": "2026-11-07T15:17:52.413Z",
      "edited_at": null,
      "reply_to": {
        "message_id": "msg_01M6V9CSMTRMX2BPZ3MJTKGREF",
        "author_name": "Ada Okafor",
        "excerpt": "@Ben can you pick Theo up from soccer on Tuesday at 5? I have a late meeting."
      },
      "attachments": [],
      "sticker": null,
      "reactions": [
        {
          "emoji": "🙌",
          "count": 1,
          "by": [
            "Ada Okafor"
          ]
        }
      ],
      "mentions": [],
      "thread": null,
      "moved_to": null,
      "links": [],
      "address": "/chat/message/msg_01M6V9CSMWTTAMGZS9MTJ8YK65"
    },
    {
      "id": "msg_01M6V9CSMZCPCNEC9EM5YQPJZP",
      "conversation_id": "cnv_00000000000000000000000000",
      "thread_root_message_id": null,
      "author": {
        "kind": "person",
        "person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
        "name": "Ada Okafor"
      },
      "format": "markdown",
      "body": "Middle shelf, restocked.",
      "state": "sent",
      "sent_at": "2026-11-07T15:17:52.418Z",
      "edited_at": null,
      "reply_to": null,
      "attachments": [
        {
          "file_id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
          "name": "pantry-middle-shelf.png",
          "kind": "image"
        }
      ],
      "sticker": null,
      "reactions": [],
      "mentions": [],
      "thread": {
        "reply_count": 1,
        "last_reply_at": "2026-11-07T15:17:52.422Z"
      },
      "moved_to": null,
      "links": [],
      "address": "/chat/message/msg_01M6V9CSMZCPCNEC9EM5YQPJZP"
    }
  ],
  "next_cursor": null
}

Read a thread

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?thread_root_message_id=msg_01M6V9CSMZCPCNEC9EM5YQPJZP' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?thread_root_message_id=msg_01M6V9CSMZCPCNEC9EM5YQPJZP", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.list?thread_root_message_id=msg_01M6V9CSMZCPCNEC9EM5YQPJZP HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSNPPF636J6DBJR0FS3T

{
  "items": [
    {
      "id": "msg_01M6V9CSN5T718Z3H3SD8CW3D0",
      "conversation_id": "cnv_00000000000000000000000000",
      "thread_root_message_id": "msg_01M6V9CSMZCPCNEC9EM5YQPJZP",
      "author": {
        "kind": "person",
        "person_id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
        "name": "Ada Okafor"
      },
      "format": "markdown",
      "body": "We're out of **rice** though.",
      "state": "sent",
      "sent_at": "2026-11-07T15:17:52.422Z",
      "edited_at": null,
      "reply_to": null,
      "attachments": [],
      "sticker": null,
      "reactions": [],
      "mentions": [],
      "thread": null,
      "moved_to": null,
      "links": [],
      "address": "/chat/message/msg_01M6V9CSN5T718Z3H3SD8CW3D0"
    }
  ],
  "next_cursor": null
}

For Rigel#

Rigel's tool for this query is chat_message_list. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel