OpenDialog Docs
opendialog.aiStart BuildingTalk to an expert
  • GETTING STARTED
    • Introduction
    • Getting ready
    • Billing and plans
    • Quick Start AI Agents
      • Quick Start AI Agent
      • The "Start from Scratch" AI Agent
        • Chat Management Conversation
        • Welcome Conversation
        • Topic Conversation
        • Global No Match Conversation
        • Supporting LLM Actions
        • Semantic Classifier: Query Classifier
      • A Process Handling AI Agent
  • STEP BY STEP GUIDES
    • AI Agent Creation Overview
    • Add a new topic of discussion
    • Use knowledge sources via RAG
    • Adding a structured conversation
    • Add a 3rd party integration
    • Test and tweak your AI Agent
    • Publish your AI Agent
  • CORE CONCEPTS
    • OpenDialog Approach
      • Designing Conversational AI Agents
    • OpenDialog Platform
      • Scenarios
        • Conversations
        • Scenes
        • Turns and intents
      • Language Services
      • OpenDialog Account Management
        • Creating and managing users
        • Deleting OpenDialog account
        • Account Security
    • OpenDialog Conversation Engine
    • Contexts and attributes
      • Contexts
      • Attributes
      • Attribute Management
      • Conditions and operators
      • Composite Attributes
  • CREATE AI APPLICATIONS
    • Designing your application
      • Conversation Design
        • Conversational Patterns
          • Introduction to conversational patterns
          • Building robust assistants
            • Contextual help
            • Restart
            • End chat
            • Contextual and Global No Match
            • Contextual FAQ
          • Openings
            • Anatomy of an opening
            • Transactional openings
            • Additional information
          • Authentication
            • Components
            • Example dialog
            • Using in OpenDialog
          • Information collection
            • Components
            • Example dialog
            • Using in OpenDialog
            • Additional information
          • Recommendations
            • Components
            • Example dialog
            • Additional information
          • Extended telling
            • Components
            • Example dialog
            • Additional information
          • Repair
            • Types of repair
            • User request not understood
            • Example dialog
            • Additional information
          • Transfer
            • Components
            • Example dialog
            • Additional information
          • Closing
            • Components
            • Example dialog
            • Using in OpenDialog
            • Additional information
        • Best practices
          • Use Case
          • Subject Matter Expertise
          • Business Goals
          • User needs
            • Primary research
            • Secondary research
            • Outcome: user profile
          • Assistant personality
          • Sample dialogs
          • Conversation structure
          • API Integration Capabilities
          • NLU modeling
          • Testing strategy
          • The team
            • What does a conversation designer do
          • Select resources
      • Message Design
        • Message editor
        • Constructing Messages
        • Message Conditions
        • Messages best practices
        • Subsequent Messages - Virtual Intents
        • Using Attributes in Messages
        • Using Markdown in messages
        • Message Types
          • Text Message
          • Image Message
          • Button Message
          • Date Picker Message
          • Audio Message
          • Form Message
          • Full Page Message
          • Conversation Handover message
          • Autocomplete Message
          • Address Autocomplete Message
          • List Message
          • Rich Message
          • Location Message
          • E-Sign Message
          • File Upload Message
          • Meta Messages
            • Progress Bar Message
          • Attribute Message
      • Webchat Interface design
        • Webchat Interface Settings
        • Webchat Controls
      • Accessibility
      • Inclusive design
    • Leveraging Generative AI
      • Language Services
        • Semantic Intent Classifier
          • OpenAI
          • Azure
          • Google Gemini
          • Output attributes
        • Retrieval Augmented Generation
        • Example-based intent classification [Deprecated]
      • Interpreters
        • Available interpreters
          • OpenDialog interpreter
          • Amazon Lex interpreter
          • Google Dialogflow
            • Google Dialogflow interpreter
            • Google Dialogflow Knowledge Base
          • OpenAI interpreter
        • Using a language service interpreter
        • Interpreter Orchestration
        • Troubleshooting interpreters
      • LLM Actions
        • OpenAI
        • Azure OpenAI
        • Output attributes
        • Using conversation history (memory) in LLM actions
        • LLM Action Analytics
    • 3rd party Integrations in your application
      • Webhook actions
      • Actions from library
        • Freshdesk Action
        • Send to Email Action
        • Set Attributes Action
      • Conversation Hand-off
        • Chatwoot
    • Previewing your application
    • Launching your application
    • Monitoring your application
    • Debugging your application
    • Translating your application
    • FAQ
    • Troubleshooting and Common Problems
  • Developing With OpenDialog
    • Integrating with OpenDialog
    • Actions
      • Webhook actions
      • LLM actions
    • WebChat
      • Chat API
      • WebChat authentication
      • User Tracking
      • Load Webchat within page Element
      • How to enable JavaScript in your browser
      • SDK
        • Methods
        • Events
        • Custom Components
    • External APIs
  • Release Notes
    • Version 3 Upgrade Guide
    • Release Notes
