Web SDK - JavaScript Integration Reference for ConvyAI Web Chat
Overview
The ConvyAI Web SDK exposes a JavaScript interface that lets your website interact with the bot programmatically - without relying on the chat widget UI. Use it to start conversations automatically, pass customer data, trigger bot events, and listen for conversation lifecycle notifications.
All SDK functions are available after the HTML snippet has been included in the page, via:
window.ConvyAI.function_name(parameters)
Data exchange between the page and the bot interface is handled via postMessage.
Functions
startConversation()
Starts the conversation with the bot. Equivalent to the customer clicking the engagement button.
window.ConvyAI.startConversation()
endConversation()
Ends the conversation currently in progress.
window.ConvyAI.endConversation()
sendMessage( text_message )
Sends a text message to the bot on behalf of the customer.
| Parameter | Type | Description |
|---|---|---|
text_message | String | The text to send as a customer message. |
window.ConvyAI.sendMessage('I need help with my order')
attachData( obj )
Sends customer data to the bot before the conversation starts. The data is attached to the next startConversation() call and made available as variables in the flow.
| Parameter | Type | Description |
|---|---|---|
obj | Object | Key-value pairs of customer data to pass as variables. |
window.ConvyAI.attachData({ customerId: '12345', plan: 'premium' })
window.ConvyAI.startConversation()
sendEvent( event_name, parameters )
Triggers a bot event. Use this when a flow node is configured to wait for an external event.
| Parameter | Type | Description |
|---|---|---|
event_name | String | The name of the event to trigger, matching the event name configured in the WAIT_FOR_EVENT node. |
parameters | Object | Optional data to pass with the event. Available as variables in the WAIT_FOR_EVENT node. Pass {} if no data is needed. |
window.ConvyAI.sendEvent('payment_confirmed', { orderId: 'ORD-789', amount: 42.00 })
init( init_parameters )
Defines bot behaviors before the conversation starts. Call this before startConversation().
init_parameters values are merged with any query string parameters. If the same parameter is specified in both, init() takes precedence.
| Parameter | Type | Description |
|---|---|---|
autoStart | Boolean | Automatically starts the conversation on script load. |
autoStartDelay | Number | Delay in milliseconds before autostart fires. |
hideButton | Boolean | Hides the engagement button. |
fullPage | Boolean | The bot interface fills the entire page. |
window.ConvyAI.init({ hideButton: true, autoStart: true, autoStartDelay: 3000 })
getVersion()
Returns the current GUI version string.
const version = window.ConvyAI.getVersion()
listen
Subscribes to conversation lifecycle events. Each listener accepts a callback function that is called when the event fires.
window.ConvyAI.listen.event_name(callbackFunction)
Available events
| Event | When it fires | Callback payload |
|---|---|---|
conversationCreated() | Conversation starts. | { type: 'conversationCreated' } |
conversationClosed() | Conversation ends. | { type: 'conversationClosed' } |
messageReceived() | A message is received. | { type: 'messageReceived', message: String } |
eventReceived() | A bot event is received. | { type: 'eventReceived', ...eventParameters } |
handoverStarted() | Handover to agent begins. | { type: 'handoverStarted' } |
handoverSuccessful() | Handover completes successfully. | { type: 'handoverSuccessful' } |
handoverClosed() | Handover session ends. | { type: 'handoverClosed' } |
handoverFailed() | Handover fails (e.g. queue timeout). | { type: 'handoverFailed' } |
All callbacks receive an object with a type key indicating the event name.
Examples
Full-page bot on load:
window.ConvyAI.init({ fullPage: true })
Listen for conversation end:
window.ConvyAI.listen.conversationClosed(function(event) {
console.log('Conversation ended', event)
})
Pass CRM data and autostart:
window.ConvyAI.attachData({ email: 'user@example.com', tier: 'gold' })
window.ConvyAI.init({ autoStart: true, autoStartDelay: 1000 })