Documentation

JavaScript API 2.0

Customise your Web Conversations 2.0 instance through its JavaScript API

Suggest Edits

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:

cmwc.get('WEBCONVERSATION_ID').METHOD([<PAYLOAD>])

Where:

  • <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.

Methods

📘

Did you know?

The JavaScript API of Web Conversations 2.0 can be configured before the Web Chat UI is initialized.

You cannot call the JS API functions before the webchat has initialized. However, you can pass a function to the install function. This allows the given function to be called when the webchat is being initialized.

Example code:

<body>

  <script>
  // Declaration function
  function jsapi() {
        // function calls
		cmwc.get('WEBCONVERSATIONS_ID').open()
	}
	</script>

  // Declared function added in the install function
  <script type="module" crossorigin="anonymous" src='https://webchat.digitalcx.com/webchat.js' onload="cmwc.add('WEBCONVERSATIONS_ID', jsapi).install();">
  </script>


</body>

If the function above is passed through the following behaviour will happen:

  • When Web Chat gets initialized the passed function will be called and if configured your 'onload' event.
  • If you reset your Web Chat via the reset button the function will be called again and if you configured an onload event, this as well.
  • If there are multiple functions that contain more than one call for example: 'SendEvent/sendMessage' and/or the onload event is configured the response might not be in the same order as the called order.

The following methods are supported:

sendMessage

Provides the option to send a question in Web Conversations
Method: 'sendMessage'
Payload: String

Example code:

// Send a message
cmwc.get('WEBCONVERSATION_ID').sendMessage('hello world!')

Response:

{ 
  success: true,
  message: 'Successfully sent message "<message>"'
}

Error response examples:

{ 
  success: false,
  message: `Expected type "string" but received type "${receivedType}"`
}

// Empty argument
// Thrown when the argument is either empty or undefined
{ 
  success: false,
  message: 'Argument cannot be empty'
}

Show/Hide

Provides the option to show or hide the chatbot (rendered, but completely hidden).
Method: show/hide'

PropertyFunction
showShows the web chat
hideHides the web chat

Example code:

cmwc.get('WEBCONVERSATION_ID').show()

cmwc.get('WEBCONVERSATION_ID').hide()

Response:

undefined

Open/Close

Provides the option to open (maximize) and close (minimize) the bot
Method: 'open/close''

PropertyFunction
openMaximizes the chatbot
closeMinimizes the chatbot

Example code:

cmwc.get('WEBCONVERSATION_ID').open()

cmwc.get('WEBCONVERSATION_ID').close()

Returns:

undefined

SendEvent

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

Example using string payload:

cmwc.get('WEBCONVERSATION_ID').sendEvent('eventname')

Response:

{ 
  success: true,
  message: 'successfully sent event <eventname>'
}

Error response examples:

// Thrown when the argument is not a string
{ 
  success: false,
  message: `Expected type "string" but received type "${receivedType}"`
}

// Empty argument
// Thrown when the argument is either empty or undefined (falsy)
{ 
  success: false,
  message: 'Argument cannot be empty'
}

Language detection

Provides the ability to set and get the selected language.
Method: 'setLanguage' & 'getLanguage'
Payload: String

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. The list of the supported language codes can be found over here: https://developers.cm.com/conversational-ai-cloud/docs/languages

Example code:

cmwc.get('WEBCONVERSATION_ID').setLanguage(language: 'en')

Example code:

cmwc.get('WEBCONVERSATION_ID').getLanguage()

Response:

// Response setLanguage
{ 
  success: true,
  message: 'Successfully set language code to <languageCode>'
}

// Response getLanguage
{ 
  success: true,
  message: 'Successfully returned a <languageCode>'
  result: <languageCode>
}

Error response examples:

// Thrown when the argument is not a string
{ 
  success: false,
  message: `Expected type "string" but received type "${receivedType}"`
}

// Empty argument
// Thrown when the argument is either empty or undefined (falsy)
{ 
  success: false,
  message: 'Argument cannot be empty'
}

// Translation is not enabled for this configuration
{ 
  success: false,
  message: 'Config "${WEBCONVERSATION_ID}" does not have translation enabled'
}

//The input language is not enabled for this configuration
{ 
  success: false,
  message: 'Config "${WEBCONVERSATION_ID}" does not have language "${language}" enabled'
}

addContext

Provides the option to set the context through the JS API.

Empty string as context value will not be accepted.

Method: 'addContext'
Payload: Object

Example code of setting one context:

cmwc.get('WEBCONVERSATION_ID').addContext({key: 'value'})

Example code of setting multiple context:

cmwc.get('WEBCONVERSATION_ID').addContext({ key1: 'value1', key2: 'value2' })

All set context will be saved until your session expires and you reset/refresh Web Chat. For example:

cmwc.get('WEBCONVERSATION_ID').addContext({ key1: 'John', key2: 'Doe' } )

The call after:

cmwc.get('WEBCONVERSATION_ID').addContext({ key1: 'Bob', key2: 'Doe' })

The context that will be set through the JS API will then be:

{ key1: 'Bob', key2: 'Doe' }

Returns:

{ 
  success: true,
  message: `Context <contexts> set`
}

Error response examples:

// Thrown when the argument is not an object
{ 
  success: false,
  message: `Expected type "object" but received type "${receivedType}"`
}

// Empty argument
// Thrown when the argument is either empty or undefined (falsy)
{ 
  success: false,
  message: 'Argument cannot be empty'
}

// Empty argument
// Thrown when the argument has a key with a falsy value 
{ 
  success: false,
  message: `Value of context '${contextName}' cannot be empty`
}

// Generic error
// Thrown when the value of one of the contexts is not a string
{ 
  success: false,
  message: `Value of context '${contextName}' must be of type 'string'`
}

addConversationVariables

Provides the option to set conversation variables through the JS API.

Empty string as context value will not be accepted.

Method: 'addConversationVariables'
Payload: Object

Example code:

cmwc.get('WEBCONVERSATION_ID').addConversationVariables({ key: 'value' })

Example code of setting multiple conversation variables:

cmwc.get('WEBCONVERSATION_ID').addConversationVariables({ key1: 'value1', key2: 'value2' })

Response:

{ 
  success: true,
  message: `Conversation variable <conversationVariables> added`
}

Error response examples:

// Thrown when the argument is not an object
{ 
  success: false,
  message: `Expected type "object" but received type "${receivedType}"`
}

// Empty argument
// Thrown when the argument is either empty or undefined (falsy)
{ 
  success: false,
  message: 'Argument cannot be empty'
}

// Empty argument
// Thrown when the argument has a key with a falsy value 
{ 
  success: false,
  message: `Value of conversation variable '${conversationVariableName}' cannot be empty`
}

// Generic error
// Thrown when the value of one of the contexts is not a string
{ 
  success: false,
  message: `Value of conversation variable '${conversationVariableName}' must be of type 'string'`
}


onAnswer

Provides the option to add on answer logic through the JS API.

The event object contains the current answer and related data (outputAdditions, images, video, links, etc)

cmwc.get('WEBCONVERSATION_ID').onAnswer((event) => {
              //Your onAnswer logic here
})

Updated 8 months ago