SYNCLI DEVELOPER PORTAL

Quick Reference

Authentication

Authorization: Bearer syncli_...
      

Accepts Session JWT, syncli_... API keys, or legacy sk-... keys.

Base URL

https://apivoice.syncli.cloud/v1
      

HTTP API

GET  /v1/models                        # List available models
POST /v1/chat/completions            # Text chat completion
GET  /api/v1/api-keys                # Manage API keys
POST /api/v1/api-keys
GET  /v1/mcp/servers               # MCP server config
POST /v1/mcp/servers
DELETE /v1/mcp/servers/{id}
      

Chat Completion Example

POST /v1/chat/completions
{
  "model": "syncli-voice",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": false
}
      

Voice (WebRTC)

Step 1: POST /start
  Authorization: Bearer syncli_...
  Body {
    end_user_session_id,   // required for API embeds — see section below
    chat_id,               // optional — reuse from prior /start response
    end_user_email,        // optional — when tracking mode uses email
    client_timezone,
    client_timestamp,
    agent_config           // optional — per-session agent behaviour (see below)
  }
  Response {
    sessionId,             // use in Step 5 URL
    chat_id,               // persist in localStorage for return visits
    iceServers[],
    iceTransportPolicy
  }

Step 2: Create RTCPeerConnection
  pc = new RTCPeerConnection({
    iceServers,
    iceTransportPolicy: 'relay'
  })

Step 3: Attach mic audio (full-duplex — keep mic open while bot speaks)
  // Retrieve mobile-optimized constraints via SyncliVoiceAudio helper
  const voiceConstraints = SyncliVoiceAudio.getVoiceAudioConstraints()
  localStream = await getUserMedia(voiceConstraints)
  const transceiver = pc.addTransceiver('audio', { direction: 'sendrecv' })
  await transceiver.sender.replaceTrack(localStream.getAudioTracks()[0])
  // Play remote bot audio (pc.ontrack → audio element) for browser AEC
  // Do NOT mute mic on bot-started-speaking — barge-in needs continuous uplink

Step 4: Create data channel & AEC warmup notifier
  const dc = pc.createDataChannel('chat', { ordered: true })
  const aecWarmup = SyncliVoiceAudio.createAecWarmupNotifier(dc)
  dc.onopen = () => { if (aecWarmup) aecWarmup.onDataChannelOpen(); }
  // On pc.ontrack play remote audio track, trigger:
  // audioEl.play().then(() => { if (aecWarmup) aecWarmup.onRemoteAudioPlaying(); })
  // Chat UI: ignore bot-output; display bot-output-raw only

Step 5: Offer → Answer exchange
  offer  = await pc.createOffer()
  await pc.setLocalDescription(offer)
  answer = await POST /sessions/{sessionId}/api/offer
    Body {
      sdp, type,
      request_data: {
        end_user_session_id,  // same value as /start
        chat_id,
        client_timezone,
        client_timestamp
      }
    }
  await pc.setRemoteDescription(
    new RTCSessionDescription(answer)
  )

Step 6: ICE candidates
  Buffer candidates until pc_id is known,
  then PATCH /sessions/{id}/api/offer
  Body: { pc_id, candidates: [...] }
      

👤 End-user session ID (embedded voice)

When you embed Syncli voice on your website with an API key, every visitor must be identified by a stable end_user_session_id that your frontend generates and sends on POST /start. This is separate from the gateway sessionId returned in the response (that ID is per WebRTC call).

Without end_user_session_id, the gateway falls back to the client IP address. Multiple visitors behind the same NAT or corporate network would share one caller profile, chat history, rate-limit bucket, and webhook identity.

What it enables

• Per-browser visitor tracking (matches your Rate Capping → Tracking Mode setting, e.g. browser)
• Stable chat_id across reconnects so the agent remembers prior conversation
• Correct resolved_tracking_key and is_returning_user in post-call webhooks
• Isolated usage limits per end user instead of per IP

1. Generate and persist a browser session ID

Create a UUID once per browser profile and store it in localStorage (or your own auth/session store). Reuse the same value on every call and reconnect from that browser.

function getBrowserSessionId() {
  const key = 'syncli_browser_session_id';
  let id = localStorage.getItem(key);
  if (!id) {
    id = (crypto.randomUUID && crypto.randomUUID())
      || ('bs_' + Date.now() + '_' + Math.random().toString(36).slice(2));
    localStorage.setItem(key, id);
  }
  return id;
}
      

