Conversation lifecycle

In general we can distinguish between two scenarios; at first a new conversation is created and presented to the visitor, and in case the visitor leaves the website or app temporarily and returns the connection to the Seamly conversation can be resumed.

This section contains high level overview of the steps to be taken. For exact details on the requests, parameters and responses (including examples), please have a look a the OpenApi and AsyncAPI specifications.

Create initial conversation

To create a new conversation you must follow the following steps.

Get account config

First of all send a request to the account config endpoint to get account settings and further URLs required for the other requests. The response contains enough information to setup the interface. For example it might return that the translation feature is available, so you can already render a button allowing the visitor to translate the conversation.

Send a POST request to https://api.uat.seamly-app.com/channels/api/v2/client/{api_key}/configs for the Seamly UAT environment, or https://api.seamly-app.com/channels/api/v2/client/{api_key}/configs for the Seamly production environment, replacing {api_key} with your api key.

The response will contain two segments: config containing account configuration settings and _links containing HAL Links. You must use the links provided in the _links section for all other requests. URLs used in links returned in _links sections may change at any time in the future without notice (this applies to all requests returning HAL Links).

Get UI translations

We provide an endpoint with a set of interface labels for each enabled locale of your account. The set is finite, but specific values can be changed by Seamly support and new labels may be needed for new features. Of course it's up to you whether you want to use this endpoint, or whether you want to provide your own interface labels. But please note:

In case you use the Seamly translation feature, the visitor can enable translating to any number of languages. As it is nice to also switch the chat interface labels to the newly selected language, the UI translation endpoint will provide labels for all available languages.

The URL of the endpoint is available in the HAL links of the account config endpoint. But it has two placeholders; {version} and {locale} . You'll need to replace {version} with the current translation version. At this moment it's "2", and once we rename or delete any label a new version will be made available. {locale} must be replaced with the requested locale ("en-GB" for example).

Create a new conversation

Send a POST request to the conversation endpoint as found in the HAL links in the account config response. This will create a blank conversation, and from the Seamly perspective no connection will be made yet to a bot or livechat service.

The response will contain information about the conversation to be able to continue with the next steps. The three most important details are:

conversation.accessToken : The token required to start (or resume) interacting with the conversation. All requests relating to the conversation require this token as a bearer token in the Authorization header. So the header would look like this:
```
Authorization: Bearer <accessToken>
```
_links.socket.href : The URL of the conversation's websocket.
_links.conversation.href : The URL to get all current information (including all messages) of the conversation.

You should store the access token and the conversation href somewhere so you'll be able to resume the conversation in case the visitor temporarily leaves the conversation. When integrating for the web, you might use the browser's SessionStorage for example. See the next chapter (Resume the conversation) for details on how to resume a conversation given you have these three details at hand.

In case the hibernation feature is enabled, you may send an externalId along with this request. In that case the handling of this request differs slightly. Please look at the hibernation feature in the Features section for more information.

Connect websocket

Finally setup a websocket connection to the websocket endpoint found in the HAL links in the account config response. (The same link is also returned in the response of the create conversation request.)

All messages sent and received over the websocket are documented in the AsyncAPI specification.

Once connected you first must attach the channel to the conversation. Once attached you can send messages and you'll start receiving conversation updates. The message is constructed like:

{
  "type": "attach_channel",
  "payload": {
    "accessToken": "[access_token]",
    "channelName": "[channel_name]"
  }
}

This message must be sent within 5 seconds after establishing the websocket connection. Failure to do so will result in Seamly disconnecting the websocket in an attempt to guard against denial of service.

When the attach was successful or in case something went wrong you'll receive a AttachChannelResponse message.

Next up we want to actually start the conversation by sending a StartConversation message:

{
  "type": "start_conversation"
}

As a response you'll receive a StartConversationResponse message indicating if everything was successful, followed by a ServiceAttach message. The last message contains all service specific information, such as a character limit of messages.

Too keep the websocket connection open you need to implement a heartbeat mechanism. Browsers will by default close a websocket connection in about 60 seconds after the last message. Hence we'll need to make sure we keep sending something even if the conversation is idle. So make sure to send a Ping message at least every 30 seconds. You'll receive a Pong message in return.

In case the websocket get disconnected you'll need to reconnect the websocket. This might happen for example due to a network hick-up or due to a webserver reload.

From now on you can start interacting with the conversation.

Resume the conversation

It might happen a visitor temporarily leaves the conversation. For example when a visitor navigates to another page on your website. As documented in the 'Create initial conversation' flow above you'll have stored the conversation's access token and URL. With those available you can send a request to that conversation URL to resume the conversation.

Get account config

As in the regular flow when creating a new conversation, start with the request to get the account configuration.

Get conversation

Send a GET request to the stored conversation URL. This request might fail in case the visitor was away for too long. The Seamly conversation will expire after a certain amount of time (configurable by Seamly support, but usually around 15 minutes). When this happens you can delete the stored id, access token and url, and start a new conversation.

But in case the conversation is still available the response of this request will contain all information about the conversation so far. Including all messages sent back and forth, so you'll be able to complete reconstruct the history.

Get UI translations

You might want to hold of the requesting the UI translations to right after the get conversations request. In case the translation feature was active in the conversation, the conversation response will contain that locale and you will be able the immediately request the translations for that locale. In any other case, just request the default locale.

Connect websocket

Just as with the initial create conversation flow, connect to the websocket and send a AttachChannel message. This time however, since the conversation is already started, there's no need to send the StartConversation message again.