Comment on page
Technical documentation
The article below will deepdive in technical possibilities of our new 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 completedOption | 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 |
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. |
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.
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 |
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 the
keyId
andkeySecret
. The JWT header must specify the key ID in thekid
field. The JWT payload must include achannel_id
claim in the jwt payload and asub
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) |
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 eventsSet the current language. Only languages on the list of languages supported by your bot will be accepted.
The current language of the widget
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.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 modified 15d ago