Chatkit Files API

The Chatkit Files service is where we store your instance's files, for attachment to messages and storage in rooms. While the client and server SDKs provide methods for interacting with the service, we also provide this API for you to use.

Endpoint

Chatkit Files requests should be sent to:

https://us1.pusherplatform.io/services/chatkit_files/v1/: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.

Get File

GET /rooms/:room_id/files/:file_name

Used to retrieve a resource link for a single file. The resource link has a TTL, when it expires the link will stop functioning and a new resource link will need to be requested.

Response Body

A JSON object containing the following keys:

  • file (json object): contains the file info json object:
    • name (string): name of the file, prefixed with the instanceID and roomID.
    • bytes (int): file size in bytes.
    • last_modified (int): Unix timestamp of last POST modification.
  • resource_link (string): file download URL.
  • ttl (int): Unix timestamp of the resource_link ttl.

Example:

1
2
3
4
5
6
7
8
9
{
  "file": {
      "name": "picture.jpg",
      "bytes": 154283,
      "last_modified": 1511283829000000000
  },
  "resource_link": "https://download-link.horse",
  "ttl": 1513853795450138571
}
Response Codes
  • 200 success
  • 400 user error
  • 401 request unauthorized
  • 404 file not found
  • 5xx server error

Post File

POST /rooms/:room_id/users/:user_id/files/:file_name

Used to upload a file to Chatkit Files. File size limit is 5 MB.

URL

The file will be stored with the name defined in the URL:file_name parameter. The :file_name parameter allows the following characters: A-Z,a-z, 0-9,., _,-.

Request Body

A multipart/form request body is required (as defined by RFC 2388). The form key name should be "file" and the value should be the file to be uploaded. All other form keys will be ignored.

Response Body

A JSON object containing the following keys:

  • resource_link (string): "Get File" endpoint for this file.
  • type (string): the type of file, either "audio", "video", "image" or "file".

Example:

1
2
3
4
{
  "resource_link": "https://get-your-file-here.org.net",
  "type": "image"
}
Response Codes
  • 200 success
  • 400 user error
  • 401 request unauthorized
  • 5xx server error

Delete File

DELETE /rooms/:room_id/files/:file_name

Delete a file that has been previously uploaded to the service.

Response Body

There is no accompanying response body.

Response Codes
  • 204 success
  • 400 user error
  • 401 request unauthorized
  • 5xx server error

Delete User Files

DELETE /users/:user_id

Delete all files uploaded by a user.

Response Body

There is no accompanying response body.

Response Codes
  • 200 success
  • 400 user error
  • 401 request unauthorized
  • 5xx server error