Technical documentation

The article below will deepdive in technical possibilities of our new widget.

Initializing the widget

'Chatlayer.init(options: Options)'

Initializes the widget using the specified options . This method returns a promise like object.

Except for the on and off methods, the rest of the documented methods below needs to be called after init is completed

Options

Option

Optional

Default Value

Type

Description

channelId

No

-

string

The ID of the Chatlayer channel

title

Yes

-

string

The title to show in the header widget

subtitle

No

-

string

An optional subtitle to show below the title

position

No

right

right | left

The position of the widget. Possible values are left or right

buttonWidth

No

58

number

The width of the widget button

buttonHeight

No

58

number

The height of the widget button

customColors

Yes

-

CustomColors

Override the colors of the widget

headerIconUrl

Yes

-

url

URL of a public image to be shown in the header

region

Yes

eu-west1-gcp

string

The region of your Chatlayer account

customText

Yes

-

CustomText

Override the text of the different widget UI elements

enableTextInput

No

true

boolean

Set it to false to hide the text input, allowing users to interact only via buttons and quick replies

enableAudioInput

No

true

boolean

Set it to false to hide the audio recording button, preventing the users from sending audio messages via the widget

enableFileUpload

No

true

boolean

Set it to false to hidde the file upload button, preventing the users sending files via the widget. File upload request will still work

enableSoundNotifications

No

true

boolean

Control whether the user will receive sound notifications every time a new message arrives. It can be changed by the user as well from the settings

Custom colors

CustomColors

Option

Optional

Default Value

Description

brandColor

Yes

007171

This color will be used in the messenger header and the launcher. It must be a 3 or 6-character hexadecimal color.

conversationColor

Yes

007171

This color will be used for customer messages, quick replies and actions in the footer.

actionColor

Yes

007171

This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color.

Customize text

CustomText

Option

Optional

Default Value

Description

inputPlaceholder

Yes

Send a message

Placeholder text shown in the message input field

botDisplayName

Yes

Bot

This display name of the bot. Use an empty string to hide it.

agentDisplayName

Yes

Agent

This display name of the agent. Use an empty string to hide it.

To provide different values for different languages, add a subfield with the language code.

Opening and closing your widget

command

action

Chatlayer.open()

Opens the widget

Chatlayer.close()

Closes the widget

Chatlayer.toggle()

Toggles the widget

Chatlayer.isOpen

shows whether the widget is open

User authentication

When the widget is initialized an anonymous customer is created automatically. This customer can send messages to the bot. In some scenarios, you want to federate the customer identity with the ones of your website or application. This is done using the externalId. This field identifies the user on your system. It can be an email address, a username, a uuid or any other user id on your database. Most importantly it should be unique and always reference a entity from your system.

In order to proof the authenticity of the user, we require a signed JWT token that validates your ownership of the widget. Otherwise anyone can impersonate your users.

In order to create a signed JWT token:

  1. Login into your Chatlayer account and create an access token at https://app.chatlayer.ai/settings/api-access/tokens

  2. The token will have the form of [keyId]:[keySecret]. Notice there is : separating the two parts of the token.

  3. Implement server side code to sign new JWTs using thekeyId and keySecret. The JWT header must specify the key ID in the kid field. The JWT payload must include a channel_id claim in the jwt payload and a sub claim wich should be set to your external user id.

A node.js sample is provided below using jsonwebtoken >= 6.0.0

var jwt = require('jsonwebtoken');
// given token 647f1ecd48f7f8aa3abe17fd:5e39a6051B53e7Cf92CF0dB9F2Bd5Eb0
var KEY_ID = '647f1ecd48f7f8aa3abe17fd';
var KEY_SECRET = '5e39a6051B53e7Cf92CF0dB9F2Bd5Eb0';
var CHANNEL_ID = 'liiq8woe:647f1f0910f7d21246e1df75';

var signJwt = function (userId) {
  return jwt.sign(
    {
      channel_id: CHANNEL_ID,
      sub: userId,
    },
    KEY_SECRET,
    {
      header: {
        alg: 'HS256',
        typ: 'JWT',
        kid: KEY_ID,
      },
    }
  );
};
  1. From your website call

Chatlayer.login(externalUserId, signedJWT).then(() => {
  // user logged in
  }, err => {
// error occurred
  })`

command

necessary info

Chatlayer.login()

(externalId: string, jwt: string)

Chatlayer.logout()

(externalId: string, jwt: string)

Events sent by Chatlayer

Chatlayer.on(event, (arg1, arg2) => ...)

event

description

arg1

widget:opened

The widget was opened

-

widget:closed

The widget was closed

-

widget:custom_action

When a custom action button was clicked

-

message:received

A message was received

-

message:sent

A message was send by the user

-

event:received

An event was received

EventPayload

init

The widget was initialized

-

destroy

The widget was destroyed

-

EventPayload

Field

Type

Description

generic_event

GenericEvent

A generic event

agent_joined_event

AgentJoinedEvent

When an agent joins the conversation

agent_left_event

AgentLeftEvent

When an agent leaves the conversation

GenericEvent

Field

Type

Description

payload

JSON

Arbitrary data set to the event. A valid JSON object.

Note that you can use the JSON builder to send generic events from your user's session to the site you've hosted the widget on.

AgentJoinedEvent

Field

Type

Description

agent

Agent

Represents an agent that is involved in a conversation.

Agent

Field

Type

Description

display_name

string

Agent's display name

picture_url

string

The Agent's picture url.

type

AgentType

Agent's classification can be UNKNOWN_AGENT_TYPE, HUMAN or BOT.

Use Chatlayer.off(event, (arg1, arg2) => ...)to unsubscribe from these events

Changing the language

Chatlayer.setLanguage(language)

Set the current language. Only languages on the list of languages supported by your bot will be accepted.

Chatlayer.language

The current language of the widget

Setting Session Data

If you want to transfer data from your website to the chatbot, you can add that data to the chatlayer function after initializing the widget. All data will be put in the Chatlayer session. This data can then be used to customize the chatbot flow, based on actual website data.

Chatlayer.setSessionData(SessionData)

Sets extra data in the conversation session and returns a promise

Example

Chatlayer.setSessionData({
  Product: 'iPhone XS',
  });
// or
Chatlayer.setSessionData('Product', 'iPhone XS');

The example above shows how you can set the variable Product in the Chatlayer session. It will get the value iPhone XS in this case.

Last updated