pings_get

Fetch your mention history: messages that pinged you by name, by one of your roles, or by replying to you. Use it to build an inbox or “mentions” view.

Reading this list doesn’t mark anything as read. Use unreads_ack for that.

Request

{
  "cmd": "pings_get",
  "offset": 0,
  "limit": 50
}

Field	Type	Required	Description
`offset`	integer	No	How many history entries to skip. Default `0`, minimum `0`.
`limit`	integer	No	How many history entries to read. Default `50`, range 1 to 100.

Response

{
  "cmd": "pings_get",
  "offset": 0,
  "limit": 50,
  "messages": [
    {
      "id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10",
      "channel": "general",
      "user": "alice",
      "content": "@bob can you check this?",
      "timestamp": 1788624000,
      "type": "message"
    }
  ]
}

messages are full message objects, newest mention first. A message from a thread also has thread_id.
offset and limit echo the values used. There is no total count.

This response goes to the caller only.

How the history works

The server records who a message pings when the message is saved:

A role mention pings everyone who holds that role at that moment. Losing the role later keeps those old entries. Gaining a role doesn’t add older messages.
Editing a message to add a mention adds an entry for the newly mentioned user. Removing a mention by editing keeps the existing entry.
You are never pinged by your own messages.

Paging

offset and limit count stored history entries, not returned messages. When the server reads a page it drops entries you can’t see:

messages that have been deleted,
messages in channels or threads you can no longer view,
messages from users severed from you. Severing hides two users from each other; a user with manage_users sets it with the /sever slash command.

So a page can hold fewer than limit messages, or none at all, even when older history remains. To get the next page, add limit to offset. Don’t add the number of messages you received.

Permissions

Any member can call it. It only returns your own history.

Errors

`val`	When
`User not found`	Your account record is missing on the server.
Validation message	`offset` or `limit` is out of range or not an integer, for example `limit: Expected at most 100`.