Webchat

Webchat Template

Setting up your template for webchat interactions

To effectively handle webchat interactions, you need to set up two important contexts in your template:

1. Create Context: Handles the initial connection and creates a new stub for each conversation
2. Default Context: Manages the ongoing conversation and processes user messages

# Create Context Setup

The create context is responsible for receiving the first message from a webchat user and initializing a new conversation stub.

# What is the Create Context Used For?

• In order to interact with end users through webchat, you need to have a stub that manages incoming traffic
• The create context specifies actions that handle the first message a user sends from webchat
• A stub will be created from the create context, and this stub will handle webchat events

# Setup Options

You have two routing options for your webchat traffic:

# Option 1: Stubref Routing (Recommended for Most Cases)

1. Navigate to the create context and open the canvas

2. Create an action called _update_from_webchat

   Your canvas should look like this:

3. Configure Create Stub Task

   In the _update_from_webchat action, add the task create_stub (with data) from the task library:

   Configure with the following parameters:

           "params": {
     "templateuuid": "~~template.templateuuid",
     "template_branch": "~~template.branch",
     "template_context": "default",
     "data": {
       "_incoming_webchat_data": "~~stubpost.data._incoming_webchat_data"
     }
   }
   
         

   Data from the webchat service is placed in stub.data._incoming_webchat_data. To pass this data to the new stub, we configure params.data._incoming_webchat_data to have the value ~~stubpost.data._incoming_webchat_data.

4. Test Your Webchat Client

   • You will see that a draft stub was automatically created for you

   • Open that stub and copy the stubref

   • In your webchat profile, select the draft branch and enable Send webchat traffic to stub

   • Paste your copied stubref into the stubref field

   • Open your webchat client and send a message

   • After sending a message, the webchat service will execute the _update_from_webchat action

# Option 2: Heimdall Routing (For Advanced Use Cases)

1. Navigate to the create context and create an action register_heimdall_paths

   Your canvas should look like this when complete:

2. Configure Heimdall Register Task

   In register_heimdall_paths, add the task heimdall_register from the task library:

   Configure with the following parameters:

           "params": {
     "uuid": "{{#deterministicuuid stub.stubref stub.program.branch 'initial'}}{{/deterministicuuid}}",
     "registration_name": "heimdall_webchat_initial_message",
     "on_trigger_method": "keep",
     "events": {
       "webchat_initial_message": {
         "path": "stubber.systems.notifications.webchat.org.{{stub.orguuid}}.name.{{stub.program.branch}}_your_chat_name.webchatmessagetype.firstmessage",
         "mechanism": "cbh",
         "timeout_seconds": 3600
       }
     },
     "trigger_stubaction": {
       "action_name": "create_stub",
       "stubref": "~~stub.stubref",
       "message": "Created stub from webchat"
     }
   }
   
         

   Important: Replace your_chat_name with the Chat name from your webchat profile.

3. Configure Create_Stub Action

   In create_stub, add the task create_stub (with data) from the task library:

   Configure with the following parameters:

           "params": {
     "templateuuid": "~~template.templateuuid",
     "template_branch": "~~template.branch",
     "template_context": "default",
     "data": {
       "_incoming_webchat_data": "~~stubpost.data.heimdall.webchat"
     }
   }
   
         

   Data from heimdall events is placed in stub.data.heimdall.webchat. We want to pass this data to the new stub as it contains the webchat session uuid used to reply to a specific webchat instance.

4. Test Your Webchat with Heimdall

   • Create a draft stub and run the action register_heimdall_paths

   • Open your webchat client and send a message

   • After sending a message, heimdall will execute the create_stub action

# Default Context Setup

The default context handles the ongoing conversation after the initial connection is made.

# What is the Default Context Used For?

• Handle interactions between the user and other systems in stubber
• React and respond to the user's incoming messages
• Create a stubsession between the new stub and the webchat session for ongoing communication

# Setting Up the Default Context

1. Navigate to default context and click on Edit Flow

2. Create Basic Flow Structure

   • Create a state called pending-message (This will be the state that the stub will be in when replying to messages)
   • Add an action called reply (This action will send a message to the webchat client)
   • Add an action called _create (This action runs when the stub is created)
   • Add an action called _update_from_webchat (This action will be used to trigger a reply when a user sends a message)

   

3. Configure the Reply Action

   In the reply action, add the Webchat notification to session from the library and configure it as follows:

           "platforms": {
     "webchat": {
       "sessionuuid": "~~stub.data._incoming_webchat_data.sessionuuid",
       "webchat_message": {
         "type": "markdown",
         "value": "~~stubpost.message"
       },
       "stubsession": {
         "set_new_with_timeout_hours": 24
       }
     }
   }
   
         

   Change webchat.sessionuuid value to ~~stub.data._incoming_webchat_data.sessionuuid. This will allow the notification to send a message to the correct client.

4. Configure the _create Action

   In the _create action, add the task Send action from the library and configure it as follows:

           {
     "tasktype": "sendaction",
     "params": {
       "action_name": "reply",
       "message": "A stub has been created",
       "stubref": "~~stub.stubref"
     },
     "name": "sendaction",
     "__key": "sendaction"
   }
   
         

   This will trigger a reply when the new stub is created. Once the reply is sent, a stubsession will be created between the new stub and the webchat client, allowing all future messages to be routed into the _update_from_webchat action.

   

5. Configure the _update_from_webchat Action

   To respond to future messages, add the task Send action to _update_from_webchat:

           {
     "tasktype": "sendaction",
     "params": {
       "action_name": "reply",
       "message": "Conversation stub is now handling all future replies",
       "stubref": "~~stub.stubref"
     },
     "name": "sendaction",
     "__key": "sendaction"
   }
   
         

   Now all future messages will be handled by the conversation stub:

   

# Advanced Configuration

Once you have set up your basic webchat template, you can:

1. Add AI Integration

   • Integrate with AI models to provide automated responses
   • Create intelligent routing based on message content

2. Customize Message Formats

   • Use different message types (text, markdown, cards)
   • Include images and attachments in responses

3. Implement Business Logic

   • Add form collection functionality
   • Create conversational workflows
   • Integrate with external systems through webhooks

4. Manage Conversation State

   • Track conversation history and context
   • Implement conversation timeouts and transfers