PHP Server SDK

PHP SDK for the Chatkit service.

Setting Up

Installing

You can get the Chatkit PHP SDK via a composer package called pusher-chatkit-server, which you can find on Packagist here.

1
$ composer require pusher/pusher-chatkit-server

Or add to composer.json:

1
2
3
"require": {
    "pusher/pusher-chatkit-server": "^1.0.0"
}

and then run composer update.

Or you can clone or download the library files.

We recommend you use composer.

This library depends on PHP modules for cURL and JSON. See cURL module installation instructions and JSON module installation instructions.

Requiring the SDK

To make use of Chatkit you will also need to use Composer's autoload:

require_once('vendor/autoload.php');

Instantiate the Chatkit Object

Head to your dashbord to find your instance_locator and key and use them to create a new Chatkit\Chatkit instance.

Example

1
2
3
4
$chatkit = new Chatkit\Chatkit([
  'instance_locator' => 'YOUR_INSTANCE_LOCATOR',
  'key' => 'YOUR_KEY'
]);

Authentication

Authenticate a User

To authenticate a user (a Chatkit client) use the authenticate function.

You need to provide an associative array that has a user_id key with a string value.

Example

1
$chatkit->authenticate([ 'user_id' => 'ham' ]);

It returns an associative array that is structured like this:

1
2
3
4
5
6
7
8
9
10
11
[
  'status': 200,
  'headers': [
    'Some-Header': 'some-value'
  ],
  'body': [
    'access_token' => 'an.access.token',
    'token_type' => 'bearer',
    'expires_in' => 86400
  ]
]

where:

  • status is the suggested HTTP response status code,
  • headers are the suggested response headers,
  • body holds the token payload.

Users

Create a User

Create a new User to use with the Chatkit service.

Usage

The createUser method takes an array 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
2
3
4
$chatkit->createUser([
  'id' => 'ham',
  'name' => 'Hamilton Chapman'
]);

Or with an avatar_url and custom_data:

1
2
3
4
5
6
7
8
$chatkit->createUser([
  'id' => 'ham',
  'name' => 'Hamilton Chapman',
  'avatar_url' => 'https://placekitten.com/200/300',
  'custom_data' => [
    'my_custom_key' => 'some data'
  ]
]);
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 createUsers method. It takes an array with the following keys:

  • users (array, required): An array of user arrays (see above)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
