Build Full-Stack APP To Capture Ambient Notes

What you will build

35 min | Intermediate

A Go backend that keeps Partner Token and Suki Token on the server.
An Ambient visit flow you can run yourself: create session, attach context, stream PCM, end, and retrieve the note.
Working Go examples for every Ambient REST and WebSocket step you need.

Using an AI coding tool?Copy the prompt below to point your agent at the Ambient and audio streaming skills and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Ambient and audio streaming skills and connect the documentation MCP.

Open in Cursor

Agenda

In this tutorial, you learn how to implement Suki Ambient APIs in Go and run one ambient session from start to finish. You will learn how to:

Authenticate with Partner ID and Partner Token, and keep tokens on the server.
Create an ambient session and attach provider, patient, visit, and note section context.
Open wss://…/ws/stream, send START_TIME, stream LINEAR16 PCM as JSON audio frames, and end with RU9G.
End the session over REST, poll status, then retrieve content, transcript, and structured data.
Optionally set note style with user preferences and submit note feedback.

Go through each step, copy the code examples into your product, and follow the same API sequence in your product.

The sample is not a public GitHub repo. Use the file explorer below to browse the code, or click Run locally to download a zip. Credentials are not included. Copy the patterns you need into your own backend.

By the end, you can map which Ambient APIs to call, in which order, with working Go code for each step.

What you build

You build a small clinic UI inside a Go application. The browser never calls Suki directly. Your Go server holds credentials, opens Ambient sessions, and forwards microphone PCM to Suki. This tutorial covers only the Ambient Partner API path in the steps below. Clinic schedule UI, Dictation, and a fake EHR send are also in the sample. Browse the full partner sample in the explorer.

Browse the sample project

Use the sidebar in the explorer to open files from the ambient-api-starter sample. Partner credentials are not included. Use .env.example as the template. Run locally downloads a zip you unzip and run with Go on your machine (it cannot run inside the browser).

Ambient APIs used for this tutorial

Step	Method and path
Login	`POST /api/v1/auth/login`
Register provider (once)	`POST /api/v1/auth/register`
Create ambient session	`POST /api/v1/ambient/session/create`
Attach context	`POST /api/v1/ambient/session/{id}/context`
Stream audio	`WSS /ws/stream` (`AUDIO` frames, end marker `RU9G`)
End session	`POST /api/v1/ambient/session/{id}/end`
Poll status	`GET /api/v1/ambient/session/{id}/status`
Get note content	`GET /api/v1/ambient/session/{id}/content`
Get transcript	`GET /api/v1/ambient/session/{id}/transcript`
Get structured data	`GET /api/v1/ambient/session/{id}/structured-data` and `GET /api/v1/ambient/note/{id}/structured-data`
Note section catalog	`GET /api/v1/info/loincs`
Note style	`PATCH /api/v1/user/preferences`
Note feedback	`POST /api/v1/ambient/session/{id}/content/feedback`

Staging hosts you use while you learn:

Protocol	Host
REST	`https://sdp.suki-stage.com`
WebSocket	`wss://sdp.suki-stage.com`

When you move to production, switch to https://sdp.suki.ai and wss://sdp.suki.ai. See Ambient API overview.

Architecture

Follow this Ambient visit order in your Go backend:

Best practices you follow in this tutorial

Use these practices as you build your backend.

Practice	What you do	Reference
Keep tokens on the server	Store Partner Token and Suki Token in Go only. Never put them in browser code.	Partner authentication
Capture LINEAR16 PCM at 16 kHz	Send mono 16-bit little-endian PCM in small chunks as base64 JSON frames.	Audio capture best practices
Follow Ambient stream order	Send `START_TIME`, stream `AUDIO`, end with `RU9G`, then call end session.	Ambient audio streaming
Use the Ambient wire format	Use JSON text frames on `/ws/stream`. Do not send binary frames or Dictation markers.	Ambient WebSocket wire format
Attach chart context before audio	Seed patient, visit, and LOINC sections so Suki can write the note.	Session context
Poll status before you fetch the note	Wait for `completed`, then retrieve content, transcript, or structured data.	Retrieve ambient content
Pause with `KEEP_ALIVE`	While Ambient is paused, send `KEEP_ALIVE` so the stream stays open.	Complete an ambient visit

