Calls

VOCALS handles both inbound and outbound voice calls. Each call flows through the STT, LLM, and TTS pipeline in real time, creating a natural conversational experience.

Inbound Calls

Inbound calls arrive when someone dials one of your configured phone numbers. The flow is:

1. Caller dials the number.
2. Your SIP provider routes the call to VOCALS via SIP trunk.
3. VOCALS loads the agent assigned to that number.
4. The agent's welcome message plays (if configured).
5. The real-time voice pipeline begins -- the agent listens, thinks, and responds.
6. The call ends when the caller hangs up, the agent concludes the conversation, or the max call duration is reached.

If the line stops carrying audio without ever signalling that the call is over, VOCALS closes the session shortly after the audio stops rather than leaving it open. Those calls are logged with the outcome timeout, and their duration reflects the audio the call actually carried.

No additional setup is needed beyond configuring a phone number and assigning an agent.

Outbound Calls

Outbound calls are initiated by VOCALS to a target phone number. Use cases include appointment reminders, follow-up calls, surveys, and lead outreach.

Initiating Outbound Calls

Single call via dashboard:

1. Go to Calls > New Outbound Call.
2. Select the agent to use.
3. Select the originating phone number (the number the callee will see).
4. Enter the destination phone number.
5. Click Call.

Batch calls via API:

curl -X POST https://your-vocals-domain.com/api/v1/calls/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "from_number": "+15551234567",
    "targets": [
      {"to": "+15559876543", "metadata": {"name": "John"}},
      {"to": "+15559876544", "metadata": {"name": "Jane"}}
    ]
  }'

Duplicate Protection

VOCALS will not dial the same number twice in quick succession. A second outbound call to a number you have just called is suppressed for a short cooldown (60 seconds by default), so a workflow that retries, or a double-click on Call, cannot ring the same person repeatedly. The dashboard tells you when a call was suppressed instead of placed; wait a moment and try again if you really do want to call twice.

Integrations get the same protection plus an explicit opt-in: send an Idempotency-Key header and a retried request returns the original call instead of dialling again. See Duplicate Suppression in the API reference.

Call Queue

Outbound calls are processed through a rate-limited queue to comply with carrier regulations and avoid number flagging.

• Rate limit: 1 call per second (1 CPS).
• Calls are queued in order and dispatched sequentially.
• You can view queue status in the dashboard under Calls > Queue.
• To cancel a queued call, click the cancel button next to it in the queue view, or use the API.

caution

Exceeding carrier rate limits can result in your numbers being flagged as spam. VOCALS enforces the 1 CPS limit to protect your numbers, but you should also follow Twilio's best practices for outbound calling: use verified caller IDs, register with STIR/SHAKEN, and avoid calling numbers on do-not-call lists.

Answering Machine Detection (AMD)

When making outbound calls, you often want to detect whether a human or an answering machine picked up. VOCALS supports AMD through Twilio's built-in detection.

AMD settings per agent:

Setting	Options	Description
AMD Enabled	On / Off	Whether to run answering machine detection.
On Machine	hangup, leave_voicemail, wait	Action when a machine is detected.
Machine Detection Timeout	3-10 seconds	How long to wait for AMD to decide before treating as human.

• Hangup: Immediately disconnect. Use when you only want to talk to live humans.
• Leave Voicemail: Play a pre-recorded or TTS-generated voicemail message, then hang up.
• Wait: Wait for the machine's greeting to finish, then proceed with the normal agent conversation. Useful if AMD accuracy is uncertain.

Detection runs in the background, so it never delays the start of the call: the agent begins speaking as soon as the line is answered and the verdict arrives a moment later. With Hangup selected, that means an answering machine may hear the first few words of the greeting before the call is cut. Those calls are logged with a voicemail outcome.

Voicemail Detection

When AMD detects an answering machine and the agent is configured to leave a voicemail:

1. VOCALS waits for the beep (end of the machine's greeting).
2. The voicemail message plays. You can configure this as a static message or let the agent generate it dynamically from a voicemail-specific prompt.
3. The call ends after the message plays.

Voicemail messages appear in your call logs with a voicemail tag for easy filtering.

Call Lifecycle

Every call moves through a series of statuses:

queued  -->  ringing  -->  in-progress  -->  completed
                |              |
                v              v
            no-answer       failed
                               |
                               v
                            canceled

Status	Description
queued	Outbound call is in the queue, waiting to be dispatched.
ringing	The phone is ringing on the callee's end (outbound) or the call is being set up (inbound).
in-progress	Call is connected and the voice pipeline is active.
completed	Call ended normally. Both parties disconnected gracefully.
no-answer	The callee did not pick up within the ring timeout (outbound only).
failed	A technical error occurred (provider failure, network issue, invalid number).
canceled	The call was canceled from the queue before it was dispatched.

Live Monitor

The Live Monitor page is the real-time companion to the call logs: it shows calls that are in progress right now rather than completed ones.

1. Open Live Monitor from the sidebar. A connection badge at the top reads Connected while the live feed is active.
2. Each active call appears as a card showing its From and To numbers, a live Duration counter, and the call's current pipeline State. When nothing is in progress, the page shows "No active calls".
3. Cards appear and update in real time -- place a test call from an agent's Test Call dialog in another tab to watch it arrive here.

Call Logs

Every call is logged with full details:

• Duration and timestamps (start, connect, end).
• Full transcript of the conversation with speaker labels and timestamps per utterance.
• Audio recording (if recording is enabled on the agent).
• Provider details: which STT, LLM, and TTS providers were used, along with per-turn latency.
• Cost breakdown: estimated cost per provider for the call.
• Status and outcome (completed, no-answer, failed, voicemail).
• Metadata: any custom metadata passed when initiating the call.

Interrupted Turns

When a caller talks over the agent and the agent stops mid-sentence, the transcript records only the part the caller actually heard, followed by [cut off by caller]. What the caller said while interrupting is prefixed with [interrupting]:

Agent:  Sure, I can book that for [cut off by caller]
Caller: [interrupting] actually make it Friday
Agent:  Friday it is. What time suits you?

This means the transcript matches the audio recording for interrupted turns, rather than showing the longer answer the agent would have given if it had not been stopped.

The cut-off point is whatever had actually reached the caller at the moment they cut in. Because the agent's audio keeps playing for a moment after it has finished composing its reply, a turn is still marked as cut off when the caller talks over those last words, and the transcript keeps only what they heard.

Filtering and Search

In Calls > Logs, you can filter by:

• Date range
• Agent
• Phone number
• Status
• Duration (min/max)
• Full-text search across transcripts

Exporting

Click Export to download call logs as CSV. The export includes all metadata, timestamps, and transcripts. Audio files can be downloaded individually or in bulk.

Call Recording

Recording can be enabled per agent. When enabled:

• Both sides of the conversation are recorded.
• Recordings are stored securely and accessible from the call log detail view.
• A recording consent disclaimer can be configured to play at the start of the call (required in many jurisdictions).

warning

Check your local laws regarding call recording consent. Many jurisdictions require all-party consent. Configure the consent disclaimer in your agent's welcome message if required.