API Reference (V3)

Response and Error Codes

The API will always return a 2xx response code for successful requests, while malformed or failed requests will return either a 4xx or 5xx response code along with a JSON response containing:

  • error: the type of error.
  • description (optional): a longer description of the error.

The exact response codes returned will vary with each request and endpoint.

Success response codes include:

  • 200 Request was successful.
  • 201 Request was processed and a new resource was created.
  • 204 Request was understood, but there is no content to be returned.

In the case of a 4xx error, you should fix the problem with your request. Specific error codes and their meanings are detailed below:

  • 400 Request body is malformed (invalid JSON).
  • 403 User making the request is not authorized to access the resource.
  • 404 Requested resource is not found.
  • 422 Request body is well formed JSON, but contains a value whose type is unsupported.
  • 401 Request unauthorized.

401 errors may be returned if the token is invalid at any time.

In the case of a 5xx error, you should retry later.

Endpoints

There are multiple routes provided for rooms, messages and users from the API endpoint. To learn more about these concepts, refer to the core concepts page.

API requests should be sent to

https://us1.pusherplatform.io/services/chatkit/v3/:instance_id

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

Users

Create a User

POST /users

This endpoint requires a super-user token, more information on tokens can be found here.

Request body

A JSON object with the following keys:

  • id (string|required): User id assigned to the user in your app.
  • name: (string|required): Name of the new user.
  • avatar_url (string|optional): A link to the user’s photo/image.
  • custom_data (object|optional): Custom data that may be associated with a user.

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users \
  -d '{"name": "John Doe", "id": "john", "avatar_url": "https://gravatar.com/img/2124", "custom_data": {"email": "john@example.com"}}'

Response body

A JSON object containing the following keys:

  • id (string): Id of the user.
  • name (string): Name of the new user.
  • avatar_url (string): A link to the user’s photo/image.
  • custom_data (object): Custom data that may be associated with a user.
  • created_at (string): Timestamp of when the user object was created.
  • updated_at (string): Timestamp of when the user object was updated.
1
2
3
4
5
6
7
8
9
10
{
  "id": "john",
  "name": "John Doe",
  "avatar_url": "https://gravatar.com/img/8819",
  "custom_data": {
    "email": "john@example.com"
  },
  "created_at":"2017-03-23T11:36:42Z",
  "updated_at":"2017-03-23T11:36:42Z"
}

Response codes

201, 400, 422, 503

Batch Create Users

POST /batch_users

This endpoint requires a su token, more information on tokens can be found here.

Request body

A JSON object with the following keys:

  • users (array|required): Array of user objects to be created. Max 25 users created per request.

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/batch_users \
  -d '{"users": [{"name": "John Doe", "id": "john", "avatar_url": "https://gravatar.com/img/2124", "custom_data": {"email": "john@example.com"}}, {"name": "Jane Doe", "id": "jane", "avatar_url": "https://gravatar.com/img/2123", "custom_data": {"email": "jane@example.com"}}] }'

Response body

A JSON array containing a list of created user objects

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "id": "john",
    "name": "John Doe",
    "avatar_url": "https://gravatar.com/img/8819",
    "custom_data": {
      "email": "john@example.com"
    },
    "created_at":"2017-03-23T11:36:42Z",
    "updated_at":"2017-03-23T11:36:42Z"
  },
  {
    "id": "jane",
    "name": "Jane Doe",
    "avatar_url": "https://gravatar.com/img/8820",
    "custom_data": {
      "email": "jane@example.com"
    },
    "created_at":"2017-03-23T11:36:47Z",
    "updated_at":"2017-03-23T11:36:47Z"
  }
]

Response codes

201, 400, 422, 503

Get User

GET /users/:user_id

Example request

$ curl \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id

Response body

A JSON object containing the following keys:

  • id (string): Id of the user.
  • name (string): Name of the new user.
  • avatar_url (string): A link to the user’s photo/image.
  • custom_data (object): Custom data that may be associated with a user.
  • created_at (string): Timestamp of when the user object was created.
  • updated_at (string): Timestamp of when the user object was updated.

