Web Conversations JavaScript API

Customise your Web Conversations instance through its JavaScript API

When the Web Conversations JS API has loaded you can use the JavaScript API that Web Conversations offers. With this JavaScript API it is possible to manipulate the Web Chat of Web Conversations.

In order to manipulate the Web Chat component you can use the following method:



  • <WEBCONVERSATION_ID>: The ID of the targeted Web Chat, which can be found in Web Conversations.
  • <METHOD>: The name of the method the Web Chat will call.
  • <PAYLOAD>: The argument for the method.




The Web Chat UI must be initialized before any of the methods can be triggered.

The following methods are supported:


Provides the option to ask a question in Web Conversations (and hide it from the UI)
Method: 'ask'
Payload: Object

  data: {
    userInput: '' // required
  metadata: {}

Example code:

wcc[<WEBCONVERSATION_ID>].push(['ask',  { data: { userInput: 'hello world!' } , metadata: {}])
// Ask a question
wcc[<WEBCONVERSATION_ID>].ask('hello world!')

// Ask a question and hide it in the UI
wcc[<WEBCONVERSATION_ID>].ask('hello world!', true)

It is also possible to pass user and session properties to the Conversational AI Cloud's API with the metadata. If such is wished then every property in the user/session object must be configured as a user/session property in the Conversational AI Cloud CMS.

Example code:

wcc[<WEBCONVERSATION_ID>].push(['ask',  { data: { userInput: 'hello world!' } , metadata: { session: { firstName: 'Joe'}, user: { firstName: 'Joe' } } }])

Change State

Provides the option to change the state of various UI components.
Method: 'changeState'
Payload: Object

  'property': value

The properties of the payload can be as the following (can be multiple at the same time as long as it's a key value pair within the payload):

isHiddentrue/falseHides/shows the web chat
isOpentrue/falseMaximizes/minimizes the conversation
showInputtrue/falseShows/hides the input field

Disclaimer: The above 3 properties are the only properties actively supported. If a developer decides to mutate any other properties than the ones listed above, then this action is not supported by the product, nor do we guarantee that these properties will work/continue to work functionality in future releases.

Example code:

wcc[<WEBCONVERSATION_ID>].push(['changeState', { isHidden: true }])


Provides the possibility to trigger an event on Conversational AI Cloud's API.
Method: 'sendEvent'
Payload: String/Object

  data: {
    eventName: '' // required
  metadata: {}

Example using string payload:

wcc[<WEBCONVERSATION_ID>].push(['sendEvent', 'myEvent'])

The Object payload makes it possible to send user/session properties like the 'ask' method
Example using the Object payload:

wcc[<WEBCONVERSATION_ID>].push(['sendEvent',  { data: { eventName: 'myEvent' } , metadata: { session: { mode: 'internal'} } }])

Language detection

Provides the ability to set and get the selected language.
Method: 'setSelectedLanguage' & 'getSelectedLanguage'
Payload: Object

Make sure that translation is enabled for the project/config first and that either 'en' is a valid option (either explicitly enabled or all languages are enabled by having no language set.

Example code:

await wcc[<WEBCONVERSATION_ID>].setSelectedLanguage('en')

Example code:

await wcc[<WEBCONVERSATION_ID>].getSelectedLanguage()