createInteraction()

Reference for the Embedded API createInteraction() method.

Use createInteraction() to create a new interaction session before navigating into it or starting recording.

Applies to Web Component, Window API, and PostMessage. Examples on this page use the Web Component API shape.

Usage

const interaction = await api.createInteraction({
  assignedUserId: null,
  encounter: {
    identifier: `encounter-${Date.now()}`,
    status: "planned",
    type: "first_consultation",
    period: {
      startedAt: new Date().toISOString(),
    },
    title: "Initial Consultation",
  },
});

Prerequisites

• User must be authenticated.

Input validation

• encounter.identifier: Required, non-empty string.
• encounter.status: Must be one of "planned", "in-progress", "completed", or "cancelled".
• encounter.type: Must be one of the supported encounter types.
• encounter.period.startedAt: Required ISO 8601 datetime string.
• encounter.title: Optional string.
• assignedUserId: Optional string or null.

Possible errors

• UNAUTHORIZED: User not authenticated.
• INVALID_PAYLOAD: Missing required fields, invalid encounter status or type, or invalid date format.
• INTERNAL_ERROR: Failed to create interaction.

Returns

{
  id: string,
  createdAt: string,
  status?: string
}

Notes

• Create the interaction before calling startRecording().

Related reference

• API Reference Overview
• addFacts()
• startRecording()