If your app already has a logged-in user, you may use your own stable ID instead (e.g. user_abc123 or a session token), as long as it is unique per end user and consistent across visits.

2. Send on POST /start

const startRes = await fetch('https://apivoice.syncli.cloud/start', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer syncli_YOUR_API_KEY'
  },
  body: JSON.stringify({
    end_user_session_id: getBrowserSessionId(),
    chat_id: localStorage.getItem('syncli_voice_chat_id') || null,
    end_user_email: loggedInUser?.email || null,  // optional
    client_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    client_timestamp: new Date().toISOString()
  })
});

const startData = await startRes.json();
// Persist chat_id for the next visit / reconnect
if (startData.chat_id) {
  localStorage.setItem('syncli_voice_chat_id', startData.chat_id);
}
const { sessionId, iceServers, iceTransportPolicy } = startData;
      

3. Send again in the WebRTC offer

Include the same end_user_session_id (and persisted chat_id) inside request_data when posting the SDP offer. This keeps identity aligned if the client reconnects mid-call.

await fetch(`https://apivoice.syncli.cloud/sessions/${sessionId}/api/offer`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer syncli_YOUR_API_KEY'
  },
  body: JSON.stringify({
    sdp: pc.localDescription.sdp,
    type: pc.localDescription.type,
    request_data: {
      end_user_session_id: getBrowserSessionId(),
      chat_id: startData.chat_id || localStorage.getItem('syncli_voice_chat_id'),
      client_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
      client_timestamp: new Date().toISOString()
    }
  })
});
      

Request fields reference

end_user_session_id   string   Required for API embeds. Stable per-browser or per-user ID from your frontend.
chat_id               string   Optional. Omit on first visit; send value returned by prior /start to resume history.
end_user_email        string   Optional. Used when tracking mode includes email (email, email_and_browser, etc.).
client_timezone       string   IANA timezone, e.g. "America/New_York".
client_timestamp      string   ISO-8601 timestamp from the client clock.
      

💡 Reference implementation: The Voice tab in this portal (developer-portal/js/webrtc.js) implements the full flow with getBrowserSessionId(), /start, offer request_data, and full-duplex mic handling. Copy that pattern into your embed. Full guide: Voice Integration — Full-Duplex & Barge-In.

🔊 Full-Duplex & Barge-In (listen while speaking)

Syncli sessions are full-duplex: the bot keeps listening while it speaks. Users can interrupt mid-sentence (barge-in). Your frontend must send microphone audio for the entire call — the server runs STT on uplink even during TTS.

Required frontend changes

• sendrecv audio transceiver — attach mic track before createOffer()
• Play remote bot audio via pc.ontrack (browser AEC needs the playback reference)
• AEC Warm-up Notifier — send aec-ready over data channel once AEC is warm (2.5s desktop, 3s mobile) to delay greeting
• Simple getUserMedia constraints — use SyncliVoiceAudio.getVoiceAudioConstraints() to auto-tune constraints
• Never auto-mute on bot-started-speaking — only mute when the user toggles mute
• Chat UI: ignore bot-output; display bot-output-raw only

// ✅ Load script & get mobile-optimized constraints
// <script src="https://apidev.syncli.cloud/dev/js/voice-audio.js"></script>
const voiceConstraints = SyncliVoiceAudio.getVoiceAudioConstraints();
localStream = await navigator.mediaDevices.getUserMedia(voiceConstraints);

// ✅ Set up AEC warmup notifier to prevent false barge-in during greeting
const aecWarmup = SyncliVoiceAudio.createAecWarmupNotifier(dc);
dc.onopen = () => { if (aecWarmup) aecWarmup.onDataChannelOpen(); };
// Trigger on remote audio play:
audioEl.play().then(() => { if (aecWarmup) aecWarmup.onRemoteAudioPlaying(); });
      

Barge-in is triggered server-side when a finalized transcript (≥ ~12 characters) arrives while the bot is speaking. No special client “interrupt” message is required.

💬 Send Text While in a Voice Call

You can send text messages to the bot during a WebRTC voice session. The bot receives the text as if you had spoken it, and responds via the same audio stream.

// Send text through the data channel
dc.send(JSON.stringify({ type: 'chat', text: 'Your message' }))
      

What happens on the backend:

1. The injected text is treated identically to spoken audio input
2. The LLM processes it immediately (same pipeline)
3. TTS generates audio for the bot response
4. The response plays through the WebRTC audio track

Message flow (data channel → backend):

// → FROM frontend (you send this)
{ type: 'chat', text: 'What is the weather?' }

