Promise-Based API (BETA)

The Dixa Messenger Promise-Based API is a new api that allows developers to control the Dixa Messenger widget programmatically via the native JS promises. It can be accessed through the window._dixa_.api object. it provides a set of methods that can be used to interact with the widget. Each method returns a promise that either resolves when the operation is successful or rejects when the operation fails or times out.

The payload for each method should be an object that contains the necessary data for the operation (refer to the docs below for details). The aim is to have 100% compatibility with the event-based API in terms of input and functionality. The promise-based API is a much easier-to-use alternative to the event-based API, especially for sequential operations that depend on each other.

Please note that all operations are asynchronous and should be awaited to ensure they are completed before the next operation is started.

Methods

init(payload: InitPayloadType): Promise<void>

Initializes the widget. The payload should contain the necessary data for initialization. Returns a promise that resolves when the widget is successfully initialized.

See Initialization Payload Details for more information on the argument type.

The promise can be rejected with the following errors:

• Invalid payload: rejects with the value of the provided payload
• Timeout: rejects with new Error() after 15 seconds of waiting for the widget to initialize
• Backend error: refer to backend error type definitions for more information

shutdown(): Promise<void>

Shuts down the widget. It has no arguments and returns a promise that resolves when the widget is successfully shut down. It can be rejected due to an internal widget error.

purgeUserIdentity(): Promise<void>

Purges the user identity. It has no arguments and returns a promise that resolves when the user identity is successfully purged. It can be rejected due to a timeout or an internal widget error.

setPosition(payload: SetPositionArg): Promise<void>

Sets the position of the widget. The payload should contain the necessary data for setting the position. Returns a promise that resolves when the position is successfully set. It can only be rejected due to an invalid input or an internal widget error.

setWidgetOpen(payload: boolean): Promise<void>

Opens or closes the widget based on the payload. The payload is a boolean determining if the widget should be opened or closed. Pass true for opening the widget and false to close it. This method returns a promise that resolves when the widget is successfully opened or closed. It can only be rejected due to an invalid input or an internal widget error.

setView(payload: SetViewArg): Promise<void>

Sets the view of the widget. The payload should contain the necessary data for setting the view. Returns a promise that resolves when the view is successfully set. It can be rejected due to the following reasons:

• Invalid payload: rejects with the value of the provided payload
• Timeout (5 seconds) or an internal widget error

endConversation(payload: EndConversationCommandPayload): Promise<void>

Ends the current conversation. The payload should contain the necessary data for ending the conversation. Returns a promise that resolves when the conversation is successfully ended.

It can be rejected for the following reasons:

• Invalid payload: rejects with the value of the provided payload
• Timeout: rejects with new Error() after 30 seconds of waiting for the conversation to end
• Backend error: refer to backend error type definitions for more information

startConversation(): Promise<{ conversationId: string }>

Starts a new conversation. It has no arguments and it returns a promise that resolves with the conversation ID when the conversation is successfully started.

It can be rejected for the following reasons:

• Invalid payload: rejects with the value of the provided payload
• Timeout: rejects with new Error() after 30 seconds of waiting for the conversation to start
• Backend error: refer to backend error type definitions for more information

setUserIdentity(payload: SetUserIdentityCommandPayload): Promise<void>

Sets the user identity. The payload should contain the payload for setting the user identity. Returns an empty promise that resolves when the user identity is successfully set.

It can be rejected for the following reasons:

• Invalid payload: rejects with the value of the provided payload
• Timeout: rejects with new Error() after 10 seconds of waiting for the user identity to be set
• Backend error: refer to backend error type definitions for more information

Simple Example

async function initWidget() {
  try {
    await window._dixa_.api.init({ messengerToken: 'your-token' });
    console.log('Widget initialized successfully');
  } catch (error) {
    console.error('Error initializing widget:', error);
  }
}

initWidget();

Advanced Example

async function initWidget() {
  try {
    const { api: dixaMessenger } = window._dixa_;
    await dixaMessenger.init({ messengerToken: 'yourMessengerToken' });
    console.log('Widget initialized successfully');

    await dixaMessenger.setUserIdentity({
      type: 'verified',
      payload: { type: 'jwe', token: 'yourJweTokenGoesHere' },
    });
    console.log('User identity set successfully');

    const { conversationId } = await dixaMessenger.startConversation();
    console.log('Conversation started successfully', conversationId);
  } catch (error) {
    console.error('Error initializing widget:', error);
  }
}