Web SDK

The Phonely Web SDK provides a TypeScript API for starting voice calls, controlling the microphone, listening for call events, and optionally receiving live transcript updates.

Install the SDK

npm install @phonely-ai/web

This guide describes version 0.0.8.

Keep authentication on your server

Your browser must not receive your Phonely API key. Instead:

The browser asks your application server to start a call.
Your server authenticates the user and confirms that they may access the requested agent.
Your server requests a short-lived web call session from Phonely using the API key.
Your server returns the session bundle to the browser.
The SDK uses that bundle to join the call.

Never include a Phonely API key in browser code, browser storage, URLs, screenshots, or client-visible logs.

Your server starts the short-lived session through Phonely:

POST https://db.phonely.ai/api/agents/{agent_id}/web-call-session
X-Authorization: YOUR_API_KEY
Content-Type: application/json

Send an empty JSON object, or include the optional call metadata:

{
  "metadata": {}
}

The response contains the values the browser SDK needs:

type WebCallStartResponse = {
  callId: string;
  webCallUrl: string;
  meetingToken: string;
  phonelyToken: string;
  expiresAt?: string;
  transcriptUrl?: string;
};

Return only this short-lived response to the browser. If Phonely provides an environment-specific API base URL for your account, use that URL instead.

Configure the browser client

Set webCallStartEndpoint to a server route in your own application:

import PhonelySDK, { PhonelyEvent } from "@phonely-ai/web";

const phonely = new PhonelySDK({
  webCallStartEndpoint: "/api/web-call/start",
});

phonely.on(PhonelyEvent.CALL_JOINED, () => {
  console.log("Call joined");
});

const callId = await phonely.call({ agentId: "YOUR_AGENT_ID" });

The SDK sends the following body to your route:

{
  agentId: string;
  metadata?: Record<string, unknown>;
}

Your route must return the short-lived session response produced by Phonely. If your application uses a custom authentication flow, provide createWebCallStart instead of webCallStartEndpoint.

Pass runtime variables

If a flow uses runtime variables, pass their IDs and values through metadata.callOverrides.liveVariables:

await phonely.call({
  agentId: "YOUR_AGENT_ID",
  metadata: {
    callOverrides: {
      liveVariables: [
        {
          uuid: "RUNTIME_VARIABLE_ID",
          value: "VALUE_FOR_THIS_CALL",
        },
      ],
    },
  },
});

The uuid must match the runtime variable ID configured in the flow.

Use live transcripts

Enable transcript polling when the browser needs live caller and agent messages:

const phonely = new PhonelySDK({
  webCallStartEndpoint: "/api/web-call/start",
  transcript: {
    enabled: true,
    autoStart: true,
    includeRoles: ["user", "assistant"],
  },
});

phonely.on(PhonelyEvent.TRANSCRIPT_MESSAGE, ({ message }) => {
  console.log(message.content);
});

Transcript access uses the short-lived transcript URL and token returned for the call. clearTranscript() clears only the SDK’s in-memory copy; it does not delete stored call data.

Common methods

Method	Purpose
`call(options)`	Start a call and return its call ID
`endCall()`	End the active call
`setAudioEnabled(enabled)`	Mute or unmute local audio
`sendMessage(content)`	Send an application message to the call
`getParticipants()`	Read the current participants
`startTranscript()`	Start transcript polling
`stopTranscript()`	Stop transcript polling
`getTranscript()`	Read transcript messages held in memory
`clearTranscript()`	Clear transcript messages held in memory

Use on(event, handler) and off(event, handler) to manage event listeners. The exported PhonelyEvent enum includes call lifecycle, participant, message, volume, speech, transcript, progress, and error events.

End the call

await phonely.endCall();

End the active call before starting another one with the same SDK instance.

Agent Generation

Agent Management

Call Management

Knowledge Base

Voice & Phone

Organizations

Install the SDK

Keep authentication on your server

Configure the browser client

Pass runtime variables

Use live transcripts

Common methods

End the call

​Install the SDK

​Keep authentication on your server

​Configure the browser client

​Pass runtime variables

​Use live transcripts

​Common methods

​End the call

Install the SDK

Keep authentication on your server

Configure the browser client

Pass runtime variables

Use live transcripts

Common methods

End the call