// ← TO frontend (backend event types)
{ type: 'user-transcript',     data: { text } }          // STT transcript
{ type: 'bot-output',           data: { text } }          // TTS-expanded — do NOT show in chat UI
{ type: 'bot-output-raw',      data: { text } }          // Canonical text — show this in chat UI
{ type: 'bot-started-speaking' }                          // Do NOT mute mic here
{ type: 'bot-stopped-speaking' }
      

💡 Tip: Use type: 'chat' to build hybrid UIs where users can both speak and type during voice sessions. The 'user-transcript' event will arrive for both spoken and typed input (deduplicated in the code above).

🔌 Plugin System (Dynamic Tools + Persona)

Every API key can have custom plugins injected into the voice agent. A plugin is a piece of Python code + a persona addon that gets loaded at session start. The agent can then call your custom tools and speak with your persona.

1. Create a plugin via API:

POST /api/plugins/{api_key}
{
  "name": "scheduler",
  "description": "My custom scheduler plugin",
  "persona_addon": "When scheduling, always confirm before creating.",
  "source_code": "PLUGIN = Plugin(name='scheduler', persona_addon='', tools=[\n  Tool(name='check_schedule', description='...', parameters={...}, handler=my_handler)\n])",
  "tools": [
    {
      "name": "check_schedule",
      "description": "Check if a time slot is free",
      "parameters": { "type": "object", "properties": { "date": { "type": "string" } } },
      "required": ["date"]
    }
  ]
}
      

2. Plugin Python Source (what goes in source_code):

from plugins.types import Plugin, Tool

async def check_schedule(params, deps):
    # params.tool_call_id  — unique ID from the LLM
    # params.arguments       — dict of parsed arguments
    # deps["user_id"]       — current user
    # deps["google_actions"] — Google calendar / gmail client
    # deps["chat_id"]       — current chat context
    args = params.arguments
    return {"free_slots": ["10:00 AM", "2:00 PM"]}

PLUGIN = Plugin(
    name="scheduler",
    persona_addon="You are a helpful scheduling assistant.",
    tools=[
        Tool(
            name="check_schedule",
            description="Check availability for a date",
            parameters={"type":"object","properties":{"date":{"type":"string"}}},
            required=["date"],
            handler=check_schedule
        )
    ]
)
      

3. Plugin lifecycle endpoints:

POST   /api/plugins/{api_key}                  # Create
GET    /api/plugins/{api_key}                  # List
GET    /api/plugins/{api_key}/{plugin_id}        # Get one
PATCH  /api/plugins/{api_key}/{plugin_id}       # Update source_code
DELETE /api/plugins/{api_key}/{plugin_id}        # Delete
POST   /api/plugins/{api_key}/{plugin_id}/toggle{"enabled":false}
POST   /api/plugins/{api_key}/test               # Dry-run without saving
      

💡 Tip: The persona_addon is injected into the system prompt at session start, shaping how the agent speaks. Tools are registered with the LLM so it can call them automatically when the user asks for help.

🧩 Agent Session Config (per-call behaviour)

Pass an optional agent_config object on POST /start to shape how the voice agent behaves for that session — without changing portal defaults for other calls. Omitted agent_config keeps today's behaviour (portal persona, knowledge base, API tool set).

Inline config on POST /start

{
  "end_user_session_id": "bs_abc123",
  "client_timezone": "America/New_York",
  "client_timestamp": "2026-06-19T12:00:00.000Z",
  "agent_config": {
    "persona": {
      "name": "Support",
      "identity": "You are Acme Corp support — concise and helpful.",
      "rules": "Escalate billing issues with transfer_to_human."
    },
    "persona_addon": "Always greet by first name when known.",
    "knowledge_base_id": "kb_xxxxxxxx",
    "tools": {
      "mode": "allowlist",
      "allow": ["save_visitor_info", "transfer_to_human"],
      "include_plugins": true,
      "include_mcp": true
    },
    "mcp_servers": [
      {
        "server_id": "crm",
        "url": "http://localhost:3100/sse",
        "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
      }
    ],
    "plugin_ids": ["scheduler"],
    "llm": { "temperature": 0.15, "max_tokens": 140 },
    "web_search": false,
    "metadata": { "page": "/pricing", "plan": "pro" }
  }
}

Named profile via agent_config_ref

Define reusable profiles in voice_agent/extensions/agent_config_service.py (AGENT_PROFILES), then reference them from your frontend:

{
  "agent_config": {
    "agent_config_ref": "support_voice",
    "metadata": { "locale": "en-US" }
  }
}

