Embedding of the Web Client

Notes

Branding

  • 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" />

Usage

Container

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.

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

Initialize

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 - service URL.
  • staticBaseUrl - URL to web client files.

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

<script>
(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://uebergrape.chatgrape.com",
  staticBaseUrl: "https://ug-cdn.com/static/",
  onReady: function() {
    console.log("Grape Client initialized")
  }
});
</script>

JavaScript API

Suspend

grapeClient.suspend()

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

Resume

grapeClient.resume()

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')

Options

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

Show and hide UI components

grapeClient.show(component) grapeClient.hide(component)

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

grapeClient.setOpenFileDialogHandler(handler)

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

grapeClient.authStatus

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.

Events

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.
})