Ruby Server SDK

Ruby SDK for the Chatkit service.

Setting Up

Installing

Via RubyGems:

gem install pusher-chatkit-server

Alternatively, you may add it as a dependency to your Gemfile and use Bundler to fetch the gem:

gem 'pusher-chatkit-server'

Requiring the SDK

To make use of Chatkit you will also need to require it.

require 'chatkit'

Instantiate the Client Object

The Client constructor takes an options hash with the following properties:

  • instance_locator (required): your instance locator; get this from your dashboard (click on your instance and go to the Keys tab)
  • key (required): your key; get this from your dashboard (click on your instance and go to the Keys tab)
Example
1
2
3
4
chatkit = Chatkit::Client.new({
  instance_locator: YOUR_INSTANCE_LOCATOR,
  key: YOUR_KEY,
})

Authentication

Authenticate a User

use authenticate to generate a HTTP status and body appropriate to use as the response of an authentication request from one of your clients. e.g.

1
2
3
4
5
6
7
8
9
10
11
12
# Example using Sinatra

post '/auth' do
  auth_data = chatkit.authenticate({
    user_id: 'your-user-id'
  })
  [
    auth_data.status,
    auth_data.headers,
    auth_data.body.to_json
  ]
end

Users

Create a User

Create a new User to use with the Chatkit service.

Usage

The create_user method takes a hash with the following keys:

  • id (string, required): An ID that uniquely identifies a User in the Chatkit service.
  • name (string, required): A name assigned to the user.
  • avatar_url (string, optional): Valid URL pointing to an image.
  • custom_data (object, optional): Map of user related properties.
1
chatkit.create_user({ id: "user_id", name: "user" })
Response

Returns the User hash if the User was successfully created

1
2
3
4
5
6
{
  "id": "user_id",
  "name": "user",
  "created_at": "2017-03-23T11:36:42Z",
  "updated_at": "2017-03-23T11:36:42Z"
}

Create Many Users

Create new users to use with the Chatkit service.

Usage

If you want to create multiple users in one go, you can use the create_users method. Takes a hash with the following keys:

  • users (array, required): An array of user hashes (see above)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
chatkit.create_users({
  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

Returns an array of the user hashes for the successfully created users

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"
  }
]

Update a User

The update_user method updates a previously created User. Takes a hash with the following keys

  • id (string, required): An ID that uniquely identifies a User in the Chatkit service.
  • name (string, optional): A name assigned to the user.
  • avatar_url (string, optional): Valid URL pointing to an image.
  • custom_data (object, optional): Map of user related properties.
1
2
3
4
5
6
chatkit.update_user({
  id: hams_id,
  name: 'No longer Ham',
  avatar_url: 'https://test.update.com',
  custom_data: { something: 'NEW', and: 777 }
})

No response body is returned on a successful update.

Delete a User

The delete_user method takes a hash with the following keys:

  • id (string, required): Unique ID to match the user to be deleted.
1
chatkit.delete_user({ id: "user_id" })
Response

No response body is returned on successful deletion.

Get a User

Use the get_user method to get the details of a user with a given ID. Takes a hash with the following keys:

  • id (string, required): Unique ID to match the user to be deleted.
1
chatkit.get_user({ id: "user_id" })

Returns a user hash

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

Get Users

Usage

The get_users function takes no arguments.

1
chatkit.get_users()
Response

Returns an array of users

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

Get Users by ID

Usage

The get_users_by_id function takes a hash with the following keys:

  • user_ids (array, required): an array of user IDs (strings)
1
2
3
chatkit.get_users_by_id({
  user_ids: ["matz", "john"]
})
Response

Returns an array of users

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

Rooms

Create a Room

The create_room method creates a new room. Takes a hash with the following keys:

  • creator_id (string, required): The ID of the user who is creating the room.
  • name (string, required): The name of the room.
  • private (boolean, optional): Whether or not the room is to be private. Defaults to false.
  • user_ids (array, optional): An array of user IDs to be added as members of the room.
  • custom_data (hash, optional): A hash of key value pairs that will be attached as room custom data.
1
2
3
4
5
6
7
chatkit.create_room({
  creator_id: user_id,
  name: 'my room',
  user_ids: [user_id2],
  private: true,
  custom_data: { foo: 'bar' }
})

Update a Room

The update_room method updates an existing room. Takes a hash with the following keys:

  • id (string, required): The ID of the room that is being updated.
  • name (string, optional): The name of the room.
  • private (boolean, optional): Whether or not the room is to be private.
  • custom_data (hash, optional): A hash of key value pairs that will be attached as room custom data.
1
2
3
4
5
6
chatkit.update_room({
  creator_id: user_id,
  name: 'members only',
  private: true,
  custom_data: { foo: 'bar' }
})

Delete a Room

The delete_room method irreversibly deletes a room. Takes a hash with the following keys:

  • id (string, required): The ID of the room to be deleted.
1
2
3
chatkit.delete_room({
  id: room_id,
})

Get a Room

Fetch a room by its ID. Takes an object with a single id parameter.

1
2
3
chatkit.get_room({
  id: "123"
})

Get Rooms

