Talkar Service API ReferenceCopy Anchor Link

Use these APIs when embedding Talkar inside a client's application, CRM, web portal, or backend automation pipeline. All interactive playgrounds below connect through the docs proxy—never paste live production secrets into untrusted shared environments.

Authentication HeadersCopy Anchor Link

1. Trigger Outbound Calls ProgrammaticallyCopy Anchor Link

You can initiate an automated outbound call via an API Trigger Node (trigger_path) (POST /api/v1/public/agent/{uuid}) or Workflow UUID (POST /api/v1/public/agent/workflow/{workflow_uuid}) for Published builds—or insert /test/ (POST /api/v1/public/agent/test/{uuid} and /test/workflow/{workflow_uuid}) to test the Latest Draft:

• phone_number (required): E.164 destination phone number or SIP target.
• initial_context (optional): Key-value dictionary merged into initial_context ({{customer_name}}, {{order_id}}, etc.).
• Response: Returns { "status": "initiated", "workflow_run_id": ..., "workflow_run_name": "WR-API-..." } (use workflow_run_id as {run_id} in monitoring routes).

curl -X POST "https://api.example.com/api/v1/public/agent/<trigger_uuid>" \
  -H "X-API-Key: <org_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "initial_context": {
      "customer_name": "Rohan Sharma",
      "order_id": "ORD-9182"
    }
  }'

curl -X POST 'https://api.talkar.in/api/v1/public/agent/string' \  -H 'Content-Type: application/json' \  -d '{  "phone_number": "string"}'

{  "status": "string",  "workflow_run_id": 0,  "workflow_run_name": "string"}

curl -X POST 'https://api.talkar.in/api/v1/public/agent/workflow/string' \  -H 'Content-Type: application/json' \  -d '{  "phone_number": "string"}'

2. Monitor Call Runs, Poll/Stream Transcripts & Download ArtifactsCopy Anchor Link

After launching a call (saving workflow_run_id), you can:

1. Check completion, disposition & extracted data via GET /api/v1/public/agent/run/{run_id} (X-API-Key header — returns { run_id, is_completed, extracted_data, call_disposition }). (For full recording/transcript URLs, logs, cost_info, and QA annotations, call GET /api/v1/workflow/{workflow_id}/runs/{run_id}.)
2. Poll live or completed turns (JSON) via GET /api/v1/public/agent/run/{run_id}/live-transcript (X-API-Key header — returns { run_id, is_live, turns }).
3. Stream live call events via SSE (text/event-stream) via GET /api/v1/public/agent/run/{run_id}/stream?api_key=<org_api_key> (passes api_key as a query parameter for browser EventSource compatibility; emits connected, turn, agent_start, agent_done, ended, timeout, error with 1s heartbeats).
4. Download recordings or transcripts (recording, transcript, user_recording, bot_recording) using public run token links (GET /api/v1/public/download/workflow/{token}/{artifact_type}, returns 302 redirect to a 1-hour signed URL).

// Frames arrive as `data: <json>\n\n` (no named `event:` header) with `: heartbeat` ticks every 1s.
const stream = new EventSource(
  `https://api.example.com/api/v1/public/agent/run/${runId}/stream?api_key=${encodeURIComponent(apiKey)}`
);

stream.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  if (payload.type === 'connected') console.log('Subscribed to run', payload.run_id);
  if (payload.type === 'turn') console.log(`[${payload.role}]`, payload.text, { final: payload.final });
  if (payload.type === 'ended' || payload.type === 'timeout' || payload.type === 'error') {
    console.warn('Stream closed:', payload);
    stream.close();
  }
};

Querying & Filtering Run History (/runs/all & /{workflow_id}/runs)Copy Anchor Link

List paginated runs across your organization (GET /api/v1/workflow/runs/all) or scoped to a single workflow (GET /api/v1/workflow/{workflow_id}/runs) with optional page, limit, sort_by ("duration" or "created_at"), sort_order ("asc" | "desc", default "desc"), and filters (URL-encoded JSON array):

