Run a call

No API key is needed to run a call. POST /api/v1/conversations gives you a conversation id and a token; the token authorizes the audio connection and the answer poll for that one conversation.

Before you start

You need the agent ID of a published agent. GET /api/v1/agents/{agent_id}/public returns the agent’s title, questions list, and agent_speaks_first flag. Use it to render your form UI before the call starts.

curl

curl https://api.formbharo.artpark.ai/api/v1/agents/AGENT_ID/public

agent_speaks_first tells you whether to show a “waiting for agent” state or a push-to-talk prompt on connect.

Run the call

Create the conversation

The server generates the conversation id and returns the token with it.

javascript

const res = await fetch("https://api.formbharo.artpark.ai/api/v1/conversations", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ agent_id: "AGENT_ID" }),
});
const { conversation_id, token } = await res.json();

The token expires after 12 hours and works only for this conversation.

Open the audio connection

POST /offer starts the WebRTC handshake. This path sits at the bare root of the server, not under /api/v1.Send a JSON body with these fields:

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

The response is a WebRTC SDP answer. To exchange ICE candidates after the initial handshake, send them with PATCH /offer.

javascript

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();
    });
  }
});

const offerResponse = await fetch("https://api.formbharo.artpark.ai/offer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    sdp: pc.localDescription.sdp,
    type: "offer",
    request_data: {
      agentId: "AGENT_ID",
      conversation_id,
      conversation_token: token,
    },
  }),
});

const answer = await offerResponse.json();

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, sending the token as X-Conversation-Token.The response has form_data (answers keyed by question name) and form_status (per-question: empty, skipped, or answered). When the call ends, ended_at appears.

javascript

function pollAnswers(agentId, conversationId, token) {
  const url = `https://api.formbharo.artpark.ai/api/v1/data/${agentId}/${conversationId}`;

  const interval = setInterval(async () => {
    const res = await fetch(url, {
      headers: { "X-Conversation-Token": token },
    });
    const data = await res.json();

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

    if (data.ended_at) {
      clearInterval(interval);
    }
  }, 2000);
}

Next steps

Poll for calls

Read form_data and form_status after a call ends

Agent config schema

See the full shape of an agent’s JSON config

Get Started

Guides

Reference

Before you start

Run the call

Next steps

Poll for calls

Agent config schema

​Before you start

​Run the call

​Next steps

Poll for calls

Agent config schema

Before you start

Run the call

Next steps