Powered by GitBook
On this page
  • How to create & use your custom components
  • A working example
  1. Developing With OpenDialog
  2. WebChat
  3. SDK

Custom Components

This section describes how you can pass in your own message types to be rendered in the WebChat application.

PreviousEventsNextExternal APIs

Last updated 7 months ago

WebChat will allow you to pass in your own components to render as message types in the message list. This means that you could, for example, write your own Location message using a maps plugin of your choice and use it to override the default OpenDialog Location message, which requires a Google Maps API key.

Or you could use custom components to render message types outside of the current types supplied by OpenDialog. However, you will also need to set up a backend data source that provides the correct message data for WebChat to render in your components.

For more info about the current message types, response types and their data structure, explore our .

How to create & use your custom components

Any component passed into the WebChat application must be written as a Vue 3 single file component. How you create and import your components into your application beyond that is entirely up to you.

Every message-type component that you create can receive the following properties, and emit the following events:

<your-message-component
   :msg="" // Message object - the current message object. See the API docs for more details
   :theme="" // Theme object - taken from the theme/colours that you passed into your settings or set in the interface settings section of OpenDialog
   :latest="" // boolean - derived dynamically from the current message history. Indicates whether the message is the latest one in the list
   :errorTemplates="" // object - uses settings.messages from the config endpoint
   :language="" // string - the currently selected language code
   @submit="(data: any) => onComponentSubmit(data.type, data.data)"
   @cancel="onCancel(message)"
/>

A working example

This is an example of a very basic message component that renders some text and emits a submit event when the button is clicked:

LocationMessage.vue
<template>
  <div class="location-message">
    <p>{{ msg.data.text }}</p>
    <small>I'm a basic component being used to override the default location message</small>
    <button class="submit" @click="handleSubmit">Submit</button>
  </div>
</template>

<script setup lang="ts">
export interface ILocationMessage {
  author: string
  data: {
    text: string
    callback_id: string
    attribute_name: string
    api_key: string
    [key: string]: any
  }
  [key: string]: any
}

export interface ILocationProps {
  msg: ILocationMessage
  theme?: {[key: string]: any}
  latest?: boolean
  errorTemplates?: {[key: string]: any}
  language?: string
}

const props = withDefaults(defineProps<ILocationProps>(), {
  msg: () => {
    return {} as ILocationMessage
  }
})

const emit = defineEmits(['submit'])

const handleSubmit = () => {
  const data = {
    text: 'You clicked the submit button!',
    callback: props.msg.data.callback_id,
  }
  
  /**
  * @event submit
  * @type {object}
  * @property {object} data - The data you wish to send back to ChatApi
  * @property {string} type - The response type you wish to send. See API docs for more details
  */
  emit('submit', {data, type: 'button'})
}
</script>

<style scoped>
.location-message {
  color: green;
}
</style>

Now that we have a component, we need to provide WebChat with a name for it and some optional other values. At it's simplest, this will look as follows:

main.js
import { LocationMessage } from 'my-library' // this will depend on your setup
import type { Component } from 'vue' // you don't need Vue as a dependency at this point. This is just importing the Component type for our interface

interface CustomComponent {
  name: string
  component: Component
  fullScreen?: Boolean
  autoShow?: Boolean // only applicable if overriding the esign or location message
  showMessage?: Boolean // only applicable if overriding the fp-form message
}

const componentData: Array<CustomComponent> = [
  {
    name: 'location', // must be the same as the `type` in the message data.
    component: LocationMessage,
    fullScreen: true,
    autoShow: false
  }
]

The name property must be the same as the message type property in the data. This is how WebChat maps message components to the data received from the API.

Finally, we can pass in our custom components when we initialise our WebChat widget:

main.js
const webchat = new ODWebChat.OpenDialogChatSDK('#my-webchat-element')

webchat.init(settings, componentData)

When we put all these elements together, your Javascript code will look like the following:

main.js
import { LocationMessage } from 'my-library'
import type { Component } from 'vue'

interface CustomComponent {
  name: string
  component: Component
  fullScreen?: Boolean
  autoShow?: Boolean 
  showMessage?: Boolean 
}

const componentData: Array<CustomComponent> = [
  {
    name: 'location',
    component: LocationMessage,
    fullScreen: true,
    autoShow: false
  }
]

const settings = {
  url: 'your_bot_url', 
  appKey: 'your_app_key', 
  sdkEnabled: true,
  user: {
    custom: {
      selected_scenario: your_scenario_id 
    }
  }
}

const webchat = new ODWebChat.OpenDialogChatSDK('#my-webchat-element')

webchat.init(settings, componentData)

At this point, when WebChat receives a message from ChatApi with a type of location , it will render the custom component rather than the default one provided by OpenDialog.

ChatAPI documentation