Safe Exchange API / Vault

How to Inject Sensitive Data into an Ongoing Chat Using the Safe Exchange API

The Safe Exchange API is designed to securely inject sensitive data into an ongoing chat session. Here’s a step-by-step guide on how to set it up and use it effectively:

Fetch the Chat ID

This can be done when the information should be injected, for example when a user successfully logs in to the site. The chatId is required for the Safe Exchange API to know where the information should be injected.

• When an Ebbot chat widget is loaded on a web page, a unique chat ID is generated and saved in the client’s local storage.

• Retrieve this chat ID from local storage. The key follows the format: <bot_id>_ebbot_chat_session_id.

• You can find the botID in Ebbot App under Chat Widget -> Settings.

Performing the API Call

• Use the retrieved chat ID to make an API call to inject data.

API Call Details

• Method & Endpoint: PUT https://<ebbot-url>/api/chats/<chatId>/vault

Note that the ebbot URL can differ depending on environment. Available urls are: v2.ebbot.app, ca.ebbot.app, ebbot.eu

• Authorization Headers: Include the API Key in the x-api-key header. This key can be generated in the Ebbot platform by navigating to: Settings -> Integrations -> API Keys

  Example format:

  {
    "x-api-key": "<publicKey>.<secretKey>"
  }

• Payload: The data to be injected should be in JSON format.

  Example:

  {
    "loggedIn": true,
    "customerInformation": {
      "first_name": "John",
      "last_name": "Smith",
      "customer_number": 1337
    }
  }

• cURL Example:

  curl --location --request PUT 'https://ebbot.eu/api/chats/<chatId>/vault' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: ••••••' \
  --data '{
    "loggedIn": true,
    "customerInformation": {
      "first_name": "John",
      "last_name": "Smith",
      "customer_number": 1337
    }
  }'

Listen to Chat Events

• Your web page can listen to specific events in the chat widget using the ChatWidgetAPI. This can help determine the appropriate time to inject data.

Recommended Events:

• onReset

• onCreate

• onStartConversation

For detailed information, refer to the Chat Widget API Reference.

Important Note

• Although the ChatWidgetAPI’s setUserAttribute function can also inject data into an ongoing chat, it's not recommended when dealing with sensitive information. This is due to security concerns of potential misuse through client browsers.

Data Storage in Vault

• Once injected, the data is stored in the vault section of the chat’s data object as key/value pairs.

• You can access or expand these variables within the bot's responses using the format: {{ vault.key_name }}.