Sending Messages

The SDK provides methods to send different types of AI requests through the WebSocket connection. Each method corresponds to a specific action type.

Available Methods

• interaction(params) - Handle customer interactions
• reception(params) - Handle initial customer reception
• elevate(params) - Escalate to human agent
• adjust(params) - Adjust AI behavior
• summarize(params) - Generate summaries
• translate(params) - Translate content
• recommend(params) - Get recommendations
• insights(params) - Generate insights
• customerInteraction(params) - ⚠️ Deprecated (use interaction instead)

Example: Sending an Interaction Message

note

The customerInteraction method is deprecated. Please use the interaction method instead for new implementations.

const interactionParams = {
  headers: {
    timestamp: "2024-01-15T10:30:00.000Z"
  },
  session: {
    sessionId: "a1b2c3e6-e5f6-7890-1234-56789abcdef0",
    channel: {
      browser: "Safari 17.0",
      deviceInfo: "iOS/18.2, iPhone15,3",
      deviceType: "mobile",
      language: "en-US",
      location: "40.7128,-74.0060",
      medium: "chat",
      section: "support_page"
    },
    interface: {
      appVersion: "2.1.0",
      category: "crm",
      language: "en-US",
      name: "my_support_app",
      type: "custom_components"
    }
  },
  request: {
    requestId: "a1b2c3d4-e5f6-7890-1234-56789ab2345",
    attributes: {
      variant: "A"
    },
    connections: {
      threadId: "9e8d7c6b-5a49-3827-1605-948372615abc"
    },
    context: {
      organizationId: "f7e8d9c0-b1a2-3456-7890-123456789abc",
      tenantId: "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
    },
    settings: {
      disableSearch: false,
      disableStream: false,
      disableSources: false,
      disableTools: false,
      disableBrowsing: false,
      maxResponseLength: 2000,
      overrideOutputLanguage: "en-US",
      overrideInterfaceLanguage: "en-US",
      overrideChannelMedium: "voice"
    },
    scope: {
      resources: {
        links: [
          {
            id: "20382320302",
            type: "payment_link",
            url: "https://checkout.stripe.com/pay/cs_test...",
            label: "Complete Payment",
            html: false,
            expiresAt: "2025-08-06T00:00:00Z"
          }
        ],
        codes: [
          {
            id: "328123-123812312-13023f08asdxjfw0e",
            type: "order_number",
            value: "ORD-12345",
            label: "Order Number"
          }
        ]
      },
      conversations: [
        {
          conversationId: "",
          participants: [
            {
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              displayName: "John Doe",
              role: "user"
            },
            {
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789xyz",
              displayName: "Sarah Smith",
              role: "operator"
            }
          ],
          messages: [
            {
              content: "Hi, can you help me?",
              participantId: "2c4f8a9b-1d3e-5f70-8293-456789012def",
              timestamp: "2024-01-15T10:30:00.000Z"
            },
            {
              content: "Hello! I'd be happy to assist you today. What can I help you with?",
              participantId: "5b8c9d0e-2f4a-6b1c-9d8e-123456789xyz",
              timestamp: "2024-01-15T10:30:15.000Z"
            }
          ],
          metadata: {}
        }
      ],
      interactions: [
        {
          content: "Support ticket T12345 has been created for user John Doe",
          id: "1",
          name: "ticket_created",
          role: "system",
          timestamp: "2024-01-15T10:29:45.000Z"
        }
      ]
    }
  }
};

const response = await client.interaction(interactionParams);
console.log('Response:', response.data);

Payload Structure

The SDK manages a default payload structure that encapsulates session information, user details, agent information, requests, and more. When sending a message, you provide a params object that is merged with the default payload to form the final payload sent over the WebSocket.

Envelope Headers

Each outbound message is wrapped in an envelope with a headers object. The SDK auto-populates the following headers:

const headers = {
  correlationId: "3b8c9d0e-2f4a-6b1c-9d8e-123456789xyz", // Auto-generated (uuid v7)
  action: "interaction", // "adjust", "elevate", etc.
  schemaRef: "optave.message.v{<major>}",
  sdkVersion: "3.2.1",
  identifier: "message",
  traceId: "234c9d0e-2f4a-6b1c-9d8e-123456789xyz", // Auto-generated (uuid v7)
  idempotencyKey: "774c9d0e-2f4a-6b1c-9d8e-123456789xyz", // Auto-generated (uuid v7)
  timestamp: "2024-01-15T10:30:00.000Z", // client event time
  issuedAt: "2024-01-15T10:31:00.000Z",
  networkLatencyMs: 120
};

Default Payload Overview

• sessionId: Custom identifier that lasts for the duration of a chat session or a call
• session: Contains session-related data including:
  • channel: Channel information (medium, section, language, location, device details, browser)
  • interface: Interface details (app version, type, category, name, language)
  • network: Network information (latency measurements, moved to headers - networkLatencyMs)
• request: Contains the main request structure with:
  • requestId: Unique identifier for the request
  • attributes: Optional attributes like variant information
  • connections: Connection details such as threadId (should remain unique across all requests related to the same ticket/case/conversation)
  • context: Generated by Optave, includes tenantId and organizationId
  • settings: Configuration options for response behavior (disable flags, length limits, language overrides)
  • scope: Contains:
    • resources: Resource data like links and codes
    • conversations: Array of conversation messages with participant details
    • interactions: Array of system interactions and events