Prerequisites and dependencies

Prerequisites
Dependencies

Before you begin, make sure you have:

Go 1.22+ installed.
Completed Partner onboarding and received staging Partner ID.
Chrome or Edge with microphone permission for a live visit test.

Set these environment variables when you run locally:

Variable	Purpose
`PARTNER_ID`	Your staging Partner ID
`PARTNER_TOKEN`	Your staging Partner Token (server only)
`AUTH_MODE`	`standard`, `bearer`, or `single` as assigned by Suki
`PROVIDER_ID`	Required when `AUTH_MODE` is `bearer` or `single`
`SUKI_BASE_URL`	Defaults to `https://sdp.suki-stage.com`
`SUKI_WS_URL`	Defaults to `wss://sdp.suki-stage.com`

Store Partner Token and Suki Token only on your backend. Never put them in browser JavaScript.

Install and configure these before you run the Ambient path:

Dependency	Why you need it
Go 1.22+	Language for the Partner API client
`github.com/gorilla/websocket`	Ambient `/ws/stream` client
Staging Partner ID and Partner Token	Login and session APIs
16 kHz LINEAR16 mono PCM	Ambient audio format
HTTPS and WSS access to `sdp.suki-stage.com`	Staging REST and streaming

Add the WebSocket client:

go get github.com/gorilla/websocket@v1.5.3

Standard library packages used in the snippets: net/http, encoding/json, encoding/base64, context, fmt, io, sync, time, strings.

Project setup

Create a Go module for your backend.
Add github.com/gorilla/websocket.
Put Partner credentials in a local .env or secret store. Do not commit them.
Plan to send LINEAR16 PCM at 16 kHz, mono, 16-bit little-endian. If your UI captures browser audio, resample to that format before you forward bytes to Suki.

Your backend should have this shape:

package suki

import (
	"net/http"
	"strings"
	"sync"
	"time"
)

type Client struct {
	baseURL      string
	partnerID    string
	partnerToken string
	authMode     string
	providerID   string
	http         *http.Client

	mu        sync.Mutex
	sukiToken string
	tokenAt   time.Time
}

func NewClient(baseURL, partnerID, partnerToken, authMode, providerID string) *Client {
	return &Client{
		baseURL:      strings.TrimRight(baseURL, "/"),
		partnerID:    partnerID,
		partnerToken: partnerToken,
		authMode:     authMode,
		providerID:   providerID,
		http:         &http.Client{Timeout: 60 * time.Second},
	}
}

Tutorial steps

Go through each step in order. Read the explanation, copy the Go example, then continue. Every code block is written in Go and follows the Ambient API path.

Call Login with Partner ID and Partner Token. Send the returned suki_token later as the sdp_suki_token header. If the provider is new, call Register once, then log in again.In the demo UI, clinic sign in stays in the browser. Partner Token stays in .env on the Go server.Code example

func (c *Client) login(ctx context.Context) (string, error) {
var out struct {
	SukiToken string `json:"suki_token"`
}
body := map[string]string{
	"partner_id":    c.partnerID,
	"partner_token": c.partnerToken,
}
if c.providerID != "" {
	body["provider_id"] = c.providerID
}
if err := c.doJSON(ctx, http.MethodPost, c.baseURL+"/api/v1/auth/login", "", body, http.StatusOK, &out); err != nil {
	return "", err
}
if out.SukiToken == "" {
	return "", fmt.Errorf("login response missing suki_token")
}
return out.SukiToken, nil
}

