API methods

All API methods can be invoked on window.amioWebchat.

close()

window.amioWebchat.close() - closes the chat.

init()

window.amioWebchat.init({ /* params */}) - Initializes the chat.

Following customization options can be added to the configuration object of the init() function:

• channelId - string, required, the Channel ID of your Amio Chat channel
• externalContactId - string, an ID provided by you to persist a contact's conversation history. It can be used to overcome the short local storage history on iOS devices. The same generated ID should always be provided for the unique contact whenever init() is called and should be stored in the device storage.
  Note: If you want to logout a user and clear message history, you can call init() again without externalContactId or set externalContactId: null.
• logoUrl - string, URL of your company logo or other picture to be used as an avatar
• launcherImageUrl string, URL of an image used in the launcher.
• theme - string, color theme
• startOpened - boolean, if set to true, the chat will be already opened when the page is loaded
• lang - string, selects language. Default value is en (English).
• showVoice - boolean, if set to true, voice-to-text input method will be enabled and displayed as the primary means of input. NOTE: The voice-to-text feature is not enabled for all accounts. Contact our sales representative if you'd like to enable this feature.
• zIndex - number or string, sets the z-index value for Web Chat's wrapper div. Default value is 100.
• storageType - string, allows to choose if session data will be stored in localStorage or sessionStorage. Allowed values are: local (use localStorage, default), session (use sessionStorage).
• hideLauncher - string, this parameter changes how the Launcher (the button in bottom right that is shown when the Web Chat is closed and is used to open/close the Web Chat) is displayed. Supported values are:
  • never - default, Launcher is always displayed
  • chatOpen - Launcher will be hidden when Web Chat window is open. This makes the Web Chat window slightly taller which might allow for better use of the screen space.
  • always - Launcher will never be displayed. We recommend to use this option only if you want to implement an alternative way to open/close the Web Chat.
• hideCloseButton - boolean, if set to true, the Close button in the header of the Web Chat window will be hidden.
• hideHeader - boolean, if set to true, the Web Chat window will be displayed without the header.
• iframeOffsetX - string, e.g. 30px to move the iframe left by 30px
• iframeOffsetY - string, e.g. 30px to move the iframe up by 30px
• forceFullScreen - boolean, if set to true, the Web Chat's wrapper div and the Web Chat window will always occupy the whole screen (like it does on mobile device screen sizes)
• disablePopUpMessages - boolean, if set to true, the latest message will not display as a pop-up if the Web Chat window is closed (only the red badge indicating the number of unread messages will be shown).
• wideButton boolean, if set to true, the Launcher will be wide (displays chat icon with a title)
• themeOverride - JSON object, a data object containing chat widget theme properties. By customizing the values in this object and using them in themeOverride, you can change the default appearance and update how chat looks.
• langOverride - JSON object, a data object containing chat Text properties for chat's selected language (see lang parameter). By customizing the values in this object and using them in langOverride, you can replace the default text and update the wording in chat.

destroy()

window.amioWebchat.destroy() - removes the chat widget from the page and cleans up all associated resources. This function should be called when the chat widget is no longer needed, for example, when the user navigates away from the page or logs out. It ensures that all event listeners are removed and DOM elements created by the chat widget are cleaned up.

open()

window.amioWebchat.open() - opens the chat.

triggerEvent(eventId)

window.amioWebchat.triggerEvent(eventId) - triggers a custom event with event ID eventId.

setMetadata(metadata)

window.amioWebchat.setMetadata(metadata) - add arbitrary data to be sent along with chat messages. metadata can be any valid JS object

• FreshChat metadata described in more detail here.

onCallbackButtonPressed(callbackFunction)

window.amioWebchat.onCallbackButtonPressed(callbackFunction) - registers a function which will be called whenever a Callback button is pressed. The function should accept one parameter - payload of the pressed Callback button.

onUserEvent(callbackFunction)

📘

Connect 3rd party analytics

Using this method, you can react pass the events e.g. to your GA4.

window.amioWebchat.onUserEvent(callbackFunction) - registers a function which will be called whenever a user event is emitted. The function should accept two parameters - userEventName, and userEventParams (nullable).

// Implementation example
function yourCallbackFunction(userEventName, userEventParams = null) {
  switch (userEventName) {
    case 'message_submit':
      // do something
}

window.amioWebchat.onUserEvent(yourCallbackFunction)

userEventName Examples:

• launcher_click_open
• launcher_click_close
• header_click_close
• file_submit
• message_submit
• pop_up_click_open
• pop_up_click_close
• pop_up_button_click
• pop_up_quick_reply_click
• button_click
• quick_reply_click
• call_operator

userEventParams Examples:

Nullable and will vary depending on userEventName

// userEventParams example for 'file_submit'
const fileSubmitUserEventParams = {
  type: 'file',
  payload: 'someImageFile.png',
  metadata: {
    browserUrl: 'https://clientWebsite.com'
  }
}

// userEventParams example for 'message_submit'
const messageSubmitUserEventParams = {
  type: 'text',
  payload: 'Hello, where is my parcel?',
  metadata: {
    browserUrl: 'https://clientWebsite.com'
  }
}

// userEventParams example for 'button_click' and 'pop_up_button_click'
const buttonClickUserEventParams = {
  type: 'button',
  title: 'Visit Amio',
  payloadType: 'url',
  payload: 'https://amio.io',
  metadata: {
    browserUrl: 'https://clientWebsite.com'
  }
}

// userEventParams example for 'quick_reply_click' and 'pop_up_quick_reply_click'
const quickReplyClickUserEventParams = {
  type: 'quickReply',
  title: 'Delivery Info',
  payloadType: 'text',
  payload: 'qrPayload',
  metadata: {
    browserUrl: 'https://clientWebsite.com'
  }
}

// userEventParams example for 'call_operator'
const callOperatorUserEventParams = {
  intent: 'intentId',
  context: {
    customerRequest: {
      text: 'Can I have a custom debit card design?'
    }
  },
  metadata: {
    browserUrl: 'https://clientWebsite.com'
  }
}