Embedding of the Web Client


CORS Exception

The embedded chat probably runs on a different domain than Grape. By default, the same-origin policy forbids requests to different domains. To allow this, a server can set appropriate CORS headers.

A list of allowed hostnames can be configured on the Grape server. If a hostname is in the exceptions list, the server will answer with a Access-Control-Allow-Origin header containing this hostname.

The exceptions have to be configured on the server and a restart is required.

If you don’t want to wait for the Grape team or for your server admin to do this or if you don’t know which hostnames you will be using, you can use a plugin in Google Chrome to override the header to allow all Origins. This plugin should only be used for development and poses security risks. It is not maintained by Grape.


  • Grape client doesn’t offer any styling customizations yet. Please restrain from overriding any look and feel of the client and use it “as is”.

  • Do not integrate any custom functionality into the Grape UI directly. Use the space outside the container or use modals.

Browsers support

Grape supports only latest browsers: IE11+, latest Chrome, latest Firefox, latest Safari.

We also support IE10 document mode in IE11. To turn it on, you can use meta tag:

<meta http-equiv="X-UA-Compatible" content="IE=10" />



In order to know where to render the client, you need to provide a div in the document. Also you need to make sure this div has a desired size. Client will adapt to the size of your container.

  <div id="grape-client"></div>


All options are required:

  • container - selector string for insertion container, any valid CSS selector.

  • channelId - channel id, a number.

  • orgId - organization id, a number.

  • serviceUrl - your Grape server’s URL.

  • staticBaseUrl - URL to the web client files.

  • onReady - will be executed when script loaded

  • onRender - will be executed when history loaded

  • onPin - will be executed when some messages pinned

  • onUnpin - will be executed when some messages unpinned

Use the code below in order to load the chat. Modify the options based on your setup.

(function(a){var b=document.createElement("script");b.async=1;b.src=a.staticBaseUrl+"app/embedded.js";b.onload=function(){grapeClient.embed(a);if(a.onReady)a.onReady()};document.head.appendChild(b)})({
  container: "#grape-client",
  channelId: 632,
  orgId: 1,
  serviceUrl: "https://chatgrape.com",
  staticBaseUrl: "https://ug-cdn.com/static/",
  onReady: function() {
    console.log("Grape Client initialized")
  onRender: function() {
    grapeClient.setChannel(9687, 'c2a4a15c2f7e11e9a0b60242c0a83003')
    console.log('App rendered')
  onPin: function() {
    console.log('Message just pinned!')
  onUnpin: function() {
    console.log('Message just unpinned!')

For developing and testing, you can also try the latest (beta) web client version. Use this serviceUrl: https://unpkg.com/grape-web-client/dist/.

JavaScript API



This method will put the chat into a suspend mode, where no connection to the server will be maintained.



This method will reactivate the client after it was in a suspend mode.

Search messages

grapeClient.searchMessages(query[, options])

Opens a search UI for messages and displays results for a given query. Can be called multiple times while user is typing.

grapeClient.searchMessages('my search')


  currentChannelOnly: {
    show: true,
    status: false
  searchActivities: {
    show: true,
    status: false

Change channel

grapeClient.setChannel(channelId[, messageId])

This method will change channel for client.

grapeClient.setChannel(1, 'c96422a2e9a911e899060242ac190005')

Client version


This variable contain current client version.


Show and hide UI components

grapeClient.show(component[, options]) grapeClient.hide(component[, options])

Possible component values: “mentions”, “labeledMessages”, “search”.

grapeClient.show('mentions') // Show mentions
grapeClient.hide('mentions') // Hide mentions

Mentions options

  showRoomMentions: {
    show: true,
    status: false

Labeled messages options

  currentChannelOnly: {
    show: true,
    status: false

Custom File Upload Dialog


You can create your custom file upload functionality by defining a handler. Handler will be invoked if defined instead of the default upload UI, when upload button is clicked.

grapeClient.setOpenFileDialogHandler(() => {
  alert('Upload button was clicked')

Authorization status


Current authorization status is always defined in grapeClient.authStatus property. Possible values are “authorized” and “unauthorized”.

If you want to react to auth status change, see in events section.


Emitter API

Object grapeClient is an event emitter.

Subscribing any event: grapeClient.on(event, handler).

Subscribing any event once: grapeClient.once(event, handler).

Unsubscribing all events: grapeClient.off().

Unsubscribing specific event: grapeClient.off(event).

Unsubscribing specific event from a specific handler: grapeClient.off(event, handler).

Event hide

If a component was closed from inside, you may want to listen to hide event.

grapeClient.on('hide', () => {
  // Your reaction.

Event authChange

Use this event in order to react to auth status change for e.g. when user looses the session.

grapeClient.on('authChange', (authStatus) => {
  // Your reaction.



Modern browsers no longer allow notification permissions to be requested from a cross-origin iframe. To fix this, the parent window must request notification permissions with requestPermission

Data for notifications is sent via postMessage by two events depending on notification status and type: grapeClient.updateNotification and grapeClient.createNotification. The data attribute’s structure is the same for both events:

  type: 'grapeClient.updateNotification',
  payload: {
    args: {

Grape provides two helper functions for listening and handling notification: createNotification and updateNotification from grape-web.


import { createNotification, updateNotification } from 'grape-web/lib/x-platform'

window.addEventListener("message", (event) => {
  // Check if we can trust message sender
  if (event.origin !== "http://example.com:8080") return;

  switch (event.data.type) {
    case 'grapeClient.createNotification':
      const { args: { properties, callbacks, params }} = event.data.payload;
      createNotification({ properties, callbacks, params });
    case `grapeClient.updateNotification`:
      const { type, props, nextProps } = event.data.payload;
      updateNotification({ type }, this.props, nextProps);