Event types and conversation flow

The Chat API’s /converse/chat endpoint takes eventType enum as part of the body. This field tells the endpoint which conversation event is happening. Based on the event type it will respond in various fashion.

Understanding the platformConversationIds

To understand the conversation flow we need to understand how to differentiate conversations. Our Chat API uses the platformConversationId as a unique string identifier of a conversation between a visitor and a bot. It is up to your application to determine the format of this field, keeping in mind it has to be unique per conversation. We would recommend using a uuid generator to create the platformConversationIds. Here is an example of a package for Node.js.

Event Types within chat conversations

startSession

This event starts a chat session, which means starting a new conversion with a bot for a specific platformConversationId that is supplied in the body of the request.

Starting a conversation triggers the bot to send a greeting message, if it is configured. It will also start the timer of inactivity timeout, this timeout will close the conversation after a preconfigured inactivity time from the visitor. It is also possible to restart a conversation using it’s platformConversationId,if the bot supports it.

Here is an example of a request body to start a conversation:

{
  "platformConversationId": "00000001",
  "eventType": "startSession",
  "metadata": [
    {
      "key": "userId",
      "value": "123456789"
    },
    {
      "key": "accountId",
      "value": "abcdefghi",
      "sanitize": true
    }
  ]
}

message

This event value means sending a message from the visitor in an already existing conversation identified by platformConversationId. If a conversation associated with the platformConversationId does not exist, this will also start a session using the supplied platformConversationId. The endpoints handles sending messages and preconfigured escalation events.

Here is an example of a request body to send a message in a conversation:

{
  "platformConversationId": "00000001",
  "eventType": "message",
  "text": "I want to make a refund",
  "metadata": [
    {
      "key": "userId",
      "value": "123456789"
    },
    {
      "key": "accountId",
      "value": "abcdefghi",
      "sanitize": true
    }
  ]
}

endSession

This event ends an existing conversation with a bot for the specified platformConversationID. This will also delete the conversation session.

Here is an example of a request body to end a conversation:

{
  "platformConversationId": "00000001",
  "eventType": "endSession"
}

metadata

Although you should send the metadata field with any event, in a rare case you might need to send it separately. The recommended way is to send this in the other events.

Here is an example of a request body to send metadata to a conversation:

{
  "platformConversationId": "00000001",
  "eventType": "metadata",
  "metadata": [
    {
      "key": "userId",
      "value": "123456789"
    },
    {
      "key": "accountId",
      "value": "abcdefghi",
      "sanitize": true
    }
  ]
}

The conversation flow diagrams

The conversation with the bot be:

  1. (OPTIONAL) We start the session with the backend. If we don’t explicitly start a session, it will be created when the first message is received:
    Start Session
    Start Session

Pro tip

Using the start a session event allows for the bot to send the welcome reply message in the conversation before the first message of the user. By skipping this event the greeting message in the chat would have to be handled by the chat widget or by your application, it would then not be configurable on the bot.

  1. Conversing with the bot (used for each visitor message):

    Message
    Message

  2. (OPTIONAL) Ending the session, if this is not explicitly performed, the session will automatically time out. The timeout is configurable on a bot level.

    End Session
    End Session