Example

1
2
3
4
5
6
7
8
9
10
{
  "id": "john",
  "name": "John Doe",
  "avatar_url": "https://gravatar.com/img/8819",
  "custom_data": {
    "email": "john@example.com"
  },
  "created_at":"2017-03-23T11:36:42Z",
  "updated_at":"2017-03-23T11:36:42Z"
}

Response codes

200, 404, 503

Get Users

GET /users

Example request

$ curl \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users

Query parameters

  • from_ts (string|optional): Timestamp (inclusive) from which users with a more recent created_atshould be returned. If no timestamp is provided then the users created the longest time ago will be returned. The number of users returned is 20. The timestamp should use the ISO 8601 notation; specifically the B8601DZw.d format. An example of a timestamp in this format is 2018-04-17T14:02:00Z.
  • limit (string|optional): limit of users to return. must be between1 and 100. If omitted will default to 20.

Response body

An array of User objects as outlined in Get User.

Response codes

200, 422, 503

Get Users by IDs

GET /users_by_ids

Example request

$ curl \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users_by_ids?id=ham&id=booker

Query parameters

  • id (string|required): Repeating key value pairs for each User ID that is to be retrieved. This is parsed into an array on the server side.

Response body

An array of User objects as outlined in Get User.

Response codes

200, 422, 503

Update a User

PUT /users/:user_id

Request body

A JSON object with the following keys:

  • name (string|optional): Updated name for the user.
  • avatar_url (string|optional): Updated user image link.
  • custom_data (object|optional): Updated custom data.

The request body must contain at least one of these fields. If none are provided, the request will be rejected.

An appropriate success or failure response code will be returned.

Example request

$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id \
  -d '{"name": "Jake", "avatar_url": "https://imgur.com/img/6987", "custom_data": {"email": "jake@example.com"}}'

Response codes

204, 400, 404, 503

Delete a User

This endpoint requires a su token, more information on tokens can be found here.

DELETE /users/:user_id

Example request

$ curl -X DELETE \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id

Please note: Deleting a user will remove any memberships associated with the user in any room.

Response codes

204, 400, 404, 503

Get User Rooms

GET /users/:user_id/rooms

Query Parameters

  • joinable (boolean): Indicates if only rooms that the user can join should be returned.

Example request

$ curl -X GET \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id/rooms

Response body

A JSON object with the following keys:

  • rooms (array): A list of all the Rooms the user is a member of along with room memberships and user objects.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "rooms": [
    {
      "id": "1",
      "created_by_id": "john",
      "name": "mycoolroom",
      "private": false,
      "custom_data": {
        "cool": true
      },
      "created_at": "2017-03-23T11:36:42Z",
      "updated_at": "2017-03-23T11:36:42Z",
      "member_user_ids": ["luke", "ham"]
    }
  ]
}

Response codes

200, 400, 404, 503

Join a Room

POST /users/:user_id/rooms/:room_id/join

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id/rooms/:room_id/join

Response body

1
2
3
4
5
6
7
8
9
{
  "id": "1",
  "created_by_id": "john",
  "name": "mycoolroom",
  "private": false,
  "created_at": "2017-03-23T11:36:42Z",
  "updated_at": "2017-03-23T11:36:42Z",
  "member_user_ids": ["luke", "ham"]
}

Response codes

200, 503, 400

Leave a Room

POST /users/:user_id/rooms/:room_id/leave

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users/:user_id/rooms/:room_id/leave

Response body

There is no accompanying response body. An appropriate status will be returned.

Response codes

200, 503, 400

Receive User Events

SUBSCRIBE /users

Example request

$ curl -X SUBSCRIBE https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/users

Response body

Not applicable since this opens up a stream of events that can be consumed. See Subscription Events.

Response codes

400, 503

Rooms

Create a Room

POST /rooms

Request body

