Phone Numbers & Telephony SetupCopy Anchor Link

Talkar supports connecting multiple carrier trunks per organization under Telephony Configurations across 7 production telephony providers plus 1 Mock simulator, letting you route inbound DIDs to specific agents, balance outbound campaigns across caller-ID pools, transfer live calls to human teams, and detect voicemail machines.

---

1. Multi-Trunk Telephony Configurations & Phone NumbersCopy Anchor Link

Organizations can hold multiple carrier configurations (for example, a Plivo trunk for India, a Twilio trunk for US/global numbers, and an Asterisk ARI trunk for on-prem PBX routing), with one trunk marked as Default Outbound.

Adding Phone Numbers & Ownership ValidationCopy Anchor Link

Each phone number lives under a specific Telephony Configuration:

• Accepted Address Formats: E.164 (+918061234567, +14155551234), 8–15 bare digits when accompanied by an ISO-2 country_code (e.g. "IN", "US"), short extensions, or SIP URIs (sip: / sips:).
• Immutability: Once created, a phone number's address cannot be edited—to change a number string, delete the entry and add the updated number.
• Global Ownership Conflict Guard (HTTP 409): Talkar checks whether an active DID is already owned by another organization (or already registered on the trunk) and rejects conflicting registrations with HTTP 409 Conflict.
• Single-Call Caller-ID Resolution Order: When placing a single outbound call:
  1. If from_phone_number_id is explicitly provided, it must belong to the selected telephony_configuration_id (mismatch or inactive number rejects cleanly).
  2. Otherwise, Talkar uses the trunk's is_default_caller_id active number.
  3. Otherwise, Talkar picks an available active number from that trunk's pool.
• Bulk Campaign Pooling: Bulk campaigns rotate outbound calls across all active numbers in the trunk's pool (or prioritize a per-row caller_number with 20s wait fallback).

Canonical Inbound Routing & Carrier Webhook SyncCopy Anchor Link

• Canonical Inbound Webhook: POST /api/v1/telephony/inbound/run (plus /fallback for carrier error fallback; legacy /inbound/{workflow_id} routes are deprecated).
• Assigning inbound_workflow_id: Assigning a published workflow to an active DID automatically syncs upstream routing; clearing inbound_workflow_id or deleting the DID detaches upstream hooks first.
• Per-Number Sync vs. Shared Carrier App Sync:
  • Twilio & Vobiz: Sync per phone number whenever you attach or detach an inbound workflow (Twilio updates VoiceUrl and StatusCallback directly on the IncomingPhoneNumber resource).
  • Plivo, Telnyx, Cloudonix & Vonage: Share an Application / Call Control webhook URL pointing to /api/v1/telephony/inbound/run. For Vonage, configure signature_secret and enable signed_callbacks=true for verified callbacks.
• Common Inbound TelephonyError Causes: Carrier webhook hits an inactive trunk, unassigned or inactive DID, missing/unpublished inbound_workflow_id, an organization in suspension or pre-live build stages (under_review, pending_approval, info_requested, approved, agent_building), or failed wallet/concurrency admission checks.

---

2. Supported Telephony Providers (7 Production Providers + Mock)Copy Anchor Link

Media WebSocket Close CodesCopy Anchor Link

Carrier media streams connect over WebSockets (WS). Unexpected session rejections return explicit close codes:

• 4401 — Unauthorized / invalid authentication signature or credentials.
• 4409 — Conflict (duplicate active session or concurrency conflict).
• 4400 — Bad request (missing required media parameters or invalid workflow/run state).

---

3. Live Call Transfers (transfer_call)Copy Anchor Link

To escalate a call to a human agent, queue, or SIP destination, attach a transfer_call tool to an Agent node.

Destination Resolution ModesCopy Anchor Link

Key Transfer SettingsCopy Anchor Link

• Pre-transfer announcement (messageType): Play "none", "custom" TTS text, or "audio" (a pre-recorded clip via audioRecordingId) before bridging the caller.
• Ring Timeout (timeout): 5 to 120 seconds (default 30s) waiting for the destination leg to answer.

---

4. Voicemail & Answering Machine Detection (AMD)Copy Anchor Link

Talkar provides two independent mechanisms to detect answering machines and save minutes on unattended calls:

1. Carrier-Level AMD (Twilio trunks only): Enable amd_enabled on your Twilio telephony config. Twilio evaluates the call answer pattern and reports answered_by (machine_start, machine_end_beep, machine_end_silence, machine_end_other, or fax), appending voicemail_detected to call_tags and triggering campaign voicemail retries if enabled.
2. In-Pipeline LLM Voicemail Detection: Enabled per workflow inside workflow settings (voicemail_detection, using either the workflow LLM or a dedicated fast detection model with a long_speech_timeout defaulting to 8.0s). Automatically disabled on Realtime Speech-to-Speech workflows. When triggered, Talkar terminates immediately with mapped_call_disposition = "voicemail_detected" and skips final variable extraction.

---

5. Concurrency Limits, Channel Rejections & Slot RecoveryCopy Anchor Link

• Organization Concurrency Cap: Organizations enforce a Concurrent Call Limit (default platform cap 10, customizable per org). Sub-organizations under a Master Org can also enforce individual sub-org concurrency caps alongside the master fleet cap.
• No Queuing on Real-Time Channels: Single calls, inbound calls, and WebRTC playground sessions reject immediately if slots are full or quota fails:

• Crash Recovery: Active call slots send heartbeats every 10s; any crashed or hung session older than stale thresholds (120s heartbeat miss or 40 min max duration) is automatically reclaimed so capacity never leaks permanently.