Metadata in Conversation Tools

5min
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.
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).
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"
      }
    ]
  }
}
{
  "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
      }
    }
  }
}
{
  "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..)
﻿
Advanced Conversational Settings (LLM Provider, external tools)
Overview