get_rooms fetches rooms, ordered by ID, in pages of 100 at a time. Takes an object with the following properties:

  • from_id (string, optional) starting ID of the range of rooms (exclusive)
  • include_private (boolean, optional) If true private rooms will be included in the response, otherwise they will be filtered out.
1
chatkit.get_rooms()

Get User Joinable Rooms

The get_user_joinable_rooms function takes an object of the form:

  • id (String, required): ID of the user for whom rooms should be retrieved
1
chatkit.get_user_joinable_rooms({ id: user_id })
Response

An array of JSON objects

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

Get User Rooms

The get_user_rooms function takes an object of the form:

  • id (String, required): ID of the user for whom rooms should be retrieved
1
chatkit.get_user_rooms({ id: user_id })
Response

An array of JSON objects

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

Add Users to a Room

add_users_to_room adds users as members of a room. Takes an object with the following parameters

  • room_id (string, required) The room to add users to
  • user_ids ([]string, required) The users to add
1
2
3
4
chatkit.add_users_to_room({
  room_id: room_id,
  user_ids: ['alice', 'bob']
})

Remove Users From a Room

remove_users_from_room removes users with the given ID from a room. Takes an object with the following parameters

  • room_id (string, required) The room to remove users from
  • user_ids ([]string, required) The users to remove
1
2
3
4
chatkit.remove_users_from_room({
  room_id: room_id,
  user_ids: ['alice', 'bob']
})

Messages

Send a Message

send_message publishes a message to a room as the given user. Takes an object of the form:

  • user_id (string, required) the ID of the user to send the message as
  • room_id (string, required) the ID of the room to send the message to
  • text (string, required) the content of the message
1
2
3
4
5
chatkit.send_message({
  user_id: 'alice',
  room_id: '123',
  text: 'hello!',
})

Get Messages From a Room

get_room_messages fetches the messages from a room. Messages are returned in pages of at most 100 at a time. Takes an object with the following properties:

  • room_id (string, required) the ID of the room to get messages from
  • direction (string, optional) direction to page back through messages – one of "older" or "newer"
  • initial_id (string, optional) starting ID of the range of messages (exclusive)
  • limit (number, optional) number of messages to return in a single page (defaults to 20, maximum 100)
1
2
3
4
chatkit.get_room_messages({
  room_id: room_id,
  limit: 10,
})

Delete a Message

delete_message irreversibly deletes the message and replaces it with a generic tombstone. Takes an object with a single id parameter: the ID of the message to be deleted.

1
2
3
chatkit.delete_message({
  id: id_of_message_to_delete
})

Read Cursors

Set a Read Cursor

set_read_cursor sets the read cursor for the given user and room to the given position (the latest read message ID). Takes an object with the following properties

  • user_id (string, required) The ID of the user to set the cursor for.
  • room_id (string, required) The ID of the room to set the cursor for.
  • position (number, required) The latest read message ID
1
2
3
4
5
chatkit.set_read_cursor({
  user_id: user_id,
  room_id: room_id,
  position: 42,
})

Get a Read Cursor

get_read_cursor gets the read cursor for the given user and room. Takes an object with the following properties

  • user_id (string, required) The ID of the user to get the cursor for.
  • room_id (string, required) The ID of the room to get the cursor for.
1
2
3
4
chatkit.get_read_cursor({
  user_id: user_id,
  room_id: room_id,
})

Get All of a User’s Read Cursors

get_read_cursors_for_user gets all of the given user’s read cursors. Takes an object with the following properties

  • user_id (string, required) The ID of the user to get the cursors for.
1
2
3
chatkit.get_read_cursors_for_user({
  user_id: user_id,
})

Get All of the Read Cursors for a Room

get_read_cursors_for_room gets all of the read cursors for the given room. Takes an object with the following properties

  • room_id (string, required) The ID of the room to get the cursors for.
1
2
3
chatkit.get_read_cursors_for_room({
  room_id: room_id,
})

Roles and Permissions

Create a Role With the Room Scope

Create a Role intended for use within the scope of a room identified by its ID.

Usage

create_room_role takes a hash with the following keys:

  • name (string, required): A unique name for the role.
  • permissions (array, required): A list of permissions outlined in the authentication docs.
1
2
3
4
chatkit.create_room_role({
  name: "mycoolroomrole",
  permissions: ["room:join"]
})
Response

No response body is returned.

Create a Role With the Global Scope

Create a Role intended for use globally.

Usage

create_global_role takes a hash with the following keys:

  • name (string, required): A unique name for the role.
  • permissions (array, required): A list of permissions outlined in the authentication docs.
1
2
3
4
chatkit.create_global_role({
  name: "mycoolglobalrole",
  permissions: ["room:join"]
})
Response

No response body is returned.

Delete a Room Scoped Role

Delete a room scoped role.

Usage

delete_room_role takes a hash with the following keys:

  • name (string, required): Role name by which the role is identified.
1
2
3
chatkit.delete_room_role({
  name: "mycoolroomrole"
})
Response

No response body is returned.

Delete a Global Scoped Role

Delete a global scoped role.

Usage

delete_global_role takes a hash with the following keys:

  • name (string, required): Role name by which the role is identified.
