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. Twilio 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.

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"}}
    ]
  }'

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.

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.

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.

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.