Customizing Push Notifications

Chatkit can be configured to send push notifications to your users when they miss an incoming message. This guide covers how you can customize the notifications sent to your users.

Built-in Push Notification behavior

Push notifications are only sent to inactive users in private rooms

Group Chat

If a room contains more than two people, notifications will use the room name as the title and the Authors name prepended to the message content in the body:

1-to-1 Chat

If a private room contains exactly two people, this is considered a 1-to-1 chat. The message author’s name will be used as the notification title and the message content will be used in the body:

Media-only messages

If the incoming message does not contain any text parts, an emoji icon will be used to represent the attached media:

Overriding the Notification Title

For some use cases, it can be useful to set the notification title to a value specific to your application. For example, in a support application it would be more useful to have the push notification appear to come from “Acme inc. Support” rather than the username of the support agent:

Custom notification titles can contain any valid UTF-8 string

Creating a room with a push notification title override

You can override Chatkit push notification titles for a given room by setting the title override property for the room when it is created:

SERVER-SIDE

  • PHP
  • Go
  • JavaScript
  • Ruby

PHP

1
2
3
4
5
6
7
$chatkit->createRoom([
  'creator_id' => 'alice',
  'name' => 'new name',
  'user_ids' => ['bob'],
  'private' => true,
  'push_notification_title_override' => '<CUSTOM_TITLE_GOES_HERE>'
]);

CLIENT-SIDE

  • JavaScript

Web

1
2
3
4
5
6
7
8
9
10
11
12
currentUser.createRoom({
  id: '#general',
  name: 'General',
  private: true,
  addUserIds: ['craig', 'kate'],
  pushNotificationTitleOverride: '<CUSTOM_TITLE_GOES_HERE>',
}).then(room => {
  console.log('Room created')
})
.catch(err => {
  console.log('Error creating room', err)
})

Updating the push notification title override on a room

You can modify the override for Chatkit push notification titles for a given room by using the update room method:

SERVER-SIDE

  • PHP
  • Go
  • JavaScript
  • Ruby

PHP

1
2
3
4
$chatkit->updateRoom([
  'id' => '123',
  'push_notification_title_override' => '<NEW_TITLE_GOES_HERE>'
]);

CLIENT-SIDE

  • JavaScript

Web

1
2
3
4
5
6
7
8
9
10
currentUser.updateRoom({
  roomId: someRoomID,
  pushNotificationTitleOverride: '<NEW_TITLE_GOES_HERE>',
})
  .then(() => {
    console.log('Updated room')
  })
  .catch(err => {
    console.log('Error updating room', err)
  })

Removing a push notification title override from a room

You can remove the override for Chatkit push notification titles for a given room by using the update room method to set the notification title override field tonull:

SERVER-SIDE

  • PHP
  • Go
  • JavaScript
  • Ruby

PHP

1
2
3
4
$chatkit->updateRoom([
  'id' => '123',
  'push_notification_title_override' => NULL
]);

CLIENT-SIDE

  • JavaScript

Web

1
2
3
4
5
6
7
8
9
10
currentUser.updateRoom({
  roomId: someRoomID,
  pushNotificationTitleOverride: null,
})
  .then(() => {
    console.log('Updated room')
  })
  .catch(err => {
    console.log('Error updating room', err)
  })