A JSON object with the following keys:

  • name (string|optional): Represents the name with which the room is identified. A room name must not be longer than 40 characters and can only contain lowercase letters, numbers, underscores and hyphens.
  • private (boolean|optional): Indicates if a room should be private or public. By default, it is public.
  • custom_data (object|optional): Custom data that will be associated with the Room.
  • user_ids(array|optional): If you wish to add users to the room at the point of creation, you may provide their user IDs.

Note that leaving the request body empty means that a room will be created with an automatically assigned name and no users.

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms \
  -d '{"name": "my-cool-room", "user_ids": ["ham", "will"]}'

Response body

A JSON object containing the following keys:

  • id (string): A unique id for the room that was created.
  • created_by_id (string): User id that created the room.
  • name (string): Room name.
  • private (boolean): Indicates if the room is private or public.
  • custom_data (object|optional): Custom data that was associated with the Room.
  • created_at (string): Timestamp of when the room was created.
  • updated_at (string): Timestamp of when the room was updated.

Example:

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "1",
  "created_by_id": "john",
  "name": "mycoolroom",
  "custom_data": {
    "cool": true
  },
  "private": true,
  "created_at": "2017-03-23T11:36:42.399058434Z",
  "updated_at": "2017-03-23T11:36:42.399058434Z"
}

Response codes

201, 400, 422, 503

Fetch a Room

GET /rooms/:room_id

Example request

$ curl \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id

Response body

A JSON object containing the following keys:

  • id (string): A unique id for the room that was created.
  • name: (string): Room name.
  • created_by_id (string): User id that created the room.
  • private (boolean): Indicates if the room is private or public.
  • custom_data (object|optional): Custom data that was associated with the Room.
  • created_at (string): Timestamp of when the room was created.
  • updated_at (string): Timestamp of when the room was updated.

Example:

1
2
3
4
5
6
7
8
9
10
11
{
  "id": "1",
  "name": "my-cool-room",
  "created_by_id": "john",
  "private": false,
  "custom_data": {
    "cool": true
  },
  "created_at":"2017-03-23T11:36:42.399058434Z",
  "updated_at":"2017-03-23T11:36:42.399058434Z"
}

Response codes

200, 400, 422, 404, 503

Fetch Rooms

GET /rooms

Example request

curl https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms

Query Parameters

  • from_id (string|optional): ID (exclusive) from which rooms with larger IDs should be returned. The number of room returned is at most 100 per request.
  • include_private (string|optional): If `true` will also return private rooms present in the instance. This requires a su token.

Response codes

200, 422, 503

Delete a Room

DELETE /rooms/:room_id

Example request

$ curl -X DELETE \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id

Response codes

204, 400, 404, 503

Update a Room

PUT rooms/:room_id

Request body

A JSON object with the following keys:

  • name (string|optional): New name for the room.
  • private (boolean|optional): Indicates if a room should be private or public.
  • custom_data (object|optional): Custom data that was associated with the Room.

Note that once custom_data for a room has been set you then cannot completely clear the custom_data for the room. You can, however, set the custom_data to be an empty object, i.e. {}.

Example request

$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms \
  -d '{"name": "my-cool-room-2", "private": false}'

Note that updating a room will return no response body. Updated resources must be fetched using a subsequent request.

Response codes

204, 400, 404, 422, 503

Add Users

PUT rooms/:room_id/users/add

Request body

A JSON object with the following keys:

  • user_ids (array|optional): List of user IDs to add to the room.

Example request

$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/users/add \
  -d '{"user_ids": ["ham", "will"]}'

An appropriate response code will be returned with no accompanying response body.

Response codes

204, 400, 404, 422, 503

Remove Users

PUT /rooms/:room_id/users/remove

Request body

A JSON object with the following keys:

  • user_ids (array|optional): List of user id's to remove from the room.

Example request

$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/users/remove \
  -d '{"user_ids": ["ham", "will"]}'

An appropriate response code will be returned with no accompanying response body.

Response codes

204, 400, 404, 422, 503