Developer service / controller pattern

extensions/agent_config_service.py   # AGENT_PROFILES + resolve_for_session()
extensions/agent_config_controller.py # validation + gateway hook
extensions/agent_config_router.py     # GET /api/agent-config/profiles
                                      # POST /api/agent-config/resolve (dry-run)

Copy extensions/template_service.py for CRM sync, transcript webhooks, etc.

💡 Tip: Use POST /api/agent-config/resolve to preview the merged config before starting a voice session. The gateway stores resolved agent_config on the session and forwards it to the WebRTC offer automatically.

🔌 Webhook CRM / QA Integration

At the end of every WebRTC voice session, the agent automatically executes an AI summarization task and issues a secure HTTP POST request containing detailed conversation analysis, extracted key topics, structured action items, customer sentiment, and chronological transcripts to your configured endpoint.

Webhook POST Payload Structure:

{
  "event": "voice_agent.session_completed",
  "event_version": "2.0",
  "timestamp": 1779556480,
  "session": {
    "session_id": "call_8f3d10ab_cd39_4f0b",
    "started_at": 1779556296,
    "ended_at": 1779556480,
    "duration_seconds": 184,
    "completed_successfully": true,
    "resolution_status": "resolved_by_ai",
    "termination_reason": "user_ended_call",
    "ended_by": "user",
    "was_transferred_to_human": false,
    "handoff_reason": null
  },
  "developer": {
    "developer_user_id": "dev_usr_0a12",
    "workspace_id": "wrk_123",
    "project_id": "proj_456",
    "resolved_tracking_key": "[email protected]"
  },
  "user_profile": {
    "user_id": "usr_99b0c2a1",
    "name": "Obiajulu",
    "email": "[email protected]",
    "phone": null,
    "client_ip": "192.168.1.45",
    "is_returning_user": true
  },
  "client_context": {
    "device_type": "desktop",
    "browser": "chrome",
    "os": "macos",
    "location": {
      "country": "US",
      "region": null,
      "city": null,
      "is_vpn_or_local": true
    },
    "user_agent": "Mozilla/5.0..."
  },
  "analytics": {
    "overall_sentiment": "Positive / Inquisitive",
    "sentiment_score": 0.82,
    "conversation_summary": "The user inquired about Kanban boards and smart attendance templates. Zara explained how to configure boards in the Projects tab and link attendees. The user expressed satisfaction.",
    "key_topics_extracted": [
      "Kanban boards",
      "Smart attendance",
      "Video meetings"
    ],
    "detected_intents": ["product_question", "setup_guidance"],
    "faq_candidates": [
      "How do I configure Kanban boards?",
      "How does smart attendance work?"
    ],
    "action_items": [
      {
        "owner": "user",
        "task": "Configure smart attendance via video meetings",
        "priority": "medium",
        "due_date": null,
        "status": "open"
      }
    ]
  },
  "quality_metrics": {
    "ai_resolution_score": 0.91,
    "customer_satisfaction_estimate": 0.88,
    "conversation_friction_score": 0.12,
    "first_response_time_ms": 900,
    "avg_response_time_ms": 1200,
    "assistant_talk_ratio": 0.58,
    "user_talk_ratio": 0.42,
    "interruption_count": 0,
    "clarification_count": 1,
    "fallback_count": 0
  },
  "transcript": [
    {
      "speaker": "assistant",
      "text": "Good afternoon, OBI! I’m Zara, here to help you navigate Syncli's workspace.",
      "timestamp": 1779556296
    },
    {
      "speaker": "user",
      "text": "How do I configure the Kanban boards and smart attendance?",
      "timestamp": 1779556310
    }
  ],
  "metadata": {
    "agent_id": "agent_zara",
    "agent_name": "Zara",
    "agent_version": "6.1",
    "prompt_version": "2026-05-voice-v3",
    "source": "SyncliVoiceGateway",
    "environment": "production"
  }
}
      

💡 Note: If configured, the webhook will contain an Authorization: Bearer <Token> header matching your designated secret. Use the **Rate Capping** panel to set up your URL/token and send live test connection payloads!

Deploy This Portal

Completely self-contained. No build step.

# Python 3 one-liner
python3 -m http.server 8443

# Node.js (npx serve)
npx serve -l 8443

# Vite project
npm create vite@latest my-syncli -- --template vanilla
cp index.html my-syncli/index.html
cd my-syncli && npm install && npm run dev

# S3 / Cloudflare Pages / Vercel / Netlify
# Upload index.html directly. No build step.