Commands

The Dixa Messenger supports commands that can be called programmatically to manipulate different aspects of the widget.

API

To call a command you should use the _dixa_.invoke() API, which receives two arguments, first is the method name and the second is the options* for that command.

Here's a list of available commands:

Each command is explained in detail in the following sections.

Example syntax:

// Set the widget position programmatically, after it has been initialized.
_dixa_.invoke('setPosition', 'bottomLeft');

// clear user authentication data
_dixa_.invoke('purgeUserIdentity');

// open the widget programmatically
_dixa_.invoke('setWidgetOpen', true);

Commands & payloads

Note: some methods don't have a payload.

Command details

EndConversationCommandPayload

EndConversationCommandPayload: { conversationId?: string } | void

endConversation method can be used to end an open conversation. If no payload is provided, the current (latest) conversation will be closed. You can use this if you want to enforce a new conversation to be created. By calling this method you can be sure that the subsequent call to startConversation will create a new conversation.

Example:

// Close a known conversation
_dixa_.invoke('endConversation', { conversationId: '1234' });

// Close the current ongoing conversation
_dixa_.invoke('endConversation');

WidgetPosition

Union type for all possible widget position options

WidgetPosition: WidgetPositionSimple | WidgetPositionAdvanced

UserIdentity

UserIdentity: AnonymousUserIdentity | ClaimedUserIdentity | VerifiedUserIdentity

Union type for all possible user identities, See:

• AnonymousUserIdentity
• ClaimedUserIdentity
• VerifiedUserIdentity

setUserIdentity method can be used to change the identity of the user. For example when a user logs into your application, you can use this method to set the identity of the user. So that your customer service agents can see who they are talking to.

StartConversationCommandPayload

• StartConversationCommandPayload: void

startConversation method can be used to start a new conversation. this method will open the widget and navigate to the newly created conversation. If there's already an open conversation, this method will navigate to that conversation.

When the messenger is in form only mode (refer to the messenger settings in the Dixa dashboard), this method will open the form directly without creating a new conversation. Once the form is submitted, a new email-based conversation will be created on the Dixa platform.

SetViewCommandPayload

setView method can be used to control the current view of the widget. Note that this method doesn't automatically open the widget. Example:

// Opens a knowledge base article and then opens the widget itself
_dixa_.invoke('setView', {
  view: 'knowledgeBaseArticle',
  params: { articleId: '1234' },
});
_dixa_.invoke('setWidgetOpen', true);

SetWidgetViewPayload

SetWidgetViewPayload: { view: WidgetViews ; params?: SetViewKnowledgeBaseArticleViewPayload | SetViewKnowledgeBaseHomeViewPayload | SetViewConversationViewPayload | SetViewBulletinViewPayload }

setView method can be used to control the current view of the widget. Note that this method doesn't automatically open the widget. Example:

// Opens a knowledge base article and then opens the widget itself
_dixa_.invoke('setView', {
  view: 'knowledgeBaseArticle',
  params: { articleId: '1234' },
});
_dixa_.invoke('setWidgetOpen', true);

SetPositionCommandPayload

setPosition method. Can be used to set the position of the widget relative to the screen frame. Example:

// Shows the widget
_dixa_.invoke('setPosition', 'bottomLeft');

// Finer control over the positioning of the widget
_dixa_.invoke('setPosition', {
  position: 'bottomLeft',
  verticalPadding: 10,
  horizontalPadding: 10,
});

setPosition Parameters

purgeUserIdentity Payload

purgeUserIdentity method. Can be used to remove the current users identity info. The user will become anonymous after this operation. Example:

// Shows the widget
_dixa_.invoke('purgeUserIdentity');

purgeUserIdentity Parameters

Returns

void

SetWidgetOpen Command

setWidgetOpen method. Can be used to show or hide the widget programmatically. Example:

// Shows the widget
_dixa_.invoke('setWidgetOpen', true);

// Hides the widget
_dixa_.invoke('setWidgetOpen', false);

setWidgetOpen Parameters

Returns

void

shutdown command

shutdown method. It removes all widget related elements from the DOM and closes any connection. It has no payload and can be invoked in this way:

_dixa_.invoke('shutdown');

shutdown Parameters

Returns

void

Important note:

To restart the widget you can run the shutdown command and then the init command again. But for this to work properly you need to wait until the on-shutdown-completed event is emitted.

An example for restarting the widget:

_dixa_.invoke('shutdown');

// wait till the widget is completely shutdown
_dixa_.addListener('on-shutdown-completed', () => {
  // initialize the widget again
  _dixa_.invoke('init', {
    messengerToken: 'your-messenger-token',
  });
});

init command

init method. Once called, the widget iframe will be added to the DOM, the widget will be initialized and the toggler will show up (if it is not disabled in the payload).

The payload can be used to customize the initialization behavior, for example it is possible to hide the default toggler button setting the hideToggler property to true:

_dixa_.invoke('init', {
  messengerToken: '[YOUR_MESSENGER_TOKEN]',
  hideToggler: true,
});

You can find all the options in the InitPayload page.

Parameters:

Init Parameters

Returns

void