func (c *Client) RegisterThenLogin(ctx context.Context, providerName, providerOrgID string) error {
body := map[string]string{
	"partner_id":      c.partnerID,
	"partner_token":   c.partnerToken,
	"provider_name":   strings.TrimSpace(providerName),
	"provider_org_id": strings.TrimSpace(providerOrgID),
}
if c.providerID != "" {
	body["provider_id"] = c.providerID
}
// 409 Conflict means the provider is already registered.
_ = c.doJSON(ctx, http.MethodPost, c.baseURL+"/api/v1/auth/register", "", body, http.StatusCreated, nil)

token, err := c.login(ctx)
if err != nil {
	return err
}
c.mu.Lock()
c.sukiToken = token
c.tokenAt = time.Now()
c.mu.Unlock()
return nil
}

For every subsequent REST call, set the following headers:

req.Header.Set("Content-Type", "application/json")
req.Header.Set("sdp_suki_token", sukiToken)
if providerID != "" {
req.Header.Set("sdp_provider_id", providerID) // single auth mode
}

Open a Visit from the Clinic UI

Before you create an ambient session, run the sample locally so you have a clinic UI and a patient chart ready.

In the explorer above, click Run locally to download suki-partner-samples.zip.
Unzip the archive, then cd ambient-api-starter.
Copy .env.example to .env and set your staging Partner ID and Partner Token.
Run go run ./cmd/server, then open http://127.0.0.1:8080.
Register or sign in to the demo clinic, open Appointments, and add a walk-in or open a scheduled visit so a patient chart is ready.

The clinic schedule is demo UI only. Suki Ambient does not require a booked calendar slot. Your Go backend still runs the same create session and stream path for a walk-in or a scheduled visit.In the explorer, open ambient-api-starter/internal/suki/client.go to see how login and session helpers are wired before the next steps.

Create an Ambient Session

Call Create ambient session. The response includes ambient_session_id (required for streaming) and often composition_id (useful for note-scoped structured data).

type CreateSessionResult struct {
AmbientSessionID string `json:"ambient_session_id"`
CompositionID    string `json:"composition_id"`
}

func (c *Client) CreateAmbientSession(ctx context.Context) (CreateSessionResult, error) {
token, err := c.Token(ctx)
if err != nil {
	return CreateSessionResult{}, err
}
var out CreateSessionResult
err = c.doJSON(ctx, http.MethodPost, c.baseURL+"/api/v1/ambient/session/create", token, map[string]any{}, http.StatusCreated, &out)
if err != nil {
	return CreateSessionResult{}, err
}
if out.AmbientSessionID == "" {
	return CreateSessionResult{}, fmt.Errorf("create response missing ambient_session_id")
}
return out, nil
}

Attach Session Context

Send provider specialty, patient demographics, visit details, and LOINC note sections with Session context. Suki uses this chart context when writing the note.

type NoteSection struct {
Loinc string `json:"loinc"`
Title string `json:"title,omitempty"`
}

var DefaultSections = []NoteSection{
{Loinc: "10154-3", Title: "Chief Complaint"},
{Loinc: "10164-2", Title: "History of Present Illness"},
{Loinc: "29545-1", Title: "Physical Exam"},
{Loinc: "51847-2", Title: "Assessment and Plan"},
}

func DemoContext(sections []NoteSection) map[string]any {
if len(sections) == 0 {
	sections = DefaultSections
}
return map[string]any{
	"provider": map[string]string{"specialty": "CARDIOLOGY", "provider_role": "ATTENDING"},
	"patient": map[string]any{
		"patient_id": "demo-alex-001",
		"name":       map[string]any{"given": []string{"Alex"}, "family": "Demo"},
		"dob":        "1985-06-15",
		"sex":        "male",
	},
	"visit": map[string]string{
		"chief_complaint":  "Headache",
		"encounter_type":   "AMBULATORY",
		"reason_for_visit": "Follow-up for migraines",
		"visit_type":       "ESTABLISHED_PATIENT",
	},
	"sections": sections,
}
}