FILTERS='[{"attribute":"workflowId","type":"number","value":{"value":103}},{"attribute":"status","type":"radio","value":{"status":"completed"}},{"attribute":"duration","type":"numberRange","value":{"min":30}}]'

curl -G "https://api.example.com/api/v1/workflow/runs/all" \
  -H "X-API-Key: <org_api_key>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=25" \
  --data-urlencode "sort_by=duration" \
  --data-urlencode "sort_order=desc" \
  --data-urlencode "filters=${FILTERS}"

(Malformed JSON returns HTTP 400, and disallowed filter attributes return HTTP 403. List responses set logs: null and annotations: null; call GET /api/v1/workflow/{workflow_id}/runs/{run_id} for full transcripts, logs, and QA annotations.)

curl -X GET 'https://api.talkar.in/api/v1/public/agent/run/0'

{  "run_id": 0,  "is_completed": true,  "extracted_data": {},  "call_disposition": "string"}

curl -X GET 'https://api.talkar.in/api/v1/public/agent/run/0/live-transcript'

{  "run_id": 0,  "is_live": true,  "turns": [    {      "role": "agent",      "text": "string",      "timestamp": "2019-08-24T14:15:22Z"    }  ]}

curl -X GET 'https://api.talkar.in/api/v1/public/agent/run/0/stream?api_key=string'

curl -X GET 'https://api.talkar.in/api/v1/public/download/workflow/string/recording'

3. Public Web Embeds (Voice or Text Chat)Copy Anchor Link

Client websites can embed a Published Talkar workflow (settings.widgetType configured as voice or chat, returned as top-level widget_type from /init) with allowed_domains, floating/inline/headless modes, and usage_limit caps (see the step-by-step Public Web Embeds Guide for code samples, 409 revision locking, and WebRTC signaling):

1. Fetch origin-validated widget config (GET /api/v1/public/embed/config/{token}).
2. Initialize a 1-hour session (POST /api/v1/public/embed/init, passing {"token": "...", "context_variables": {...}} in the JSON body).
3. In chat mode, exchange turns via POST /api/v1/public/embed/chat/{session_token}/messages (4000-char limit, optional expected_revision optimistic lock returning 409, 50-turn limit returning 429), inspect state via GET /api/v1/public/embed/chat/{session_token}, or close via POST .../end. Public embed responses automatically redact internal prompts, raw errors, and system context. (WebRTC embeds fetch ICE servers via GET /api/v1/public/embed/turn-credentials/{session_token}.)

curl -X GET 'https://api.talkar.in/api/v1/public/embed/config/string'

curl -X POST 'https://api.talkar.in/api/v1/public/embed/init' \  -H 'Content-Type: application/json' \  -d '{  "token": "string"}'

curl -X POST 'https://api.talkar.in/api/v1/public/embed/chat/string/messages' \  -H 'Content-Type: application/json' \  -d '{  "text": "string"}'

4. Org Wallet, Presigned Uploads & Platform Automation APICopy Anchor Link

Organization Wallet & S3 File Helpers (/api/v1)Copy Anchor Link

Authenticated via X-API-Key or Bearer token:

• Wallet & Ledger: GET /api/v1/wallet, GET /api/v1/wallet/balance, and GET /api/v1/wallet/transactions?page=1&limit=20&type=...
• Presigned S3 Uploads/Downloads (900s upload TTL): POST /api/v1/s3/presigned-document-url (onboarding PDF/PNG/JPG up to 20 MB), POST /api/v1/s3/presigned-upload-url (campaign .csv up to 10 MB), GET /api/v1/s3/signed-url (expires_in default 3600s), GET /api/v1/s3/file-metadata.

Platform & Automation API (https://billing.talkar.in/automation/v1)Copy Anchor Link

Scope-gated (credit, deduct, wallet_read, customer_read, suspend, stats_read, notify) with X-Talkar-API-Key: tkr_auto_..., per-key RPM throttling (429), and audit logging: