Action Buttons and Links

Action buttons and action links let you execute custom code in your chat. You can display them in two ways:

  • By adding special formatting to your chat messages
  • By adding them to your components in the Theme Editor

Actions in chat messages

To add an action to your message, use this syntax:

  • For action buttons:
    <actionbutton:myAction|I am an action button!>
  • For action links:
    <actionlink:myAction|I am an action link!>

Clicking on either one of these will emit a Custom Message Action for the action myAction:

chatbox.onCustomMessageAction('myAction', (event) => {
console.log('Action has been triggered!');
});

Note: To improve security, users cannot add action buttons/links to their messages when sending them in the chat UI. It only works with messages sent via the REST API.

Parameters

You can attach additional parameters to the action button or action link with the query string syntax. As an example, let's say we wanted to ask the user to pick which color they like more, out of red or blue. You could send a message that looks like this:

Which color do you prefer?
<actionbutton:color?choice=red|Red> <actionbutton:color?choice=blue|Blue>

A chat message with two buttons asking the user if they prefer the color red or the
color blue

Next, you can access the parameters in onCustomMessageAction:

chatbox.onCustomMessageAction('color', (event) => {
if (event.params.choice === 'red') {
alert('Roses are red!');
} else if (event.params.choice === 'blue') {
alert('Violets are blue!');
}
});

Actions in the Theme Editor

Inside the Theme Editor, action buttons and action links are available as built-ins in the following components:

  • UserMessage
  • SystemMessage
  • MessageBody
  • ChatHeader
  • MessageField
  • ConversationListHeader
  • ConversationListItem

If you want to render buttons from the example in the previous section in the Theme Editor, use this:

<ActionButton action="color" data-choice="red">Red</ActionButton>
<ActionButton action="color" data-choice="blue">Blue</ActionButton>

Or as links:

<ActionLink action="color" data-choice="red">Red</ActionLink>
<ActionLink action="color" data-choice="blue">Blue</ActionLink>

You can also add a custom CSS class:

<ActionButton action="my-action" class="my-class">
Click me!
</ActionButton>

Note: When an ActionButton or an ActionLink is placed in one of the following components:

  • ChatHeader
  • MessageField
  • ConversationListHeader
  • ConversationListItem

It will emit a Custom Conversation Action instead of a Custom Message Action. Also, actions triggered from inside ConversationListHeader will have e.conversation equal to null, while those triggered from ConversationListItem will have the property set to the relevant conversation.

Customizing the appearance

The action buttons used in the previous examples will result in this DOM:

<button data-action="color" data-choice="red">Red</button>
<button data-action="color" data-choice="blue">Blue</button>

If we had used action links, we would get this instead:

<a data-action="color" data-choice="red">Red</a>
<a data-action="color" data-choice="blue">Blue</a>

In other words, the provided action is attached as data-action. Any other parameters are also added as data-* attributes. This lets you style specific actions buttons/links with the button[data-action="color"] and a[data-choice="red"] selectors.

By default, action links look just like regular links. To make them appear differently from regular links, use the .text a[data-action] selector inside the MessageBody component in the Theme Editor.

To customize the default appearance of action buttons, you'll need to change the styles in a few places:

  • Inside the UserMessage component:
.by-me button[data-action] {
/* Buttons in messages by the current chat participant */
}
.by-other button[data-action] {
/* Buttons in messages from other chat participants */
}
  • Inside the SystemMessage component:
.message button[data-action] {
/* Buttons in system messages */
}
  • Inside the ChatHeader component:
.header button[data-action] {
/* Buttons in the chat header */
}