Run a FormBharo Voice Call Directly from Your Web Page

You can embed a FormBharo voice call directly in your web page using WebRTC. The call opens an audio connection to the agent, which asks questions out loud. You poll a key-less endpoint to read the answers as they come in.

Before you start

You need two things: the agent ID for the agent you want to run, and the URL of your FormBharo server. Before the call begins, fetch the agent’s public profile with GET /api/v1/agents/{agent_id}/public. This route requires no API key, so you can call it safely from the browser. It returns the agent’s title, its questions list, and an agent_speaks_first flag — enough to render a form UI or a progress indicator before the audio connection is open.

curl

curl {FORMBHARO_URL}/api/v1/agents/AGENT_ID/public

Use agent_speaks_first to decide whether to show a “waiting for agent” state or a push-to-talk prompt when the call first connects.

Run the call

Generate a conversation ID

Create a unique conversation ID in your browser before opening the connection. FormBharo uses whatever ID you provide — it does not generate one for you.

javascript

const conversationId = crypto.randomUUID();

Store this value — you’ll pass it to the WebRTC offer and use it later to poll for answers.

Open the audio connection

Send a POST /offer request to start the WebRTC handshake. Note that this path is at the bare root of the server — it is not under /api/v1 — and it requires no API key.Send a JSON body with three fields:

Field	Value
`sdp`	Your browser’s WebRTC SDP offer string
`type`	Always `"offer"`
`request_data`	Object with `agentId` and `conversation_id`

The response is a WebRTC SDP answer. Use it to complete the peer connection on the browser side.To exchange ICE candidates after the initial handshake, send them with PATCH /offer.

javascript

// Step 1: Generate a conversation ID
const conversationId = crypto.randomUUID();

// Step 2: Create a peer connection and generate an SDP offer
const pc = new RTCPeerConnection();

pc.addTransceiver("audio", { direction: "sendrecv" });

await pc.setLocalDescription(await pc.createOffer());

// Wait for ICE gathering to complete
await new Promise((resolve) => {
  if (pc.iceGatheringState === "complete") {
    resolve();
  } else {
    pc.addEventListener("icegatheringstatechange", () => {
      if (pc.iceGatheringState === "complete") resolve();
    });
  }
});

// Step 3: Send the offer to FormBharo
const offerResponse = await fetch(
  "{FORMBHARO_URL}/offer",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      sdp: pc.localDescription.sdp,
      type: "offer",
      request_data: {
        agentId: "AGENT_ID",
        conversation_id: conversationId,
      },
    }),
  }
);

const answer = await offerResponse.json();

// Step 4: Apply the SDP answer to complete the handshake
await pc.setRemoteDescription(new RTCSessionDescription(answer));

// Play incoming audio
pc.addEventListener("track", (event) => {
  const audio = new Audio();
  audio.srcObject = event.streams[0];
  audio.play();
});

Read answers as they arrive

Poll GET /api/v1/data/{agent_id}/{conversation_id} every two seconds or so to read answers as the agent collects them. This route requires no API key.

Before the first answer is written, the endpoint returns an empty object {}.
Once the call is underway, it returns a form_data object (keyed by question ID) and a form_status string.

javascript

async function pollAnswers(agentId, conversationId) {
  const url = `{FORMBHARO_URL}/api/v1/data/${agentId}/${conversationId}`;

  const interval = setInterval(async () => {
    const res = await fetch(url);
    const data = await res.json();

    if (data.form_status === "complete" || data.form_status === "screened_out") {
      clearInterval(interval);
    }

    console.log("Current answers:", data.form_data);
  }, 2000);
}

Anyone who knows the agent ID can read or overwrite live answers through the open routes. If your agents collect sensitive data, put your own authentication layer in front of these routes at the infrastructure level.

See Answers for details on reading form_data and form_status, including why you should never rely on truthiness alone when checking answer values.

Get Started

Core Concepts

Guides

Reference

Run a FormBharo Voice Call Directly from Your Web Page

Before you start

Run the call

​Before you start

​Run the call

Before you start

Run the call