Subscribe to a Room

Subscribe to a room to receive messages and typing indicators sent to that room.

SUBSCRIBE /rooms/:room_id

Query Parameters

  • message_limit (integer|optional): Specifies the number of messages that should be retrieved from the persistent store and populated after the subscription is established. By default it is 20. The maximum value is 100.

Example request

$ curl -X SUBSCRIBE \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id?message_limit=50

Response body

This opens up a stream of events, see Subscription Events for general information. Events on this subscription are one of two types.

New message events, which have event name "new_message" and data one message object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "event_name": "new_message",
  "timestamp": "2017-03-23T11:36:42Z",
  "data": {
    "id": "1",
    "user_id": "viv",
    "room_id": "1",
    "created_at":"2017-03-23T11:36:42Z",
    "updated_at":"2017-03-23T11:36:42Z",
    "parts": [
      {
        "type": "text/plain",
        "content": "Hello"
      }
    ]
  }
}

Is typing events, which have event name "is_typing" and data consisting of the user ID of the user who is typing. See Typing Indicators.

1
2
3
4
5
6
7
{
  "event_name": "is_typing",
  "timestamp": "2017-03-23T11:36:42Z",
  "data": {
    "user_id": "alice"
  }
}
Response codes

400, 403, 503

Subscribe to Room Memberships

Subscribe to a room’s memberships to keep up to date with the members of that room.

SUBSCRIBE /rooms/:room_id/memberships
Example request
$ curl -X SUBSCRIBE \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/memberships
Response body

Not applicable since this opens up a stream of events that can be consumed. See Subscription Events.

Response codes

400, 403, 503

Typing Indicators

POST /rooms/:room_id/typing_indicators

Request body

empty

Example request

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/user_id:/:user_id/rooms/:room_id/typing_indicators

An appropriate response code will be returned with no accompanying response body.

Response codes

200, 400, 422, 503

Messages

Message Format

A message is a JSON object with the following properties:

  • id: The message ID.
  • user_id: The ID of the user who sent the message.
  • room_id: The ID of the room to which the message belongs.
  • created_at: The creation time of the message.updated_at: The time of the last update to the message.
  • parts: an array of the message’s parts.

Where each message part is an object with the following properties:

And exactly one of the following.

  • content The string content of the part.
  • url A URL.
  • attachment An attachment object. See below.

And an attachment object has the following properties

  • id The ID of the attachment.
  • download_url Signed URL for downloading the attachment data (may expire and require refreshing).
  • refresh_url URL to refresh a stale attachment.
  • expiration Timestamp at which time the download_url expires.
  • name The name of the attached file.
  • size The size of the attached file in bytes.
  • custom_data Any custom data that was associated with the file at upload time.

For example, the following is a message with a plain text part, a URL, and an attachment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "id": 3,
  "user_id": "ham",
  "room_id": "1",
  "parts": [
    {
      "type": "text/plain",
      "content": "see attached document and figure"
    },
    {
      "type": "application/pdf",
      "attachment": {
        "id": "793c8a94-1702-4b7b-92aa-62f3be1a8efb",
        "download_url": "https://example.download.url/793c8a94-1702-4b7b-92aa-62f3be1a8efb",
        "refresh_url": "https://example.refresh.url/793c8a94-1702-4b7b-92aa-62f3be1a8efb",
        "expiration": "2019-02-12T17:29:22Z",
        "name": "super-interesting-document.pdf",
        "size": 1234,
        "custom_data": {
          "foo": "bar"
        }
      }
    },
    {
      "type": "image/png",
      "url": "https://example.com/figure01.png"
    }
  ],
  "created_at":"2017-03-23T11:36:42Z",
  "updated_at":"2017-03-23T11:36:42Z"
}

Send a Message

POST /rooms/:room_id/messages

Request body

A JSON object with a single key: "parts", with value an array of message parts.

1
2
3
{
  "parts": [ ... ]
}

Each message part is a JSON object with the following properties.

  • type (string|required): The MIME type of the part.