func (c *Client) SeedContext(ctx context.Context, ambientSessionID string, payload map[string]any) error {
token, err := c.Token(ctx)
if err != nil {
	return err
}
url := fmt.Sprintf("%s/api/v1/ambient/session/%s/context", c.baseURL, ambientSessionID)
return c.doJSON(ctx, http.MethodPost, url, token, payload, http.StatusOK, nil)
}

Do not put verbosity or section format in session context. Set those with PATCH /api/v1/user/preferences before recording starts.

Open the Ambient WebSocket and Stream PCM

Dial Ambient audio streaming at /ws/stream. Authenticate with HTTP headers from Go (sdp_suki_token, ambient_session_id, and sdp_provider_id when required).On the patient chart in the local demo, start Ambient from the microphone control. The browser sends PCM to your Go server at ws://127.0.0.1:8080/ws/pcm, and Go forwards it to Suki on /ws/stream.While you implement this step:

Keep go run ./cmd/server running from Step 2.
In the explorer, open ambient-api-starter/internal/suki/stream.go (and related session helpers) to match the dial, START_TIME, AUDIO, and RU9G order.
On the chart, start Ambient, speak a short fake visit, then stop. Confirm your server logs show frames forwarding without Partner Token errors.

Send START_TIME first, then base64 PCM chunks in AUDIO frames. Chunk about 3200 bytes (about 100 ms of 16 kHz mono 16-bit). Keep sending audio at least every 25 seconds, or send KEEP_ALIVE while paused.

const chunkBytes = 3200 // ~100 ms of 16 kHz mono 16-bit PCM

type Stream struct {
mu   sync.Mutex
conn *websocket.Conn
}

func (c *Client) DialStream(sukiToken, ambientSessionID, wsHost string) (*Stream, error) {
hdr := http.Header{}
hdr.Set("sdp_suki_token", sukiToken)
hdr.Set("ambient_session_id", ambientSessionID)
if pid := c.ProviderID(); pid != "" {
	hdr.Set("sdp_provider_id", pid)
}
conn, resp, err := websocket.DefaultDialer.Dial(wsHost+"/ws/stream", hdr)
if err != nil {
	if resp != nil {
		b, _ := io.ReadAll(resp.Body)
		resp.Body.Close()
		return nil, fmt.Errorf("WebSocket connect failed: %w; body=%s", err, string(b))
	}
	return nil, err
}
rfc3339 := time.Now().UTC().Format("2006-01-02T15:04:05Z")
if err := conn.WriteJSON(map[string]any{
	"type": "START_TIME",
	"data": base64.StdEncoding.EncodeToString([]byte(rfc3339)),
}); err != nil {
	conn.Close()
	return nil, fmt.Errorf("send START_TIME: %w", err)
}
return &Stream{conn: conn}, nil
}

func (s *Stream) SendPCM(pcm []byte) error {
s.mu.Lock()
defer s.mu.Unlock()
for i := 0; i < len(pcm); i += chunkBytes {
	end := i + chunkBytes
	if end > len(pcm) {
		end = len(pcm)
	}
	if err := s.conn.WriteJSON(map[string]any{
		"type": "AUDIO",
		"data": base64.StdEncoding.EncodeToString(pcm[i:end]),
	}); err != nil {
		return err
	}
}
return nil
}

func (s *Stream) SendEvent(event string) error {
s.mu.Lock()
defer s.mu.Unlock()
return s.conn.WriteJSON(map[string]any{"type": "EVENT", "event": event})
}

func (s *Stream) EndAudio() error {
s.mu.Lock()
defer s.mu.Unlock()
return s.conn.WriteJSON(map[string]any{"type": "AUDIO", "data": "RU9G"})
}

Pause and resume use stream events (same session):

_ = stream.SendEvent("PAUSE")
_ = stream.SendEvent("KEEP_ALIVE") // every about 4 to 5 seconds while paused
_ = stream.SendEvent("RESUME")

End the Session and Poll for the Note

When the visit stops, send the ambient end marker RU9G, close the WebSocket, then call End ambient session. Poll Session status until completed, then fetch content.

