# 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:

| Command | Description |
|  --- | --- |
| init | initialize the widget |
| shutdown | shutdown the widget |
| setWidgetOpen | open the widget programmatically |
| setUserIdentity | sets the user identity to a new one |
| purgeUserIdentity | remove cached user identity data |
| setPosition | control the position of the widget |
| setView | control the active view of the widget |
| startConversation | Start a new conversation or go to the currently live one |
| endConversation | End a conversation or end the currently live one |


Each command is explained in detail in the following sections.

Example syntax:


```ts
// 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

| Command name | Payload type | Return type | Example |
|  --- | --- | --- | --- |
| init | [InitPayload](/docs/dixamessenger/web/interfaces/initpayload) | `void` | [See @Initialization](/docs/dixamessenger/web/overview#initialization) |
| shutdown | `void` | `void` | `_dixa_.invoke('shutdown');` |
| setWidgetOpen | `boolean` | `void` | `_dixa_.invoke('setWidgetOpen', true);` |
| purgeUserIdentity | `void` | `void` | `_dixa_.invoke('purgeUserIdentity');` |
| setPosition | [WidgetPosition](/docs/dixamessenger/web/interfaces/widgetposition) | `void` | `_dixa_.invoke('setPosition', 'bottomLeft');` |
| setView | [SetWidgetViewPayload](/docs/dixamessenger/web/interfaces/widgetviews) | `void` | `_dixa_.invoke('setView', {view: 'knowledgeBaseArticle', params: {articleId: '1234'}});` |
| startConversation | `void` | `void` | `_dixa_.invoke('startConversation');` |
| endConversation | [EndConversationCommandPayload](#endconversationcommandpayload) | `void` | `_dixa_.invoke('endConversation', {conversationId: '1234'});` |
| setUserIdentity | [UserIdentity](#useridentity) | `void` | `_dixa_.invoke("setUserIdentity", { type: "verified", payload: { type: "jwe", token: "SomeJWEToken" }})` |


**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:


```ts
// 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](/docs/dixamessenger/web/interfaces/widgetposition#type-widgetpositionsimple) | [WidgetPositionAdvanced](/docs/dixamessenger/web/interfaces/widgetposition#interface-widgetpositionadvanced)

### UserIdentity

**UserIdentity**: [`AnonymousUserIdentity`](/docs/dixamessenger/web/interfaces/anonymoususeridentity) | [`ClaimedUserIdentity`](/docs/dixamessenger/web/interfaces/claimeduseridentity) | [`VerifiedUserIdentity`](/docs/dixamessenger/web/interfaces/verifieduseridentity)

Union type for all possible user identities, See:

- [AnonymousUserIdentity](/docs/dixamessenger/web/interfaces/anonymoususeridentity)
- [ClaimedUserIdentity](/docs/dixamessenger/web/interfaces/claimeduseridentity)
- [VerifiedUserIdentity](/docs/dixamessenger/web/interfaces/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:


```ts
// 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:


```ts
// 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:


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


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

#### `setPosition` Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `method` | `"setPosition"` | - |
| `payload` | `WidgetPosition` | [WidgetPosition](/docs/dixamessenger/web/interfaces/widgetposition#position) |


### `purgeUserIdentity` Payload

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


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

#### `purgeUserIdentity` Parameters

| Name | Type |
|  --- | --- |
| `method` | `"purgeUserIdentity"` |
| `payload` | `void` |


#### Returns

`void`

### `SetWidgetOpen` Command

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


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

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

#### `setWidgetOpen` Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `method` | `"setWidgetOpen"` | - |
| `payload` | `boolean` | If set to true, the widget will be displayed, otherwise it will be hidden |


#### 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:


```ts
_dixa_.invoke('shutdown');
```

#### `shutdown` Parameters

| Name | Type |
|  --- | --- |
| `method` | `"shutdown"` |


#### 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:


```ts
_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:


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

You can find all the options in the [InitPayload](/docs/dixamessenger/web/interfaces/initpayload) page.

### Parameters:

#### `Init` Parameters

| Name | Type |
|  --- | --- |
| `method` | `"init"` |
| `payload` | [InitPayload](/docs/dixamessenger/web/interfaces/initpayload) |


#### Returns

`void`