chatkit.createUsers([
  '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 user arrays 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 updateUser method updates a previously created User. Takes an array 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->updateUser({
  'id' => 'some_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 deleteUser method takes an array with the following keys:

  • id (string, required): Unique ID to match the user to be deleted.
1
$chatkit->deleteUser([ 'id' => 'some_id' ]);
Response

No response body is returned on successful deletion.

Get a User

Use the getUser method to get the details of a user with a given ID. Takes an array with the following keys:

  • id (string, required): Unique ID to match the user to be deleted.
1
$chatkit->getUser([ 'id' => 'some_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 getUsers function takes no arguments.

1
$chatkit->getUsers();
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 getUsersByID function takes an array with the following keys:

  • user_ids (array, required): an array of user IDs (strings)
1
2
3
$chatkit->getUsersByID([
  '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 createRoom 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 (assoc array, optional): A list of key value pairs containing custom data to attach to the room.
1
2
3
4
5
6
7
$chatkit->createRoom([
  'creator_id' => 'alice',
  'name' => 'new name',
  'user_ids' => ['bob'],
  'private' => true,
  'custom_data' => ['foo' => 'bar']
]);

Update a Room

The updateRoom method updates an existing room. Takes an array 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 (assoc array, optional): A list of key value pairs containing custom data to attach to the room.
1
2
3
4
5
6
$chatkit->updateRoom([
  'id' => '123',
  'name' => 'new name',
  'private' => true,
  'custom_data' => ['foo' => 'bar']
]);

Delete a Room

The deleteRoom method irreversibly deletes a room. Takes an array with the following keys:

  • id (string, required): The ID of the room to be deleted.
1
$chatkit->deleteRoom([ 'id' => '123' ]);

Get a Room

The getRoom function takes an array of the form:

  • id (String, required): ID of the room to fetch
1
$chatkit->getRoom([ 'id' => '123' ]);

Get Rooms

getRooms fetches rooms, ordered by ID, in pages of 100 at a time. Takes an array 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->getRooms([]);

Get User Joinable Rooms

The getUserJoinableRooms function takes an array of the form:

  • id (String, required): ID of the user for whom rooms should be retrieved
1
$chatkit->getUserJoinableRooms([ 'id' => 'alice' ]);
Response

An array of arrays

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 getUserRooms function takes an array of the form:

  • id (String, required): ID of the user for whom rooms should be retrieved
1
$chatkit->getUserRooms([ 'id' => 'alice' ]);
Response

An array of arrays

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

addUsersToRoom add users as members of a room. Takes an array with the following keys

  • room_id (string, required) The room to add users to
  • user_ids ([]string, required) The users to add
1
2
3
4
$chatkit->addUsersToRoom([
  'user_ids' => ['alice', 'bob'],
  'room_id' => "1001'
]);

Remove Users From a Room

removeUsersFromRoom removes users with the given ID from a room. Takes an array with the following keys

  • room_id (string, required) The room to remove users from
  • user_ids ([]string, required) The users to remove
1
2
3
4
$chatkit->removeUsersFromRoom([
  'user_ids' => ['sarah'],
  'room_id' => 1001
]);

Messages

Send a Message

sendMessage publishes a message to a room as the given user. Takes an array 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
  • attachment (array, optional): An associative array with the following keys:
    • resource_link (string, required): A link to the attachment file.
    • type (string, required): The type of the file being attached. Currently must be one of image, video, audio or file.
1
2
3
4
5
$chatkit->sendMessage([
  'sender_id' => 'sarah',
  'room_id' => 1001,
  'text' => 'This is a wonderful message.'
]);

Here's an example of sending a message with an attachment:

1
2
3
4
5
6
7
8
9
$chatkit->sendMessage([
  'sender_id' => 'sarah',
  'room_id' => 1001,
  'text' => 'This is a message with an attachment.',
  'attachment' => [
    'resource_link' => 'https://placekitten.com/200/300',
    'type' => 'image'
  ]
]);

Get Messages From a Room

getRoomMessages fetches the messages from a room. Messages are returned in pages of at most 100 at a time. Takes an array 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
$chatkit->getRoomMessages([
  'room_id' => '1001'
]);

You can also customise the messages to be returned based on your needs:

1
2
3
4
5
6
$chatkit->getRoomMessages([
  'room_id' => '1001',
  'initial_id' => 123,
  'limit' => 100,
  'direction' => 'older'
]);

Delete a Message

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

1
2
3
$chatkit->delete_message([
  id: 45678
]);

Read Cursors

Set a Read Cursor

setReadCursor sets the read cursor for the given user and room to the given position (the latest read message ID). Takes an array 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->setReadCursor([
  'user_id' => 'sarah',
  'room_id' => '1001',
  'position' => 12345
]);

Get a Read Cursor

getReadCursor gets the read cursor for the given user and room. Takes an array 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->getReadCursor([
  'user_id' => 'ham',
  'room_id' => '123'
]);

Get All of a User’s Read Cursors

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

  • user_id (string, required) The ID of the user to get the cursors for.
1
2
3
$chatkit->getReadCursorsForUser([
  'user_id' => 'ham'
]);

Get All of the Read Cursors for a Room

getReadCursorsForRoom gets all of the read cursors for the given room. Takes an array with the following properties

  • room_id (string, required) The ID of the room to get the cursors for.
1
2
3
$chatkit->getReadCursorsForRoom([
  'room_id' => '123'
]);

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

createRoomRole takes an array 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->createRoomRole([
  'name' => 'admin',
  'permissions' => ['room:join']
]);
Response

No response body is returned.

Create a Role With the Global Scope

Create a Role intended for use globally.

Usage

createGlobalRole takes an array 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->createGlobalRole([
  'name' => 'admin',
  'permissions' => ['room:join']
]);
Response

No response body is returned.

Delete a Room Scoped Role

Delete a room scoped role.

Usage

deleteRoomRole takes an array with the following keys:

  • name (string, required): Role name by which the role is identified.
1
2
3
$chatkit->deleteRoomRole([
  'name' => 'admin'
]);
Response

No response body is returned.

Delete a Global Scoped Role

Delete a global scoped role.

Usage

deleteGlobalRole takes an array with the following keys:

  • name (string, required): Role name by which the role is identified.
1
2
3
$chatkit->deleteGlobalRole([
  'name' => 'admin'
]);
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

assignRoomRoleToUser takes an array 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 (integer, required): Room ID to which the role is bound.
1
2
3
4
$chatkit->assignRoomRoleToUser([
  'user_id' => 'ham',
  'name' => 'admin'
]);
Response

No response body is returned

Assign a Global Scoped Role a User

Assign a role scoped globally to a User.

Usage

assignGlobalRoleToUser takes an array 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->assignGlobalRoleToUser([
  'user_id' => 'ham',
  'name' => 'admin'
]);
Response

No response body is returned

Remove a Room Scoped Role for a User

Un-assign a room scoped role from a User.

Usage

removeRoomRoleForUser takes an array 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->removeRoomRoleForUser([
  'user_id' => 'ham',
  'room_id' => '123'
]);
Response

No response body is returned.

Remove a Global Scoped Role for a User

Un-assign a global scoped role from a User.

Usage

removeGlobalRoleForUser takes an array with the following keys

  • user_id (string, required): User ID to which the role was assigned.
1
2
3
$chatkit->removeGlobalRoleForUser([
  'user_id' => 'ham'
]);
Response

No response body is returned.

List All Roles for an Instance

Fetch all roles created for an instance.

Usage

getRoles does not take any arguments.

1
$chatkit->getRoles();
Response

An array of arrays

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

getUserRoles takes an array with the following keys:

  • user_id (string, required): User ID to which roles are assigned.
1
2
3
$chatkit->getUserRoles([
  'user_id' => 'ham'
]);
Response

An array of arrays

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

getPermissionsForRoomRole takes an array with the following keys

  • name (string, required): Name of the role with which permissions are associated.
1
2
3
$chatkit->getPermissionsForRoomRole([
  '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

getPermissionsForGlobalRole takes an array with the following keys

  • name (string, required): Name of the role with which permissions are associated.
1
2
3
$chatkit->getPermissionsForGlobalRole([
  '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

updatePermissionsForRoomRole takes an array 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
$chatkit->updatePermissionsForRoomRole([
  'name' => 'mycoolroomrole',
  'permissions_to_add' => ['room:update']
]);

Update Permissions Associated With a Global Scoped Role

Update the list of permissions assigned to a global role.

Usage

updatePermissionsForGlobalRole takes an array 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
$chatkit->updatePermissionsForGlobalRole([
  'name' => 'mycoolglobalrole',
  'permissions_to_remove' => ['room:update']
]);

Errors

Errors

Error responses returned by the API take the shape of an array 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.