---
title: Metadata in Conversation Tools
slug: metadata-in-conversation-tools
createdAt: 2025-02-24T12:02:33.719Z
---

When using Conversation Tools with a Digital Human, you automatically receive metadata along with the LLM's response. This metadata provides valuable context about the conversation and the user.

:::hint{type="info"}
Please ensure the Digital Human is created with the **operation mode** set to "**oc**".
:::

### 
The metadata is provided as a JSON object with the following fields:

- **session\_metadata:** An object containing details about the conversation session: 
  - **org\_id:** The unique ID of the organization the Digital Human belongs to.
  - **head\_id:** The unique ID of the Digital Human.
  - **public\_org\_id:** A human-readable identifier for the organization.
  - **public\_head\_id:** A human-readable identifier for the Digital Human.
  - **user\_id:** A unique ID assigned to the user for this session.
  - **session\_id:** A unique ID for the current conversation session.
  - **username:** The username of the user (set by default as "anonymous").
  - **timestamp:** The timestamp of the message in UTC (ISO 8601 format).
  - **request\_metadata:** An object containing additional metadata about the user's request: 
    - **essential:** 
      - **origin\_domain:** The domain from which the user initiated the conversation.
      - **device\_info:** Information about the user's device: 
        - **device\_type:** (e.g., "desktop", "mobile", "tablet").
        - **browser\_family:** (e.g., "chrome", "firefox", "safari").
      - **language\_pref:** The user's preferred language (e.g., "en-US").
    - **technical:** 
      - **session\_hash:** A hash value associated with the session.
      - **request\_secure:** Indicates whether the request was made over HTTPS (true/false).

:::hint{type="info"}
With other integrations (such as Zapier), the metadata payload may contain user-defined tool parameters, for example:

- **email:** The user's email address.
- **company:** The user's company.
:::

**Example Conversation Tool Configuration with Metadata:**

Here's an example of how to configure a Conversation Tool to save user details, along with an example of the metadata received in the response:

```json
{
  "conversationSettings": {
    "tools": [
      {
        "url": "https://url.com/webhook",
        "name": "SaveUserDetails",
        "parameters": [
          {
            "name": "email",
            "type": "string",
            "description": "email of the user"
          },
          {
            "name": "company",
            "type": "string",
            "description": "company where the user works"
          }
        ],
        "description": "Use this tool to save user details"
      }
    ]
  }
}
```

### Example of a metadata response:

```json
{
  "email": "email@example.com",
  "company": "companyX",
  "session_metadata": {
    "org_id": "12c12ee1-ad12-1212-12ab-12345",
    "head_id": "123456138b2c5c0578ca8818",
    "public_org_id": "testOrganization",
    "public_head_id": "headId_name",
    "user_id": "F1sHkiFkNt5g123Tmrvyvw",
    "session_id": "121212ffb-1e1c-1212-a1f1-121ac121ec1e",
    "username": "anonymous",
    "timestamp": "2025-02-24T11:07:04.472719Z",
    "request_metadata": {
      "essential": {
        "origin_domain": "https://chat.unith.ai",
        "device_info": {
          "device_type": "desktop",
          "browser_family": "chrome"
        },
        "language_pref": "en-US"
      },
      "technical": {
        "session_hash": "012bd01cba0b01fc",
        "request_secure": true
      }
    }
  }
}
```

**Use Cases for Metadata:**

- **Conversation Logging:** The session\_id and timestamp are crucial for logging and reconstructing conversations.
- **User Identification:** The user\_id, email, and username can help identify users. *(Instructions for managing the 'username' field from the frontend will be available shortly.)*
- **Contextualization:** The device\_info and language\_pref can be used to tailor responses to the user's context.
- **Analytics:** The metadata can be used to gather insights into user behavior and platform usage.
- **Security:** The origin\_domain and request\_secure fields can be used for security and fraud prevention.

### 
The metadata capturing using Zapier integration (coming soon..)