SDK Events in DashaScript

DashaScript provides built-in capabilities to respond to events sent from the SDK, allowing your conversational AI application to react to external events during runtime. This is useful for integrating with external systems or triggering specific dialogue flows based on backend processes.

Event Handling

There are two ways to handle SDK events in DashaScript:

Using a when SDKEvent handler
Using a digression with the onSDKEvent tag

Events are sent from your Node.js application using the conv.sendEvent() method, and can be processed in your DashaScript dialogue flow.

Event Handlers

Event handlers in DashaScript are defined with the when SDKEvent syntax. These handlers can respond to specific named events sent from your application.

when SDKEvent eventName do {
    // Code to handle the event
    #sayText("I received an event!");
}

The event handler will be triggered when an event with the name matching eventName is sent from the SDK.

Digression with onSDKEvent Tag

Alternatively, you can handle events using a digression with the onSDKEvent tag. This approach allows you to temporarily interrupt the current dialogue flow to process the event.

digression handleExternalEvent {
    conditions { on true tags: onSDKEvent; }
    do {
        // Code to handle the event
        #sayText("I received an external event!");
        return;
    }
}

Using the getSDKEvent Function

To access data from the SDK event, DashaScript provides the #getSDKEvent() function.

getSDKEvent

Returns the currently processing SDK event sent from the application code. This allows you to access custom events and their data within your DashaScript dialogue flow.

#getSDKEvent();

Returns

{ eventName: string; value: { [key: string]: string; }; }?

An object containing:

eventName - The name of the event sent from the SDK
value - An object containing the event data as key-value pairs

Returns null if there is no current SDK event being processed.

Example

Here's a complete example showing both ways to handle SDK events:

Using a when SDKEvent handler:

when SDKEvent userJoined do {
    var event = #getSDKEvent();
    #log(event);
    #sayText("Welcome, " + (event?.value?.name ?? "there") + "!");
}

Using a digression with the onSDKEvent tag:

digression onExternalEvent {
    conditions { on true tags: onSDKEvent; } 
    do {
        var event = #getSDKEvent();
        #sayText("Hello, " + (event?.value?.name ?? "Unknown user"));
        return;   
    }
}

Sending Events from the SDK

Events are sent from your Node.js application using the conv.sendEvent() method. Here's an example:

// Send an event from your Node.js application
await conv.sendEvent("userJoined", {
    name: "John",
    age: "30",
    role: "customer"
});

This would trigger the corresponding event handler in your DashaScript, which could then access the event data using #getSDKEvent(). The example above would log:

[application] info {"eventName":"userJoined","value":{"name":"John","age":"30","role":"customer"}}
AI: Welcome, John!
AI: Hello, John

Common Use Cases

SDK events are particularly useful for:

External Integrations: Responding to external API calls or webhooks
Asynchronous Processing: Handling results of long-running processes
System Notifications: Receiving backend system notifications
Warm Transfers: Managing agent availability in call transfer scenarios

Best Practices

Use descriptive event names to make your code more readable
Keep event payloads concise and focused on the specific data needed
Handle unexpected events gracefully
Log events for debugging purposes
Consider using timeouts for events that require prompt handling

Found a mistake? Let us know.