Cursors

Endpoints

Requests should be sent to

https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id

appended with the right endpoint for the resource you’re interested in. Your instance ID is available from your application dashboard. Your instance ID is the third component of your instance locator, for example v1:us1:instance_id.

The routes below all begin /cursors/0. In this context 0 is the read cursor type. More cursor types may be added in the future.

Set a cursor

PUT /cursors/0/rooms/:room_id/users/:user_id
Request Body

A JSON object with the single key:

  • position (integer|required): The message ID that the user has read up to
Example Request
$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/rooms/:room_id/users/:user_id \
  -d '{ "position": 42 }'
Response Body

An empty JSON object

Response codes: 201, 400, 503

Get a cursor

GET /cursors/0/rooms/:room_id/users/:user_id
Example Request
$ curl -X GET \
https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/rooms/:room_id/users/:user_id
Response Body

A JSON encoded cursor, or null if no cursor has been set for the requested user and room.

{
  "cursor_type": 0,
  "room_id": "12",
  "user_id": "callum"
  "position": 42,
  "updated_at": "2017-11-29T16:59:55Z"
}

Response codes: 200, 400, 503

Get cursors by user

GET /cursors/0/users/:user_id
Example Request
$ curl -X GET \
https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/users/:user_id
Response Body

A JSON encoded array of all the cursors that have been set for the given user.

[
  {
    "cursor_type": 0,
    "room_id": "12",
    "user_id": "callum"
    "position": 42,
    "updated_at": "2017-11-29T16:59:55Z"
  },
  {
    "cursor_type": 0,
    "room_id": "140",
    "user_id": "callum"
    "position": 1001,
    "updated_at": "2017-11-29T16:59:55Z"
  }
]

Response codes: 200, 400, 503

Get cursors by room

GET /cursors/0/rooms/:room_id
Example Request
$ curl -X GET \
https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/rooms/:room_id
Response Body

A JSON encoded array of all the cursors that have been set in the given room.

[
  {
    "cursor_type": 0,
    "room_id": "128",
    "user_id": "alice"
    "position": 42,
    "updated_at": "2017-11-29T16:59:55Z"
  },
  {
    "cursor_type": 0,
    "room_id": "128",
    "user_id": "bob"
    "position": 1001,
    "updated_at": "2017-11-29T16:59:55Z"
  }
]

Response codes: 200, 400, 503

Subscribe to cursors by user

SUBSCRIBE /cursors/0/users/:user_id
Example Request
$ curl -X SUBSCRIBE \
https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/users/:user_id

Subscription events (by user)

When the stream opens, an initial_state event containing all of the user’s previously set cursors is sent

{
  "event_name": "initial_state",
  "data": {
    "cursors": [
      {
        "cursor_type": 0,
        "room_id": "12",
        "user_id": "callum"
        "position": 42,
        "updated_at": "2017-11-29T16:59:55Z"
      },
      {
        "cursor_type": 0,
        "room_id": "140",
        "user_id": "callum"
        "position": 1001,
        "updated_at": "2017-11-29T16:59:55Z"
      }
    ]
  }
}

followed by new_cursor events for any subsequent updates.

{
  "event_name": "new_cursor",
  "data": {
    "cursor_type": 0,
    "room_id": "12",
    "user_id": "callum"
    "position": 128,
    "updated_at": "2017-11-29T16:59:55Z"
  },
  "timestamp": "2017-12-18T12:34:18Z"
}

Subscribe to cursors by room

SUBSCRIBE /cursors/0/rooms/:room_id
Example Request
$ curl -X SUBSCRIBE \
https://us1.pusherplatform.io/services/chatkit_cursors/v2/:instance_id/cursors/0/rooms/:room_id

Subscription events (by room)

When the stream opens, an initial_state event containing the previously set cursors (if any) for each member of a room is sent

{
  "event_name": "initial_state",
  "data": {
    "cursors": [
      {
        "cursor_type": 0,
        "room_id": "128",
        "user_id": "alice"
        "position": 42,
        "updated_at": "2017-11-29T16:59:55Z"
      },
      {
        "cursor_type": 0,
        "room_id": "128",
        "user_id": "bob"
        "position": 1001,
        "updated_at": "2017-11-29T16:59:55Z"
      }
    ]
  }
}

followed by new_cursor events for any subsequent updates.

{
  "event_name": "new_cursor",
  "data": {
    "cursor_type": 0,
    "room_id": "12",
    "user_id": "callum"
    "position": 42,
    "updated_at": "2017-11-29T16:59:55Z"
  },
  "timestamp": "2017-12-18T12:34:18Z"
}