Embed browser API
The embed script calls these routes from the visitor's browser. Use them only if you build your own talk button; the script does all of this for you. They take no API key. Each request must come from one of the embed's allowed origins, and requests that control a conversation must carry its private endToken.
Base URL: https://in-api.zlicx.ai/api/v1. Every response is wrapped as { success, message, data }; errors use { success: false, code, message }.
CORS and origins
zlicx answers browser requests only from the embed's allowed origins, including on errors, so your page can read the message. A request from any other origin gets 403. Allowed methods are GET, POST, and OPTIONS; the only allowed request header is Content-Type.
GET /public/embeds/:embedId
The embed's public settings. Returns 404 if the embed is off or its agent is not ready.
{
"embedId": "wgt_...",
"name": "Support line",
"agentName": "Asha",
"theme": { "primaryColor": "#902986", "position": "bottom-right", "...": "..." },
"consentRequired": true,
"consentText": "This voice call may be recorded and transcribed.",
"sessionTtlSeconds": 900
}POST /public/embeds/:embedId/conversations
Starts a conversation. Ask for the microphone before this call, so a refused permission does not use up the visitor's allowance.
{ "visitorId": "optional anonymous ID, up to 120 characters" }Connect with plain WebRTC through the SDP route below. The transport field is always "engine".
{
"transport": "engine",
"conversationId": "wgs_...",
"endToken": "keep this private",
"roomName": "widget_wgs_...",
"expiresAt": "2026-11-03T10:15:00.000Z",
"iceServers": [
{ "urls": ["stun:stun.l.google.com:19302"] },
{ "urls": ["turn:turn.example.com:3478?transport=udp"], "username": "1793...:a1b2", "credential": "..." }
]
}Errors:
404: the embed is off or does not exist.402: the account has no credit.429: too many conversations from this visitor, or the embed is at its limit of calls at once.503: the voice service is unavailable; try again.
POST /public/embeds/:embedId/conversations/:conversationId/sdp
Send the browser's WebRTC offer and get the voice engine's answer. The engine does not use trickle ICE: wait until ICE gathering is complete (or about 3 seconds) so every candidate is in the offer. Each conversation accepts one offer.
{ "endToken": "...", "sdp": "v=0\r\no=- ..." }{
"legId": "2c973971-...",
"sdp": "v=0\r\no=- ...",
"candidates": [{ "candidate": "candidate:1 1 udp ...", "sdpMid": "0", "sdpMLineIndex": 0 }]
}Apply the answer with setRemoteDescription, then add each candidate. The agent starts speaking as soon as the media connection is up.
const pc = new RTCPeerConnection({ iceServers: conversation.iceServers });
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
mic.getAudioTracks().forEach((track) => pc.addTrack(track, mic));
pc.ontrack = (event) => { audio.srcObject = event.streams[0]; };
await pc.setLocalDescription(await pc.createOffer());
await waitForIceGatheringComplete(pc); // up to ~3 seconds
const res = await fetch(`${api}/public/embeds/${embedId}/conversations/${conversation.conversationId}/sdp`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ endToken: conversation.endToken, sdp: pc.localDescription.sdp }),
});
const { data } = await res.json();
await pc.setRemoteDescription({ type: "answer", sdp: data.sdp });
for (const candidate of data.candidates) await pc.addIceCandidate(candidate);Errors:
404: wrongendToken, or the conversation ended or expired.400: the conversation is already connected, or the SDP is not an offer.403: the request came from an origin that is not allowed.
POST /public/embeds/:embedId/conversations/:conversationId/end
Hangs up the call. Send it when the visitor ends the call or leaves the page. Ending a conversation that already ended does nothing.
{ "endToken": "..." }{ "status": "ended", "roomName": "widget_wgs_..." }The call log is written shortly after the call ends, once the transcript is complete and any recording has finished uploading.
Related
- Web embed guide
- REST API for creating and changing embeds with an API key.

