Phone and voice calls

Talk to an Agent in the app, or let an Agent phone someone for you.

There are two kinds of calls.

	In-app call	Phone call
Who talks	You and one Agent	An Agent and someone else
Where	In Worksong	Over the phone network, from your Twilio number
Who starts it	You	The Agent, after you approve a card

Talk to an Agent (in-app call)

Open the menu in a one-to-one chat with an Agent and choose Call followed by the Agent’s name. On the desktop browser Call is also one of the pinned actions in the chat header. Groups and side conversations have no call.

During the call:

• The Agent listens, answers by voice and uses its normal tools, memory and approvals. If a tool needs approval, the usual card appears on the call screen and the call keeps listening.
• You can talk over the Agent. What you interrupted is saved as the words you actually heard.
• Mute microphone, Turn speaker on/off and Hang up are on the call screen. Minimise call keeps the call going while you use the app; a bar shows it.
• The chat shows “Call started” and “Call ended”, and every spoken line is in the conversation. Nothing is lost after the call ends.
• When the call ends, the Agent does the follow-up work and writes a short summary in the chat. If the app is closed you get a notification.

Limits:

• One call at a time. You can start up to 10 calls an hour.
• A call lasts at most 30 minutes. The Agent warns you a minute before the end.
• After a minute of silence the Agent asks “Are you still there?”. If nobody answers, the call ends.
• A call stops when it spends its model cost limit (1 USD), or when the Agent or your account has used its budget.
• Calls count in Usage and spend.

A call can end with one of these messages: “The call reached its time limit”, “The call reached its cost limit”, “Nobody was talking, so the call ended”, “The connection was lost”, “The call was ended on another device”, “The server restarted, so the call ended”. Start a new call to continue.

The call is recorded as audio. A player appears under “Call ended” in the chat. Only you can play it.

Let an Agent phone someone

An Agent that has the PlaceCall permission can call a person for you, only from its main chat. You stay in control:

• The Agent writes a call brief: who to call, on whose behalf, the goal, what it may agree to and what it must not agree to, and the longest time.
• You get an approval card. You can edit the brief before you approve.
• The call is placed only after you approve. If anything changed since the card was made (for example the recording setting), the call is not placed and the Agent asks again.
• After the call, the chat shows Call with …. Open it for the outcome, summary and transcript.

Set up your Twilio account

Phone calls use your own Twilio account. Under Connections > Phone calls (Twilio) you fill in:

• Account SID, API key SID and API key secret. Auth Token is optional.
• Connect Twilio saves them, but only after Worksong checks the key with Twilio. If Twilio does not accept it, you see “Twilio did not accept this API key. Check the Account SID, API key SID and secret.” and nothing is saved.
• Choose number (later Change number) picks a voice-capable number from your account.

Use a Twilio restricted API key. It needs to create and read calls, read your phone numbers, and read and delete recordings. Without the recording permission a call still works, but its audio cannot be kept and the call says so.

Credentials are write-only. Worksong never shows them again. Replace key swaps the key (and clears the chosen number). Disconnect removes the connection.

Call limits

Under Call limits you set:

Setting	Range
Longest call	1 to 15 minutes
Calls per day	0 to 100
Monthly call budget	A dollar amount, or empty for none
Allowed countries	Prefixes the server allows
Test numbers	Up to 5 numbers; test calls dial only these, for at most 2 minutes

Before each call, and again after you approve it, Worksong checks: your limits, one live call at a time, the daily count, and that the worst-case cost fits your phone budget, the Agent’s monthly budget and the account’s.

Record calls

Record calls is on by default.

• On. Each call is recorded. The person hears “This call is being recorded.” first. Only you can play the recording. The audio is kept 90 days, or until you delete it.
• Off. Calls are not recorded and no notice is spoken. You still get the transcript. Check that this is allowed where the person is.

The approval card shows which of the two applies. While recording is on, a brief that tells the Agent not to mention the recording is stopped.

Recording status in the chat:

You see	Meaning
”Getting the recording ready…”	The call ended and the audio is being copied
A player with Play	The recording is ready
”The recording could not be saved”	The call connected but the audio could not be kept
”Recording deleted”	You or the retention rule deleted it
Nothing	Nobody answered, or nothing was recorded

Deleting a recording does not change the call, its transcript or its result.

If the Agent cannot answer during a call, it says so and ends the call politely.

_{Source: worksong-ai/worksong:docs/CALL-RECORDING.md@9f0684f, worksong-ai/worksong:docs/adr/ADR-0014-in-app-voice-call.md@9f0684f, worksong-ai/worksong:apps/mobile/src/features/voice/call/callMachine.ts@9f0684f, worksong-ai/worksong:apps/mobile/src/features/voice/call/CallView.tsx@9f0684f, worksong-ai/worksong:apps/mobile/src/features/connections/PhoneConnectionSection.tsx@9f0684f, worksong-ai/worksong:apps/mobile/src/features/connections/PhoneLimitsView.tsx@9f0684f, worksong-ai/worksong:docs/API.md@9f0684f. Docs version: Worksong 2.0 with Work 1.2.}