1. Webchat
  2. Getting Started

Webchat

Getting Started

Setting up the webchat notification system

Setup steps

Configure webchat client

  • To configure a webchat client you need and orguuid and a chat_name
  1. orguuid is used to route heimdall traffic to your orgs registered paths
  2. chat_name is used to specify different channels for webchat traffic. This is useful if you wish to setup webchats for different purposes. The chat name must be all lowercase with no special characters e.g ( livewebsitechat / personalassistant ).
  • Go to webchat demo builder
  • Enter your orguuid and chat_name into the appropriate fields under Chat admin settings and refresh the page

image

Creating template

  1. Create context
  2. Default context
  • The Create Context is used to initiate a conversation once a user sends a message
  • The Default Context is used to handle conversations with the user

Create context flow

  • The context flow has to do 3 things
  1. Register heimdall path to receive payloads from webchat client
  2. Send an initial message to the webchat client
  3. Initiate a conversation stub once a message is sent by the user

Navigate to create context and click on Edit Flow image

Heimdall path registration action

  • Create template data annotation using and name it messages.welcome. This will be the opening message sent to the webchat client when they open the chat window

  • Create an action called register_for_initial_chat_messages.

  • Add a task called Heimdall register from library.

image

  • In Advanced tab for the Heimdall register action update the params.uuid to {{#deterministicuuid stub.stubref stub.program.branch 'initial'}}{{/deterministicuuid}}. This will generate a uuid using the branch and the stubref. This is to make your heimdall path registration unique for draft and live stubs

  • In params.events remove wait_for_test_data and replace it with the below object

        "webchat_initial_message": {
  "path": "stubber.systems.notifications.webchat.org.{{stub.orguuid}}.name.{{stub.program.branch}}webchatguide.webchatmessagetype.initialize",
  "mechanism": "cbh",
  "timeout_seconds": 3600
}

      
  • The path parameter has 3 parts
  1. Base : stubber.systems.notifications.webchat.org.{{stub.orguuid}} this is your orgs base path for all webchat heimdall events
  2. Chat name : .name.{{stub.program.branch}}webchatguide this is to specify what group of webchat traffic the stub will receive. {{stub.program.branch}} Is concatenated with the name you chose such that draft and live stubs do not interfere with each others traffic
  3. Message type : .webchatmessagetype.initialize this is used to receive specific payload types from the webchat client. The initialize type is a payload sent when the user opens the chat window in their browser. We use this message to send the opening message to the user
  • Replace webchatguide in .name.{{stub.program.branch}}webchatguide of the path parameter with the name you defined at Configure webchat client

  • Create a draft stub and run register_for_initial_chat_messages action

  • Go to your webchat demo page setup in Configure webchat client

  • Make sure your chat_name has draft at the start to receive payloads from draft stubs

  • Open your webchat chat window

  • If your setup is correct you will receive the below payload in stub.data

        "heimdall": {
  "webchat": {
    "sessionuuid": "6032f9c0-794b-48df-8e50-1440035cd9a5",
    "webchat_configuration": {
      "chat_name": "draftwebchatguide",
      "pass_through_data": "{'some':'data'}",
    },
    "webchat_meta_data": {
      "ip": "000.000.000.00",
      "origin": "https://demo.webchat.notifications.stubber.com",
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
    }
  }
}

      

Sending opening message to webchat client

  • To communicate with our webchat client we need the sessionuuid. This is found at stub.data.heimdall.webchat.sessionuuid. The uuid is randomly generated when a user opens up the chat window.
  • Create an action called send_opening_message
  • This action will be responsible for sending the opening message to the user using the sessionuuid

image

  • In the action send_opening_message add a notification from the library called Webchat notification to session
  • In the Webchat notification to session enter your desired opening message in platforms.webchat.webchat_message.value as seen below
          {
    "platforms": {
    "webchat": {
        "sessionuuid": "~~stub.data.heimdall.webchat.sessionuuid",
        "webchat_message": {
          "type": "markdown",
          "value": "This is your opening message" // your opening message
        },
        "stubsession": {
          "set_new_with_timeout_hours": 24
        }
      }
    },
    "name": "webchat_out_message",
    "__key": "webchat_out_message"
  }

      
  • In the action register_for_initial_chat_messages in task Heimdall register update params.trigger_stubaction.action_name to send_opening_message
        "params": {
  "trigger_stubaction": {
    "action_name": "send_opening_message", // specifies the action you want to trigger
    "stubref": "~~stub.stubref",
    "data": "~~stubpost.data",
    "message": "~~stubpost.message"
  }
}

      
  • Go to your draft stub and run register_for_initial_chat_messages. This will overwrite your previous heimdall registration so that all initialize payloads trigger send_opening_message

  • Now when a user opens a webchat window the stub will run an action send_opening_message

  • This action will send the opening message to the user.

  • To test this go to your webchat demo page and refresh. Once you open your chat window you will see the opening message

image

Receiving a users first message

  • There are 2 ways you can receive a message from a user stubsession and Heimdall.

  • stubsession. This automatically routes all future traffic from the specific webchat session directly into the stub.

  • Traffic sent via stubsession will trigger the adam action _update_from_webchat

  • Data received from stubsession will be placed into _incoming_webchat_data

  • Below is how stubsession is configured

        "stubsession": {
  "set_new_with_timeout_hours": 24
}

      
  • In this scenario a stubsession will be created when sending your opening message.

  • The stubsession will be valid for the hours specified. In scenario case it will be 24 hours.

  • Sending this notification from a different stub will overwrite the existing stubsession and all message traffic will go to the new stub

  • Our next step is to move our chat to the default context when the user sends their first message.This is done so that we can create conversation stubs for people that are interested in communication

  • To create a stub when a user sends a message we need to override _update_from_webchat. To do so create an action called _update_from_webchat

  • Add the task create_stub_with_data from library. In the data parameter of the interpolate the _incoming_webchat_data object from stub.data. This will give the new stub all the data it needs to communicate with the webchat

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

      
  • This new stub will now be responsible for handling future messages for this session.

image

Default context flow

  • The default context has to reply to the user so that a stubsession is created between the new stub and the webchat session

Navigate to default context and click on Edit Flow

Replying to a users first message

  • Create a state called pending-message. This will be the state that the stub will be in when replying to the message
  • Add an action called reply. This action will send a messages to the webchat client.
  • Add an action called _create. This action runs when the stub is created. We want to override this action so that the new stubs first action is replying. You can trigger any actions provided you send a reply.
  • Add an action called _update_from_webchat. This action will be used to trigger a reply to the webchat when a user sends a message

image

  • Data for the webchat client will be present at stub.data._incoming_webchat_data
  • In the reply action add the Webchat notification to session from the library. change webchat.sessionuuid value to ~~stub.data._incoming_webchat_data.sessionuuid. This will allow the notification to send a message to the correct client.
        "platforms": {
  "webchat": {
    "sessionuuid": "~~stub.data.heimdall.webchat.sessionuuid",
    "webchat_message": {
      "type": "markdown",
      "value": "~~stubpost.message"
    },
    "stubsession": {
      "set_new_with_timeout_hours": 24
    }
  }
}

      
  • In the _create action add the task Send action from the library. Change the params.action_name to reply. This is to trigger a reply when the new stub is created. Once the reply is send a stubsession will be created between the new stub and the webchat client allowing all future messages to be routed into the action _update_from_webchat.

  • Change the params.message to the value A stub has been created. This is so that we can identify what action triggered the reply

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

      

image

Replying to a users future messages

  • To run actions when a user send a message we need to add the task Send action to _update_from_webchat.
  • Change the params.message to the value Conversation stub is now handling all future replies. This is so that we can identify what action triggered the reply
        {
  "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 as seen below

image