Skip to content
Rigel docs
Open Rigel

Mark a conversation read up to a message

chat.read.mark

POST/api/v1/households/{household_id}/commands/chat.read.mark

  • Command
  • Not for Rigel
  • Applies offline

Moves my read point in a conversation forward to a message (threads read with their conversation), and marks my chat notifications for it read up to then. A point earlier than where I am does nothing. Errors: conversation_not_found, message_not_found, no_person.

Parameters#

Mark a conversation read up to a message: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Mark a conversation read up to a message: request body fields
FieldDescription
conversation_idstringrequired

A conversation ID, such as cnv_01JC0000000000000000000000.

message_idstringrequired

The latest message I've seen, in the conversation or one of its threads.

Response#

200 The command was applied.

Mark a conversation read up to a message: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

versionintegerrequired

The household version after the command.

Errors#

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

Mark a conversation read up to a message: 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_found
  • The conversation doesn't exist in this household.
  • A conversation that isn't there.
404message_not_found
  • The message doesn't exist in this household.
  • A message of another conversation.
  • A message that isn't there, in the main chat before its row exists.
404not_foundThe household doesn't exist, or you aren't a member of it.
409no_personA signed-in account that isn't a person in the family.
409idempotency_key_reusedThe Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

The first read point, which marks my notifications up to it read and not later ones or anyone else's

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R09AVGWZHJ1M534W3H

{
  "result": {},
  "version": 1
}

Moving forward updates the point

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000002"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000002",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000002"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R07CY7S1R8JQJHBF5A

{
  "result": {},
  "version": 1
}

An earlier message than the point does nothing

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0GM55KSZHM8WSC992

{
  "result": {},
  "version": 1
}

The same message again does nothing

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0YQT2PWC6FYSQEGSV

{
  "result": {},
  "version": 1
}

A thread reply reads with its conversation

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000003"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000003",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000003"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0107YAES1DN9DX51X

{
  "result": {},
  "version": 1
}

A message of another conversation

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000002",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000002",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000002",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0DS858FCS4K5TE5ZZ

{
  "error": {
    "code": "message_not_found",
    "message": "That message isn't in this topic. No changes were applied.",
    "details": {
      "message_id": "msg_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0DS858FCS4K5TE5ZZ"
  }
}

A message that isn't there, in the main chat before its row exists

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_00000000000000000000000000",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_00000000000000000000000000",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_00000000000000000000000000",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0BSXJ5XDCFSH0GC0R

{
  "error": {
    "code": "message_not_found",
    "message": "That message isn't there any more. No changes were applied.",
    "details": {
      "message_id": "msg_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0BSXJ5XDCFSH0GC0R"
  }
}

A conversation that isn't there

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000003",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000003",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000003",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0GBTBTR3X8A9WBGZ1

{
  "error": {
    "code": "conversation_not_found",
    "message": "That topic isn't there any more. No changes were applied.",
    "details": {
      "conversation_id": "cnv_01JC0000000000000000000003"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0GBTBTR3X8A9WBGZ1"
  }
}

A signed-in account that isn't a person in the family

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01JC0000000000000000000001",
    message_id: "msg_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "conversation_id": "cnv_01JC0000000000000000000001",
  "message_id": "msg_01JC0000000000000000000001"
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R00KQ95THMJMPQ1ZSV

{
  "error": {
    "code": "no_person",
    "message": "Only a member of the family can write in chat. No changes were applied.",
    "details": {},
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R00KQ95THMJMPQ1ZSV"
  }
}

Mark a conversation read

Moves your read point forward to a message.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/chat.read.mark' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSP35YTRNFMVZFEMKCMW' \
  -d '{
  "conversation_id": "cnv_01M6V9CSNXY07QQP2MFR78VN9K",
  "message_id": "msg_01M6V9CSNYDRWCJMP0BFEJ1TQD"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/chat.read.mark", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSP35YTRNFMVZFEMKCMW",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    conversation_id: "cnv_01M6V9CSNXY07QQP2MFR78VN9K",
    message_id: "msg_01M6V9CSNYDRWCJMP0BFEJ1TQD",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/chat.read.mark HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSP35YTRNFMVZFEMKCMW

{
  "conversation_id": "cnv_01M6V9CSNXY07QQP2MFR78VN9K",
  "message_id": "msg_01M6V9CSNYDRWCJMP0BFEJ1TQD"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSP35KHGFBG8GCHTMX58

{
  "result": {},
  "version": 121
}

For Rigel#

Rigel's tool for this command is chat_read_mark. Rigel doesn't have this as a tool. It's for people and scripts. The agent guide has the rest.

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