Chat sidebar

The app is displayed in the panel on the right side of the chat window that opens after an agent responds to or initiates a chat with a visitor.

Example manifest

"location": {
  "chat": {
    "chat_sidebar": "assets/iframe.html"
  }
},

In addition to the objects available in all locations, the following objects and additional actions are available in this location:

• Agents object
• Chat object
• Visitor object

Events

In addition to the core events, the following events are available to apps in the chat sidebar:

• channel.chat.start
• channel.chat.end
• channel.department.changed
• channel.message.received
• channel.message.sent
• channel.textarea.changed
• channel.ticket.created
• channel.window.inbackground
• channel.window.infocus
• visitor.display_name.changed
• visitor.email.changed
• visitor.phone.changed
• visitor.notes.changed

channel.chat.start

Fires when a chat starts.

Example:

client.on('channel.chat.start', (evt) => {
  console.log(evt);
  // example:
  // - When channel information is not available, for example starting a new chat
  // {}
  // - When channel information is available
  // {
  //   "channel": "#supportchat:1-12345",
  //   "display_name": "Visitor 123",
  //   "nick": "visitor:1-12345",
  //   "ts": 1582100450713
  // }
});

channel.chat.end

Fires when a chat ends.

Example:

client.on('channel.chat.end', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "chat": [
  //     {"channel": "#supportchat:1-12345", "display_name": "Visitor 123", "nick": "visitor:1-12345", "ts": 1582100450712},
  //     {"channel": "#supportchat:1-12345", "display_name": "Visitor 123", "message": "hello", "nick": "visitor:1-12345", "ts": 1582100450713},
  //     {"channel": "#supportchat:1-12345", "display_name": "John", "nick": "agent:456", "ts": 1582100450733},
  //     {"channel": "#supportchat:1-12345", "display_name": "John", "message": "hi", "nick": "agent:456", "ts": 1582100450921},
  //     {"channel": "#supportchat:1-12345", "display_name": "Visitor 123", "nick": "visitor:1-12345", "ts": 1582100781395},
  //     ...
  //   ]
  // }
});

channel.department.changed

Fires when a chat changes department.

Example:

client.on('channel.department.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "id": 12345,
  //   "name": "test department",
  //   "event_name": "channel.department.changed"
  // }
});

channel.message.received

Fires when the agent receives a message.

Example:

client.on('channel.message.received', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "channel": "#supportchat:1-12345",
  //   "display_name": "Visitor 123",
  //   "message": "hello",
  //   "nick": "visitor:1-12345",
  //   "ts": 1582100671235
  // }
});

channel.message.sent

Fires when the agent sends a message.

Example:

client.on('channel.message.sent', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "channel": "#supportchat:1-12345",
  //   "display_name": "John",
  //   "message": "hi",
  //   "nick": "agent:456",
  //   "ts": 1582100450921
  // }
});

channel.textarea.changed

Fires when the input textarea changes.

Example:

client.on('channel.textarea.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "textarea_value": "hi"
  // }
});

channel.ticket.created

Fires when a ticket is created.

Example:

client.on('channel.ticket.created', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "ticket_id": 8266
  // }
});

channel.window.inbackground

Fires when Chat window is in background.

Example:

client.on('channel.window.inbackground', (evt) => {
  console.log(evt);
  // example:
  // {}
});

channel.window.infocus

Fires when Chat window is in focus.

Example:

client.on('channel.window.infocus', (evt) => {
  console.log(evt);
  // example:
  // {}
});

visitor.display_name.changed

Fires when visitor's display_name changes.

Example:

client.on('visitor.display_name.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "event_name": "visitor.display_name.changed",
  //   "value": "Visitor 456"
  // }
});

visitor.email.changed

Fires when visitor's email changes.

Example:

client.on('visitor.email.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "event_name": "visitor.email.changed",
  //   "value": "[email protected]"
  // }
});

visitor.phone.changed

Fires when visitor's phone changes.

Example:

client.on('visitor.phone.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "event_name": "visitor.phone.changed",
  //   "value": "123456789"
  // }
});

visitor.notes.changed

Fires when visitor's notes change.

Example:

client.on('visitor.notes.changed', (evt) => {
  console.log(evt);
  // example:
  // {
  //   "event_name": "visitor.notes.changed",
  //   "value": "new notes"
  // }
});

Agents object

Represents all the agents that are part of the chat currently being viewed.

Properties

• agents

agents

Gets the information of all the agents that are part of the chat.

get

client.get('agents');

returns

{
  "agents": {
    <agent_id> : {
      User object properties
    },
    ...
  }
}

See CurrentUser Object properties.

Chat object

Represents the chat currently being viewed.

chat

Retrieves the chat object, with all its properties.

get

client.get('chat')

returns

{
  "chat": {
    // Chat object properties
  }
}

Properties

• chat.id
• chat.department
• chat.messages
• chat.tags

Actions

• chat.tags.add
• chat.tags.remove
• chat.joinChat
• chat.sendChat
• chat.postToChatTextArea

chat.id

Retrieves the chat's id. Returns null if the chat has not started yet.

get

client.get('chat.id');

returns

{
  "chat.id": string
}

chat.department

Retrieves the chat's department. Returns null if the chat belongs to no department.

get

client.get('chat.department');

returns

{
  "chat.department": {
    "id": integer,
    "name": string
  }
}

chat.messages

Gets all the messages that have been sent in the chat.

get

client.get('chat.messages');

returns

{
  "chat.messages": [
    {
      "channel": string,
      "nick": "visitor:<visitor id>" or "agent:<agent id>",
      "display_name": string,
      "message": string,
      "ts": integer,
      "msg_lang_code": string
    }
    ...
  ]
}