func (c *Client) EndSession(ctx context.Context, ambientSessionID string) error {
token, err := c.Token(ctx)
if err != nil {
	return err
}
url := fmt.Sprintf("%s/api/v1/ambient/session/%s/end", c.baseURL, ambientSessionID)
return c.doJSON(ctx, http.MethodPost, url, token, nil, http.StatusOK, nil)
}

func (c *Client) Status(ctx context.Context, ambientSessionID string) (string, error) {
token, err := c.Token(ctx)
if err != nil {
	return "", err
}
var out struct {
	Status string `json:"status"`
}
url := fmt.Sprintf("%s/api/v1/ambient/session/%s/status", c.baseURL, ambientSessionID)
if err := c.doJSON(ctx, http.MethodGet, url, token, nil, http.StatusOK, &out); err != nil {
	return "", err
}
return out.Status, nil
}

func (c *Client) Content(ctx context.Context, ambientSessionID string) (any, error) {
return c.getOK(ctx, fmt.Sprintf("%s/api/v1/ambient/session/%s/content?cumulative=false", c.baseURL, ambientSessionID))
}

func (c *Client) Transcript(ctx context.Context, ambientSessionID string) (any, error) {
return c.getOK(ctx, fmt.Sprintf("%s/api/v1/ambient/session/%s/transcript", c.baseURL, ambientSessionID))
}

func (c *Client) SessionStructuredData(ctx context.Context, ambientSessionID string) (any, error) {
return c.getOK(ctx, fmt.Sprintf("%s/api/v1/ambient/session/%s/structured-data", c.baseURL, ambientSessionID))
}

End the stream and poll for results like this:

_ = stream.EndAudio() // RU9G
stream.Close()
if err := client.EndSession(ctx, ambientSessionID); err != nil {
return err
}
for {
status, err := client.Status(ctx, ambientSessionID)
if err != nil {
	return err
}
switch status {
case "completed":
	note, _ := client.Content(ctx, ambientSessionID)
	transcript, _ := client.Transcript(ctx, ambientSessionID)
	structured, _ := client.SessionStructuredData(ctx, ambientSessionID)
	_, _, _ = note, transcript, structured
	return nil
case "failed", "skipped", "aborted":
	return fmt.Errorf("ambient session ended with status %s", status)
}
time.Sleep(2 * time.Second)
}

Very short recordings are often skipped. When you test Ambient note generation, aim for about one minute of clinical speech.

Optional: Note Style and Feedback

Set verbosity and section format with User preferences before you start recording. After the note is ready, submit a 1 to 5 rating with content feedback.

func (c *Client) UpdatePreferences(ctx context.Context, verbosity, sectionStyle string) error {
payload := map[string]any{
	"personalization_preference": map[string]any{
		"verbosity": verbosity, // CONCISE | BALANCED | DETAILED
		"section_format": []map[string]string{
			{"loinc": "10164-2", "style": sectionStyle}, // NARRATIVE | BULLETED
			{"loinc": "51847-2", "style": sectionStyle},
		},
	},
}
token, err := c.Token(ctx)
if err != nil {
	return err
}
return c.doJSON(ctx, http.MethodPatch, c.baseURL+"/api/v1/user/preferences", token, payload, http.StatusOK, nil)
}

func (c *Client) SubmitContentFeedback(ctx context.Context, ambientSessionID string, rating int, comments string) error {
token, err := c.Token(ctx)
if err != nil {
	return err
}
body := map[string]any{
	"ratingFeedback": map[string]any{
		"min_rating": 1,
		"max_rating": 5,
		"rating":     rating,
	},
}
if comments != "" {
	body["qualitative_comments"] = comments
}
url := fmt.Sprintf("%s/api/v1/ambient/session/%s/content/feedback", c.baseURL, ambientSessionID)
return c.doJSON(ctx, http.MethodPost, url, token, body, http.StatusCreated, nil)
}

Full Ambient start flow

Use one function to run the start path: login, create the session, attach context, then open the WebSocket stream.

