Chat API 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 between conversations. Our Chat API uses the platformConversationId as a string identifier of a single conversation. It is up to the Custom CRM to determine the format of this field, as long as it is unique per conversation with a customer. 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, this means starting a new conversion with a bot for a specific platformConversationId that’s supplied in the body of the request. The platformConversationId is a unique identifier of the conversation between the visitor and the bot.

Starting the conversation will trigger bot sending a greeting message, if such is configured. It will also start the timer of inactivity timeout configured for bot, 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 given 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 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

Will end 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.

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 start a session event allows for the bot to send the welcome reply message in the conversation before a message from a user. By skipping this event the Greeting message in chat would have to be handled by the chat widget or the custom CRM, therefore not being 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 the bot level.

    End Session
    End Session