1
2
3
chatkit.delete_global_role({
  name: "mycoolglobalrole"
})
Response

No response body is returned.

Assign a Room Scoped Role to a User

Assign a room scoped role to a User for a given room ID.

Usage

assign_room_role_to_user takes a hash with the following keys

  • user_id (string, required): User ID for which to assign the role.
  • name (string, required): Name of the role to be assigned to the user.
  • room_id (string, required): Room ID to which the role is bound.
1
2
3
4
5
chatkit.assign_room_role_to_user({
  name: "mycoolroomrole",
  user_id: "user_id",
  room_id: "234"
})
Response

No response body is returned

Assign a Global Scoped Role a User

Assign a role scoped globally to a User.

Usage

assign_global_role_to_user takes a hash with the following keys:

  • user_id (string, required): User ID for which to assign the role.
  • name (string, required): Name of the role to be assigned to the user.
1
2
3
4
chatkit.assign_global_role_to_user({
  user_id: "user_id",
  name: "mycoolglobalrole"
})
Response

No response body is returned

Remove a Room Scoped Role for a User

Un-assign a room scoped role from a User.

Usage

remove_room_role_for_user takes a hash with the following keys

  • user_id (string, required): User ID to which the role was assigned.
  • room_id (string, required): Room ID of the role.
1
2
3
4
chatkit.remove_room_role_for_user({
  user_id: "user_id",
  name: "mycoolroomrole"
})
Response

No response body is returned.

Remove a Global Scoped Role for a User

Un-assign a global scoped role from a User.

Usage

remove_global_role_for_user takes a hash with the following keys

  • user_id (string, required): User ID to which the role was assigned.
1
2
3
chatkit.remove_global_role_for_user({
  user_id: "user_id"
})
Response

No response body is returned.

List All Roles for an Instance

Fetch all roles created for an instance.

Usage

get_roles does not take any arguments.

1
chatkit.get_roles
Response

An array of JSON objects

1
2
3
4
5
6
7
8
9
10
11
12
[
  {
    "role_name": "mycoolglobalrole",
    "permissions": ["room:join"],
    "scope_name": "global"
  },
  {
    "role_name": "mycoolroomrole",
    "permissions": ["room:update"],
    "scope_name": "room"
  }
]

List Roles for a User

Fetch roles assigned to a user.

Usage

get_user_roles takes a hash with the following keys:

  • user_id (string, required): User ID to which roles are assigned.
1
2
3
chatkit.get_user_roles({
  user_id: "user_id"
})
Response

An array of JSON objects

1
2
3
4
5
6
7
8
9
10
11
[
  {
    "role_name": "mycoolglobalrole",
    "permissions": ["room:join"]
  },
  {
    "role_name": "mycoolroomrole",
    "permissions": ["room:update"],
    "room_id": 234
  }
]

List Permissions Associated With a Room Scoped Role

Fetch the list of permissions assigned to a room scoped role.

Usage

get_permissions_for_room_role takes a hash with the following keys

  • name (string, required): Name of the role with which permissions are associated.
1
2
3
chatkit.get_permissions_for_room_role({
  name: "mycoolroomrole"
})
Response

An Array of permission names

1
["room:update"]

List Permissions Associated With a Global Scoped Role

Fetch the list of permissions assigned to a global role.

Usage

get_permissions_for_global_role takes a hash with the following keys

  • name (string, required): Name of the role with which permissions are associated.
1
2
3
chatkit.get_permissions_for_global_role({
  name: "mycoolglobalrole"
})
Response

An Array of permission names

1
["room:join"]

Update Permissions Associated With a Room Scoped Role

Update the list of permissions assigned to a room scoped role.

Usage

update_permissions_for_room_role takes a hash of the form:

  • name (string, required): Name of the role with which permissions are associated.
  • permissions_to_Add ([]string, optional): The permissions to add to the role.
  • permissions_to_Remove ([]string, optional): The permissions to remove from the role.
1
2
3
4
5
6
chatkit.update_permissions_for_room_role({
  roleName: 'mycoolroomrole',
  permissionsToAdd: ['room:update']
})
  .then(() => console.log('done!'))
  .catch(err => console.error(err))

Update Permissions Associated With a Global Scoped Role

Update the list of permissions assigned to a global role.

Usage

update_permissions_for_global_role takes a hash of the form:

  • name (string, required): Name of the role with which permissions are associated.
  • permissions_to_add ([]string, optional): The permissions to add to the role.
  • permissions_to_remove ([]string, optional): The permissions to remove from the role.
1
2
3
4
5
6
chatkit.update_permissions_for_global_role({
  roleName: 'mycoolglobalrole',
  permissionsToRemove: ['room:update']
})
  .then(() => console.log('done!'))
  .catch(err => console.error(err))

Errors

Errors

Error responses returned by the API take the shape of a Hash which contains details of the error.

1
2
3
4
5
{
  "error": "unprocessable_entity/invalid_json_body",
  "error_description": "Failed to parse request body",
  "error_uri": "https://docs.pusher.com/errors/unprocessable_entity/invalid_json_body"
}

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.