chat.tags

Gets the existing chat tags added by an agent.

To get the tags set by chat triggers, use visitor.tags.

get

client.get('chat.tags');

returns

{
  "chat.tags": Array of strings
}

chat.tags.add

Adds a tag to the existing chat tags.

invoke

client.invoke('chat.tags.add', value);

arguments

• String of chat tag to be added.

notes

• This action is permitted only if the agent with the app loaded is already part of the chat.
• The tag to be added must be a part of the predefined tag list.

chat.tags.remove

Removes a tag from the existing chat tags.

invoke

client.invoke('chat.tags.remove', value);

arguments

• String of chat tag to be removed.

notes

This action is permitted only if the agent with the app loaded is already part of the chat.

chat.joinChat

Allows the app to force the agent to join the chat.

invoke

client.invoke('chat.joinChat');

chat.sendChat

Allows the app to send a message to the chat on behalf of the agent viewing the chat.

invoke

client.invoke('chat.sendChat', value);

arguments

• String of the message to be sent on the chat.

notes

This action is permitted only if the viewing agent is already part of the chat.

chat.postToChatTextArea

Allows the app to set a predefined message in the chat's own text area. This message is not sent on the chat unless the agent clicks the send button on the chat.

invoke

client.invoke('chat.postToChatTextArea', value);

arguments

• String of the message to be shown on the chat's text area.

notes

• This action is permitted only if the viewing agent is already part of the chat.
• This action overwrites the content of the text area with the message.

Visitor Object

Represents the visitor in the chat currently being viewed.

visitor

Retrieves the visitor object, with all its properties.

get

client.get('visitor')

set

client.set({
  'visitor.name': value1,
  'visitor.email': value2,
  'visitor.phone': value3,
  'visitor.notes': value4
})

returns

{
  "visitor": {
    // Visitor object properties
  }
}

Properties

• visitor.id
• visitor.externalId
• visitor.name
• visitor.displayName
• visitor.email
• visitor.phone
• visitor.notes
• visitor.tags
• visitor.pastChats
• visitor.pastVisits
• visitor.pageUrl
• visitor.browser
• visitor.platform
• visitor.ip
• visitor.device
• visitor.location
• visitor.userAgent

visitor.id

Gets the id of the visitor in the chat.

get

client.get('visitor.id');

returns

{
  "visitor.id": string
}

visitor.externalId

Gets the external id of an authenticated visitor in the chat.

get

client.get('visitor.externalId');

returns

{
  "visitor.externalId": string
}

visitor.name

Gets or sets the name of the visitor in the chat.

get

client.get('visitor.name');

returns

{
  "visitor.name": string
}

set

client.set('visitor.name', value);

arguments

• String of the name to be set for the visitor.

visitor.displayName

Similar to the visitor.name API, it can be used to get or set the name of the visitor in the chat.

get

client.get('visitor.displayName');

returns

{
  "visitor.displayName": string
}

set

client.set('visitor.displayName', value);

arguments

• String of the name to be set for the visitor.

visitor.email

Gets or sets the email of the visitor in the chat.

get

client.get('visitor.email');

returns

{
  "visitor.email": string
}

set

client.set('visitor.email', value);

arguments

• String of the email to be set for the visitor.

visitor.phone

Gets or sets the phone number of the visitor in the chat.

get

client.get('visitor.phone');

returns

{
  "visitor.phone": string
}

set

client.set('visitor.phone', value);

arguments

• String of the phone number to be set for the visitor.

visitor.notes

Gets or sets the notes that have been written for the visitor in the chat.

get

client.get('visitor.notes');

returns

{
  "visitor.notes": string
}

set

client.set('visitor.notes', value);

arguments

• String of the notes to be set for the visitor.

visitor.tags

Gets the tags assigned to the visitor, including those set by a chat trigger action.

get

client.get('visitor.tags');

returns

{
  "visitor.tags": Array of strings
}

visitor.pastChats

Gets the visitor's past chats.

get

client.get('visitor.pastChats');

returns

{
  "visitor.pastChats": Array of condensed Chat objects
}

See Chat Object properties.

visitor.pastVisits

Gets the pages previously visited by the visitor.

get

client.get('visitor.pastVisits');

returns

{
  "visitor.pastVisits": [
    {
      "timestamp": integer,
      "page_title": string,
      "page_url": string
    }
    ...
  ]
}

visitor.pageUrl

Gets the url of the page that the visitor is currently viewing on the site.

get

client.get('visitor.pageUrl');

returns

{
  "visitor.pageUrl": string
}

visitor.browser

Gets the browser being used by the visitor. Some of the possible values are Chrome, Firefox, Safari, etc.

get

client.get('visitor.browser');

returns

{
  "visitor.browser": string
}

visitor.platform

Gets the platform being used by the visitor. Possible values returned could be Mac OS, Windows, etc.

get

client.get('visitor.platform');

returns

{
  "visitor.platform": string
}

visitor.ip

Gets the ip of the visitor.

get

client.get('visitor.ip');

returns

{
  "visitor.ip": string
}

visitor.device

Gets the device being used by the visitor. Possible values are either desktop or mobile.

get

client.get('visitor.device');

returns

{
  "visitor.device": string
}

visitor.location

Gets the full name of the country in which the visitor is currently online.

get

client.get('visitor.location');

returns

{
  "visitor.location": string
}

visitor.userAgent

Gets the user-agent of the visitor.

get

client.get('visitor.userAgent');

returns

{
  "visitor.userAgent": string
}