Comment on page

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 imporatnly it should be unique and always reference a entity from your system.
In order to proof the autenticity 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,
      },
    }
  );
};
4.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.
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.
​
​

Channels - Previous

Web V2

Next - Channels

Webhook channel

Last modified 15d ago

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

command	necessary info
`Chatlayer.login()`	(externalId: string, jwt: string)
`Chatlayer.logout()`	(externalId: string, jwt: string)

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	-

Field	Type	Description
agent	`Agent`	Represents an agent that is involved in a conversation.

Technical documentation

Initializing the widget

Options

Custom colors

Customize text

Opening and closing your widget

User authentication

Events sent by Chatlayer

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

Changing the language

`Chatlayer.setLanguage(language)`

`Chatlayer.language`

Setting Session Data

`Chatlayer.setSessionData(SessionData)`

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

Technical documentation

Initializing the widget

Options

Custom colors

Customize text

Opening and closing your widget

User authentication

Events sent by Chatlayer

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

Changing the language

Chatlayer.setLanguage(language)

Chatlayer.language

Setting Session Data

Chatlayer.setSessionData(SessionData)

​

​

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

`Chatlayer.setLanguage(language)`

`Chatlayer.language`

`Chatlayer.setSessionData(SessionData)`