And exactly one of the following.

  • content (string) The string content of the part.
  • url (string) A URL.
  • attachment (object) With a single key, id, referencing an uploaded attachment.

Response body

1
2
3
{
  "message_id": 10003
}

Example Requests

A simple plain text message with one inline part:

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/messages \
  -d '{
    "parts": [
      {
        "type": "text/plain",
        "content": "Hola!"
      }
    ]
  }'

A more complex message composed of an inline text part, a pdf attachment, and a link to an image.

$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/messages \
  -d '{
    "parts": [
      {
        "type": "text/plain",
        "content": "See attached pdf and image."
      },
      {
        "type": "application/pdf",
        "attachment": {
          "id": "793c8a94-1702-4b7b-92aa-62f3be1a8efb"
        }
      },
      {
        "type": "image/jpeg",
        "url": "https://images.com/mycoolimage.jpg"
      }
    ]
  }'

Response codes

201, 400, 404, 422, 503

Upload an Attachment

Before an attachment can be sent as part of a message, it must be uploaded. To upload an attachment, first request a pre-signed upload URL:

POST /rooms/:room_id/attachments

Request body

A JSON object with the following properties:

  • content_type (string | required): The MIME type of the attachment.
  • content_length (number | required): The size of the content in bytes – so that we can verify that the attachment has been fully uploaded.
  • name (string | optional): The name of the attached file.
  • custom_data (any | optional): Arbitrary custom metadata to associate with the file.

Response body

A JSON object with the following properties:

  • attachment_id: The ID of the attachment, used to reference this attachment when using it in a message part.
  • upload_url: A pre-signed upload URL.

To actually upload the attachment, send a PUT request to the upload_url with the file to be uploaded as the body.

Fetch Messages From a Room

GET /rooms/:room_id/messages

Query Parameters

There are several query string parameters that can be used to include more data in the response:

  • initial_id (integer|optional): Starting id of the range of messages (non-inclusive).
  • limit (integer|optional): Number of messages to return. If left empty, the limit is set to 20 by default. The maximum number of messages that can be fetched is 100.
  • direction (string|optional): Order of messages - one ofnewer orolder.

Note that keys other than these will be ignored.

Response body

An array of messages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
[
  {
    "id": 2,
    "user_id": "ham",
    "room_id": "1",
    "parts": [
      {
        "type": "text/plain",
        "content": "Hola!"
      }
    ],
    "created_at": "2017-03-23T11:36:42Z",
    "updated_at": "2017-03-23T11:36:42Z"
  },
  {
    "id": 3,
    "user_id": "ham",
    "room_id": "1",
    "parts": [
      {
        "type": "text/plain",
        "content": "see attached document"
      },
      {
        "type": "application/pdf",
        "attachment": {
          "id": "793c8a94-1702-4b7b-92aa-62f3be1a8efb",
          "download_url": "https://example.download.url/793c8a94-1702-4b7b-92aa-62f3be1a8efb",
          "refresh_url": "https://example.refresh.url/793c8a94-1702-4b7b-92aa-62f3be1a8efb",
          "expiration": "2019-02-12T17:29:22Z",
          "name": "super-interesting-document.pdf",
          "size": 1234,
          "custom_data": {
            "foo": "bar"
          }
        }
      }
    ],
    "created_at":"2017-03-23T11:36:42Z",
    "updated_at":"2017-03-23T11:36:42Z"
  }
]

Example request

$ curl -X GET \
  https://us1.pusherplatform.io/services/chatkit/v3/:instance_id/rooms/:room_id/messages?initial_id=1&direction=newer&limit=10

Response codes

200, 400, 422, 503

Delete a Message

DELETE /messages/:message_id

Deletes the message with the given ID and sends a tombstone (message where the text has been replaced with "DELETED") to all subscribers.

This endpoint requires a su token, more information on tokens can be found here.

Example request

$ curl -X DELETE /messages/:message_id

Response codes

204, 400, 422, 503