# Safe Exchange API

## Safe Exchange API in Ebbot <a href="#how-to-inject-sensitive-data-into-an-ongoing-chat-using-the-safe-exchange-api" id="how-to-inject-sensitive-data-into-an-ongoing-chat-using-the-safe-exchange-api"></a>

Note: the Safe Exchange API in Ebbot is for chat only.&#x20;

The Safe Exchange API is designed to securely inject sensitive data into an ongoing chat session.

## Using the Safe Exchange API

Below is a step by step guide on the Safe Exchange API, how to set it up and use it effectively in Ebbot chat platform.

### Inject sensitive data into an ongoing chat  <a href="#how-to-inject-sensitive-data-into-an-ongoing-chat-using-the-safe-exchange-api" id="how-to-inject-sensitive-data-into-an-ongoing-chat-using-the-safe-exchange-api"></a>

1. **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 the Ebbot Chat platform.

2. **Performing the API call**

Use the retrieved chat ID to make an API call to inject data. See API Call Details below.

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

{% hint style="warning" %}
Note that the ebbot URL can differ depending on environment. Available urls are: \
`v2.ebbot.app, ca.ebbot.app, ebbot.eu`&#x20;
{% endhint %}

* **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:

  ```plaintext
  {
    "x-api-key": "<publicKey>.<secretKey>"
  }
  ```
* **Payload:**\
  The data to be injected should be in JSON format.

  Example:

  ```json
  {
    "loggedIn": true,
    "customerInformation": {
      "first_name": "John",
      "last_name": "Smith",
      "customer_number": 1337
    }
  }
  ```
* **cURL Example:**

  ```bash
  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
    }
  }'
  ```

3. **Listen to Chat Events**

Your web page can listen to specific events in the chat widget using the Ebbot Chat widget API. This can help determine the appropriate time to inject data. See recommended events below:

* `onReset`
* `onCreate`
* `onStartConversation`

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.

4. **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 }}`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ebbot.ai/ebbot-docs/developer-resources/ebbot-chat/safe-exchange-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.