Data Structures and Types
This document provides comprehensive examples of the data structures and types accepted by the Optave JavaScript SDK version 3.
Overview
The Optave SDK v3 accepts structured payloads that contain information about sessions and requests. The SDK uses JSON Schema validation (via AJV) to ensure data integrity.
Main Payload Structure
The SDK v3 payload consists of three main sections:
- headers: Message envelope headers for tracking, versioning, and correlation
- session: Session tracking, channel, interface information
- request: Request details, context, connections, attributes, scope, settings, and advanced features
Message Envelope Structure (Version 3+)
Version 3+ messages are wrapped in an envelope structure with headers for tracking and versioning:
{
action: "message",
headers: {
correlationId: "a1b2c3d4-e5f6-7890-1234-56789ab2345", // Auto-generated UUID if not provided
tenantId: "tenant-123", // Provided by Optave during SDK initialization
traceId: "trace-456", // Auto-generated UUID for cross-system tracing
idempotencyKey: "idem-789",
identifier: "message",
action: "customerinteraction", // The specific action being performed
schemaRef: "optave.message.v3",
sdkVersion: "3.2.1", // Use "none" if not using the SDK
networkLatencyMs: 120,
timestamp: "2024-01-15T10:30:00.000Z",
issuedAt: "2024-01-15T10:30:00.000Z"
},
payload: {
// Session and request objects (see below)
}
}
Not using the SDK?
If you are integrating directly without the Optave JavaScript SDK, set sdkVersion to "none" in your message headers:
sdkVersion: "none"
Data Type Reference
Session Object
Contains session tracking information, channel details, and interface information.
session: {
sessionId: "session-12345", // string - Custom session identifier
channel: { // object - Communication channel info
browser: "Safari 17.0", // string - Browser info
deviceInfo: "iOS/18.2, iPhone15,3", // string - Device information
deviceType: "mobile", // string - Device type
language: "en-US", // string - Channel language
location: "45.42,-75.69", // string - Geographic coordinates
medium: "chat", // string - "chat", "voice", "email"
metadata: [], // array - Custom metadata
section: "product_page" // string - Section of interface
},
interface: { // object - Interface details
appVersion: "1.2.3", // string - Custom app version
category: "crm", // string - Interface category
language: "en-US", // string - Interface language
name: "salesforce", // string - Interface name
type: "custom_components" // string - Interface type
}
}
Request Object
Defines the current request parameters, context, connections, attributes, scope, and settings.
request: {
requestId: "a1b2c3d4-e5f6-7890-1234-56789ab2345", // string - Unique request identifier
attributes: { // object - Request attributes
content: "How can I help you today?", // string - Main content
instruction: "Be helpful and friendly", // string - Special instructions
variant: "A" // string - Request variant
},
connections: { // object - Connection relationships
journeyId: "journey-456", // string - Journey identifier
parentId: "parent-789", // string - Parent connection ID (for adjust/elevate)
threadId: "thread-123" // string - Thread identifier (REQUIRED)
},
context: { // object - Context information (generated by Optave)
caseId: "case-456", // string - Case identifier (advanced mode)
departmentId: "dept-789", // string - Department identifier (advanced mode)
operatorId: "op-012", // string - Operator identifier (advanced mode)
organizationId: "org-345", // string - Organization identifier
userId: "user-678" // string - User identifier (advanced mode)
},
reference: { // object - Reference information (optional, for analytics)
ids: [ // array - Reference IDs
{ name: "ticket_id", value: "T12345" },
{ name: "order_id", value: "O67890" }
],
labels: ["priority", "escalation"], // array - Labels
tags: ["support", "urgent"] // array - Tags
},
resources: { // object - Resource information
codes: [ // array - Code resources
{
id: "10382320302", // string - Optional code ID for tracking
label: "Order Number", // string - Optional display label
type: "order_number", // string - Code type (e.g., "order_number", "booking_reference")
value: "ORD-56789" // string - Code value
}
],
links: [ // array - Link resources
{
expires_at: "2025-08-06T00:00:00Z", // string - Optional expiration timestamp
html: false, // boolean - Optional HTML content flag
id: "20382320302", // string - Optional link ID for tracking
label: "Click here to pay", // string - Optional display label
type: "payment_link", // string - Link type (e.g., "payment_link")
url: "https://checkout.stripe.com/pay/cs_test..." // string - Link URL
}
],
offers: [] // array - Offering details
},
scope: { // object - Contextual data scope
accounts: [], // array - Account information
appointments: [], // array - Appointment information
assets: [], // array - Asset information
bookings: [], // array - Booking information
cases: [], // array - Case data
conversations: [ // array - Conversation history (REQUIRED for most actions)
{
conversationId: "conv-123", // string - Conversation identifier
participants: [ // array - Conversation participants
{
participantId: "participant-456", // string - Participant ID
displayName: "John Doe", // string - Display name
role: "user" // string - "user", "operator", "bot"
},
{
participantId: "participant-789",
displayName: "Agent Smith",
role: "operator"
}
],
messages: [ // array - Messages in conversation
{
content: "I need help with my order", // string - Message content
participantId: "participant-456", // string - Who sent the message
timestamp: "2024-01-15T10:30:00.000Z" // string - ISO timestamp
},
{
content: "I'll help you with that",
participantId: "participant-789",
timestamp: "2024-01-15T10:30:15.000Z"
}
],
metadata: {} // object - Additional conversation metadata
}
],
documents: [], // array - Document references
events: [], // array - Event data
interactions: [ // array - System interactions
{
content: "Order found: #12345", // string - Interaction content
id: "interaction-123", // string - Interaction ID
name: "order_lookup", // string - Interaction name
role: "System", // string - Role
timestamp: "2024-01-15T10:30:00.000Z" // string - ISO timestamp
}
],
items: [], // array - Item information
locations: [], // array - Location data
offers: [], // array - Offer information
operators: [], // array - Operator information
orders: [], // array - Order information
organizations: [], // array - Organization data
persons: [], // array - Person information
policies: [], // array - Policy data
products: [ // array - Product information
{
id: "prod-123" // string - Product ID
}
],
properties: [], // array - Property data
services: [], // array - Service information
subscriptions: [], // array - Subscription data
tickets: [], // array - Ticket information
transactions: [], // array - Transaction data
users: [] // array - User information
},
settings: { // object - Request settings
disableBrowsing: false, // boolean - Disable web browsing
disableSearch: false, // boolean - Disable search functionality
disableSources: false, // boolean - Disable source references
disableStream: true, // boolean - Disable streaming responses (default: true)
disableTools: false, // boolean - Disable tool usage
maxResponseLength: 0, // number - Maximum response length (0 = no limit)
overrideInterfaceLanguage: "", // string - Override interface language
overrideOutputLanguage: "" // string - Override output language
},
// Advanced mode fields:
a2a: [ // array - Agent-to-agent configurations
{
id: "bot_55", // string - Agent ID
name: "Bot 55", // string - Agent name
type: "chatbot" // string - Agent type
}
],
cursor: { // object - Time-based cursor for data retrieval
since: "2024-01-15T10:30:00.000Z", // string - Start timestamp (ISO 8601)
until: "2024-01-15T11:00:00.000Z" // string - End timestamp (ISO 8601)
},
a2a: [ // array - Agent-to-agent communication
{
id: "bot_55", // string - Agent/bot ID
name: "Support Bot", // string - Agent/bot name
type: "chatbot" // string - Agent/bot type
}
]
}
Data Type Constraints
String Fields
- All string fields accept any valid UTF-8 string
- Empty strings are valid for most optional fields
- Required fields are validated during schema validation
Array Fields
- Arrays can contain objects or primitive types depending on the field
- Empty arrays
[]are valid for all array fields - When provided, arrays completely replace the default array
Boolean Fields
- Accept
trueorfalsevalues - Default values are used when not specified
Number Fields
integertype: Whole numbers (e.g.,current_workload: 5)numbertype: Decimal numbers (e.g.,latency_ms: 120.5)
Date-Time Fields
- Must be in ISO 8601 format:
"2024-01-15T10:30:00Z" - Can also be
nullfor optional date fields - Examples:
"2024-12-31T23:59:59Z","2024-01-15T10:30:00.000Z"
Required Fields
Universal Required Fields
These fields are required for all SDK method calls:
Request Level
request.context.tenant_id- Tenant identifier (generated by Optave)request.context.organization_id- Organization identifier (generated by Optave)request.connections.thread_id- Thread identifier for request groupingrequest.scope.conversations- Array of conversation messages
Required Fields by Action Type
Universal Required Fields
These fields are required for all SDK method calls:
Request Level
request.connections.threadId- Thread identifier for request grouping
Action-Specific Required Fields
customerinteraction
request.connections.threadId- Thread identifier
adjust
request.connections.threadId- Thread identifierrequest.connections.parentId- ID of the message to adjustrequest.attributes.content- Content to adjustrequest.attributes.instruction- Adjustment instructionrequest.scope.conversations- Non-empty array of conversations
elevate
request.connections.threadId- Thread identifierrequest.connections.parentId- ID of the message to elevaterequest.attributes.content- Content to elevaterequest.scope.conversations- Non-empty array of conversations
translate, summarize, insights
request.connections.threadId- Thread identifierrequest.scope.conversations- Non-empty array of conversations
recommend
request.connections.threadId- Thread identifierrequest.resources.offers- Non-empty array of offersrequest.scope.conversations- Non-empty array of conversations
Error Categories
The SDK version 3.2.1 includes comprehensive error handling with the following categories:
AUTHENTICATION- Issues with client credentials or authentication processORCHESTRATOR- Server-side processing errorsVALIDATION- Schema validation or required field errorsWEBSOCKET- Connection and communication errors