Streaming Analyze - Interhuman AI Docs

Messages

{
  "type": "conversation_quality.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "overall": {
      "quality_index": 72,
      "clarity": 67,
      "authority": 68,
      "energy": 80,
      "rapport": 75,
      "learning": 70
    },
    "timeline": [
      {
        "start": 0,
        "end": 11,
        "values": {
          "quality_index": 70,
          "clarity": 69,
          "authority": 70,
          "energy": 78,
          "rapport": 77,
          "learning": 68
        }
      }
    ]
  }
}

{
  "type": "error",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "code": "ih6002",
    "message": "WebSocket message too large. Individual video chunks must not exceed 32 MB.",
    "link": "https://docs.interhuman.ai/api-reference/error-handling#ih6002-message-too-large",
    "segment": 2
  }
}

{
  "type": "session.ready",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "session_idle_timeout_seconds": 300,
    "session_max_duration_seconds": 3600,
    "min_segment_duration_seconds": 3,
    "min_segment_size_bytes": 1,
    "max_segment_size_bytes": 33554432,
    "supported_session_config_options": {
      "include": [
        "conversation_quality_overall",
        "conversation_quality_timeline"
      ]
    }
  }
}

{
  "type": "session.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "include": [
      "conversation_quality_overall"
    ]
  }
}

{
  "type": "signal.detected",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "signal_type": "agreement",
    "start": 3,
    "probability": "high",
    "rationale": "Subject nodded repeatedly while maintaining eye contact."
  }
}

{
  "type": "signal.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "signal_type": "agreement",
    "start": 6,
    "probability": "medium",
    "rationale": "Subject nodded once but then looked away."
  }
}

WSS

stream

analyze

Messages

{
  "type": "conversation_quality.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "overall": {
      "quality_index": 72,
      "clarity": 67,
      "authority": 68,
      "energy": 80,
      "rapport": 75,
      "learning": 70
    },
    "timeline": [
      {
        "start": 0,
        "end": 11,
        "values": {
          "quality_index": 70,
          "clarity": 69,
          "authority": 70,
          "energy": 78,
          "rapport": 77,
          "learning": 68
        }
      }
    ]
  }
}

{
  "type": "error",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "code": "ih6002",
    "message": "WebSocket message too large. Individual video chunks must not exceed 32 MB.",
    "link": "https://docs.interhuman.ai/api-reference/error-handling#ih6002-message-too-large",
    "segment": 2
  }
}

{
  "type": "session.ready",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "session_idle_timeout_seconds": 300,
    "session_max_duration_seconds": 3600,
    "min_segment_duration_seconds": 3,
    "min_segment_size_bytes": 1,
    "max_segment_size_bytes": 33554432,
    "supported_session_config_options": {
      "include": [
        "conversation_quality_overall",
        "conversation_quality_timeline"
      ]
    }
  }
}

{
  "type": "session.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "include": [
      "conversation_quality_overall"
    ]
  }
}

{
  "type": "signal.detected",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "signal_type": "agreement",
    "start": 3,
    "probability": "high",
    "rationale": "Subject nodded repeatedly while maintaining eye contact."
  }
}

{
  "type": "signal.updated",
  "timestamp": "2025-01-01T00:00:00.000000Z",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "signal_type": "agreement",
    "start": 6,
    "probability": "medium",
    "rationale": "Subject nodded once but then looked away."
  }
}

bearerAuth

type:http

API key authentication. Include your API key in the Authorization header as 'Bearer <api_key>'.

headers

type:object

X-Client-Request-Id

type:string

Optional identifier supplied by the client to correlate this request with their own logs. When provided, the value is recorded alongside the server-assigned correlation ID in Interhuman logs to aid lookup and support investigations. This header is not echoed back in the response; the server returns its own correlation ID in the X-Correlation-ID HTTP response header.

Sec-WebSocket-Protocol

type:string

Authentication credential supplied during the WebSocket handshake. Pass your API key here when your client cannot set an Authorization header for WebSocket connections.

Example: <api_key>

Video (bytes)

Binary video segment sent by the client for analysis. Each segment must be at least 3 seconds long and must not exceed 32MB. Accepts the following formats: mp4, avi, mov, mkv, mpeg-ts, mpeg-2-ts, webm.

Session Config

type:object

Optional caller-supplied session configuration. This message can be sent at any time to update the configuration.

Conversation Quality Updated

type:object

Carries Conversation Quality Index values for the most recently closed cadence period. Emitted at most once per period and only when the caller has set at least one CQI include flag on the session-config message. data.overall is cumulative across the whole session up to the end of the just-closed period and is included whenever include: ["conversation_quality_overall"] was supplied. data.timeline carries a single entry covering the just-closed period and is included whenever include: ["conversation_quality_timeline"] was supplied — periods with no analyzer-reported signals still emit the timeline; its scores reflect any engagement contribution and fall back to all-50 defaults when nothing contributes, so the requested section is always present.

Engagement Updated

type:object

Reports a change in engagement state. Emitted once when engagement is first established for the session, and again only when the detected engagement level differs from the most recently emitted level. data.start uses absolute session-cumulative time.

Error

type:object

Reports an error encountered while processing the stream. data.code carries the machine-readable error id (sub-type), and data.segment identifies the incoming caller segment when the failure maps to a specific chunk (size validation, quota); analysis-time failures that do not map to one chunk carry data.segment: null.

Session Ready

type:object

Acknowledges that the v1 stream session is established. Emitted exactly once per session, immediately after the server accepts the WebSocket handshake. Carries the session-level contract (idle / max-duration timeouts, segment size and duration constraints, supported session-config options) so the caller can adapt its producer side without round-tripping rejections. Sessions that fail to fully establish close without this envelope; a client that has not seen session.ready must assume the session is not ready to receive video.

Session Updated

type:object

Acknowledges that an inbound stream_session_config_v1 text frame was accepted. Carries the consolidated post-apply config (include).

Signal Detected

type:object

Reports that a social signal has transitioned from inactive to active. Emitted once when the signal type is first detected for the session, and again only when the signal becomes active after a prior signal.ended. data.start uses absolute session-cumulative time.

Signal Ended

type:object

Reports that a previously active social signal is no longer active. Emitted when a signal type that was active in the previous analyzed window is not present in the current window. data.end uses absolute session-cumulative time.

Signal Updated

type:object

Reports that an already-active social signal experienced a change in probability. Emitted when an active signal type's probability has changed from the previous value reported for that signal type (either signal.detected or a prior signal.updated). data.start uses absolute session-cumulative time.

Analyze uploaded video Error handling