Authentication and Session Flow

Build a React component that signs in, creates an ambient session with encounterId, and controls recording with sessionStatus and local phase state

This example shows how to sign in, create an ambient session, and record in one component. First sign in. Then create a session with an encounterId. Then start recording.

Use sessionStatus for the session lifecycle, such as created or submitted.

Do not use sessionStatus for recording versus paused. Keep a local phase value for your start, pause, and resume buttons.

Code example

React

import { useState, useEffect } from 'react';
import { useAuth, useAmbient, useAmbientSession } from '@suki-sdk/platform-react';

function SukiRecorder() {
  const [sessionId, setSessionId] = useState(null);
  // sessionStatus does not include "recording" or "paused". Track those locally.
  const [phase, setPhase] = useState('idle'); // 'idle' | 'recording' | 'paused'

  // Step 1: Authenticate
  const { isLoggedIn, isPending: authPending } = useAuth({
    partnerId: 'your-partner-id',// Required
    partnerToken: 'your-partner-token',// Required
    autoRegister: true, // Required for auto-registration
    loginOnMount: true, // Optional
    providerName: 'Dr. John Doe', // Required for auto-registration
    providerOrgId: 'org-123', // Required for auto-registration
    providerSpecialty: 'FAMILY_MEDICINE' // Required for auto-registration
  });

  // Step 2: Create session (encounterId is required)
  const {
    ambientSessionId,
    session: { create, isSuccess: sessionCreated }
  } = useAmbient();

  useEffect(() => {
    if (isLoggedIn && !sessionCreated) {
      create({ encounterId: 'your-encounter-id' });
    }
  }, [isLoggedIn, sessionCreated, create]);

  useEffect(() => {
    if (ambientSessionId) {
      setSessionId(ambientSessionId);
    }
  }, [ambientSessionId]);

  // Step 3: Manage recording
  const {
    start,
    pause,
    resume,
    submit,
    sessionStatus,
    sessionType,
    setSessionContext
  } = useAmbientSession({
    ambientSessionId: sessionId
  });

  async function handleStart() {
    await start();
    setPhase('recording');
    await setSessionContext({
      patient: { dob: '1980-01-15', sex: 'M' },
      provider: { specialty: 'FAMILY_MEDICINE', role: 'Attending Physician' },
      visit: {
        visit_type: 'Follow-up',
        encounter_type: 'Office Visit',
        reason_for_visit: 'Medication review'
      }
    });
  }

  async function handlePause() {
    await pause();
    setPhase('paused');
  }

  async function handleResume() {
    await resume();
    setPhase('recording');
  }

  if (authPending) {
    return <div>Authenticating...</div>;
  }

  if (!isLoggedIn) {
    return <div>Please sign in</div>;
  }

  if (!sessionId) {
    return <div>Creating session...</div>;
  }

  return (
    <div>
      <h2>Session status: {sessionStatus}</h2>
      {sessionType === 'offline' && (
        <p>Session will sync when online</p>
      )}

      {sessionStatus === 'created' && phase === 'idle' && (
        <button type="button" onClick={handleStart}>Start Recording</button>
      )}

      {sessionStatus === 'created' && phase === 'recording' && (
        <>
          <button type="button" onClick={handlePause}>Pause</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}

      {sessionStatus === 'created' && phase === 'paused' && (
        <>
          <button type="button" onClick={handleResume}>Resume</button>
          <button type="button" onClick={submit}>Submit</button>
        </>
      )}
    </div>
  );
}

Key implementation details

Step 1: Authentication

Use useAuth to sign in. With autoRegister: true and loginOnMount: true, sign-in runs on mount. Pass providerName, providerOrgId, and providerSpecialty when auto-registration is on. Prefer specialty enum tokens such as FAMILY_MEDICINE. See Authentication hook.

Step 2: Session Creation

Call session.create({ encounterId }) only after the user is signed in. encounterId is required. Wait for isSuccess before you use ambientSessionId. See Create ambient session.

Step 3: Recording

Pass ambientSessionId into useAmbientSession. Use start, pause, resume, and submit. Use sessionStatus for lifecycle state, and a local phase for recording versus paused. See Manage ambient session.

Always wait for isSuccess before you use ambientSessionId. An undefined session id breaks useAmbientSession.

Next steps

Refer to the Manage ambient session guide to add session context and improve note quality.