func StartAmbientVisit(ctx context.Context, client *Client, wsHost string, chart map[string]any) (ambientSessionID string, stream *Stream, err error) {
	if err := client.Login(ctx); err != nil {
		return "", nil, err
	}
	created, err := client.CreateAmbientSession(ctx)
	if err != nil {
		return "", nil, err
	}
	payload := DemoContext(DefaultSections)
	// Overlay patient and visit fields from your EHR chart when present.
	if chart != nil {
		if visit, ok := chart["visit"].(map[string]any); ok {
			payload["visit"] = visit
		}
		if patient, ok := chart["patient"].(map[string]any); ok {
			payload["patient"] = patient
		}
	}
	if err := client.SeedContext(ctx, created.AmbientSessionID, payload); err != nil {
		_ = client.EndSession(ctx, created.AmbientSessionID)
		return "", nil, err
	}
	token, err := client.Token(ctx)
	if err != nil {
		_ = client.EndSession(ctx, created.AmbientSessionID)
		return "", nil, err
	}
	stream, err = client.DialStream(token, created.AmbientSessionID, wsHost)
	if err != nil {
		_ = client.EndSession(ctx, created.AmbientSessionID)
		return "", nil, err
	}
	return created.AmbientSessionID, stream, nil
}

In a UI-backed demo, the browser can send mic PCM to your local Go process over ws://127.0.0.1:8080/ws/pcm. Your Go process then calls stream.SendPCM(pcm) toward Suki. Capture audio any way your product needs, as long as the bytes you send to /ws/stream are LINEAR16 PCM.

How this tutorial was tested

This tutorial is tested on the following:

Go 1.22+ on macOS
Staging endpoints https://sdp.suki-stage.com and wss://sdp.suki-stage.com
Local server start with go run ./cmd/server on http://127.0.0.1:8080
Partner ID and Partner Token from a staging partner account in local .env
Demo clinic register or sign in in Chrome
Ambient visit on the patient chart: start recording, stream microphone PCM through the Go server, stop, poll status, and retrieve note content
Fake clinical speech only (do not record real patients)

Common mistakes

Mistake	What to do instead
Putting Partner Token in the browser	Keep Partner Token and Suki Token on the Go server only
Mixing Ambient and Dictation frames	Ambient uses `/ws/stream` and `RU9G`. Dictation uses `/ws/transcribe` and `AUDIO_END`
Sending binary WebSocket frames	Send JSON text frames with base64 PCM in `data`
Skipping context	Attach patient and visit context before you stream
Ending without `RU9G`	Send `AUDIO` with `data: "RU9G"` before you close the socket and call end
Expecting a note from a few seconds of audio	Record closer to one minute for Ambient note generation

Next steps

Build an ambient streaming client - End-to-end login, stream, and retrieve in another tutorial. Ambient audio streaming - /ws/stream order, auth headers, and chunking. Retrieve ambient content - Load note sections, transcript, and structured data after completed. Partner authentication - Keep Partner Token and Suki Token on the server. Create ambient session - Request and response fields for session create.

Streaming

SDKs

Webhook

Build Full-Stack APP To Capture Ambient Notes

Agenda

What you build

Browse the sample project

Ambient APIs used for this tutorial

Architecture

Best practices you follow in this tutorial

Prerequisites and dependencies

Project setup

Tutorial steps

Full Ambient start flow

How this tutorial was tested

Common mistakes

Next steps

​Agenda

​What you build

​Browse the sample project

​Ambient APIs used for this tutorial

​Architecture

​Best practices you follow in this tutorial

​Prerequisites and dependencies

​Project setup

​Tutorial steps

​Full Ambient start flow

​How this tutorial was tested

​Common mistakes

​Next steps

Agenda

What you build

Browse the sample project

Ambient APIs used for this tutorial

Architecture

Best practices you follow in this tutorial

Prerequisites and dependencies

Project setup

Tutorial steps

Full Ambient start flow

How this tutorial was tested

Common mistakes

Next steps