Skip to main content

Phone calls

OtoDock agents can handle real phone calls — answering when someone calls in, and placing calls out. It's how an agent becomes a support line, a reminder service, or a voice assistant on an actual phone number.

Calls run on the same live voice pipeline as dashboard voice conversations: natural spoken replies, the ability to talk over the agent to interrupt it, and short progress lines while it thinks or uses a tool.

What you need​

The phone service, included in the standard install (see Installation if you upgraded from a release without it), plus one of two ways onto the phone network:

  • Twilio — the quickest path. Buy a number from Twilio and paste your account SID and auth token into OtoDock. Calls enter through your install's existing public dashboard URL, with no extra ports or subdomains to open, and OtoDock points the number at your install automatically when you create a route.
  • Asterisk / FreePBX — your own phone system. You paste a one-time dialplan snippet that OtoDock generates for you; after that, OtoDock provisions each call route into FreePBX automatically, or on plain Asterisk hands you the one-line command to run per route. The phone service listens on two TCP ports your PBX must reach over your local network or a private tunnel — never the open internet: 9092 for call audio and 9093 for caller details. They listen only on the address your PBX dials, the one you set as OTO_AUDIOSOCKET_PUBLIC_HOST (see Installation). Without it, only the server itself can reach them, which is all a Twilio-only install needs.

Inbound and outbound​

  • Inbound — someone dials your number and the assigned agent picks up, greets the caller, and holds a natural spoken conversation. It can pause mid-sentence to think or use a tool, and the caller can talk over it to interrupt.
  • Outbound — an agent places a call through the phone-calls tool (on its own, or as part of a task). The call runs as its own fresh session: the outbound route's assigned agent dials out, briefed on what the call is for, and writes its opening line while the phone rings, so the first thing the person hears is the agent's own greeting. While on the call, the calling agent can message the agent that requested the call to check a detail mid-conversation, and that agent answers directly — or asks you.

For responsiveness, the low-latency direct engine is recommended for calls — but it isn't required. Each route runs on whatever engine its assigned agent uses, so the choice is yours.

Setting up calls​

An admin sets everything up in the dashboard under Setup → Phone (speech providers live under Setup → Audio):

  1. Add a phone server — Twilio credentials, or the FreePBX/Asterisk bootstrap — and click Verify to confirm connectivity.
  2. Create routes — each inbound or outbound route assigns an agent and a language to a number and decides who the agent is talking to, with call-specific instructions and per-route speech-provider overrides.
  3. Tune the call feel — background ambience, thinking fillers, and per-language prompts, all on the same page.

Who the agent is talking to​

Every route has a caller identity. It decides what the agent remembers about the person on the line, which files it works in, and what it's allowed to do. There are two choices.

Per caller (the default)​

Each phone number gets its own private notes and files, and its own memory. A caller who rings back is recognised by their number, and the agent remembers what it learned about them last time. Every call is still its own conversation; the previous one isn't replayed. Nothing one caller says ever reaches another caller or the team's shared memory. On a shared-only agent (one with no personal spaces) there is no private space to give, so callers see the agent's shared files instead, and they can't change them.

Callers run with the viewer role: they can read the agent's shared files and change nothing, and their own folder is theirs to write.

One setting shapes the mode. Remember callers (on by default) keeps each caller's notes between calls, so a customer who calls your support line again is recognised. Turn it off for a line where nothing should be kept between calls: every call then starts from a clean slate and its files are deleted at hangup. A withheld number is always treated that way.

Callers are not platform users, so the platform's core tools are never on the line: scheduling, triggers, delegation, notifications, meetings, agent configuration and creation, the catalog browser, SSH hosts, and placing further calls. Any other tool you've assigned to the agent works, and the route form shows what's available on this line and what's not on calls before you save.

A platform user​

The call runs as that user's own session: their memory, schedules, meetings, delegation, and connected accounts, capped at manager rights. It's the shape for a line that is really an extension of one person: your own agent on your own number. Two things follow from it:

  • Require a PIN on an inbound route in this mode. Without one, anyone who dials the number acts as that user. On an outbound route, whoever answers acts as that user.
  • If the user ever loses access to the agent, calls on the route quietly fall back to Per caller rather than running as someone else.

Protecting a number with a PIN​

Any inbound route can require an access code: a 6-digit PIN every caller must enter on the keypad before the agent answers, even people you know. Three failed tries end the call politely, and repeated failures put the caller's number (and, under sustained abuse, the whole route) into a 15-minute cooldown. Callers who fail never reach the agent; no session is even started. The code is stored encrypted and never shown again in the dashboard. A caller who passed the PIN is marked as verified in the call log.

The call log​

Every route keeps a call log, opened by the clock icon on the route row. Each call shows when, the direction, the number, who the session ran as (a remembered caller, a PIN-verified caller, an anonymous one, or a platform user), how it ended, the tools it used, and how long it lasted. Callers who failed the PIN or hit the lockout are listed too, with their numbers and attempt counts, so it's the place to look when someone is probing a protected line. The log is kept for as long as caller data is (below).

Caller data and retention​

Callers who aren't platform users leave three things behind: their private notes and files, the phone conversations, and the call log. They age out together, under Setup → Phone → Caller Data:

  • Forget callers automatically (on by default) removes callers not heard from within the window: 90 days by default, counted from each caller's last call, adjustable from a day to ten years. Turn it off to keep everything until you forget it by hand.
  • Forget all caller data now deletes every caller's files, every phone conversation, and the whole call log at once. Calls in progress are skipped. Nothing lands in the Recover bin, so it can't be undone.

The same page shows how many callers are remembered, with their files, conversations, and log rows. Callers' files never sync to a remote machine, and all callers of an agent together share a separate 1 GB allowance (see Usage & Limits).

Context for this call​

A route can also carry context into the call so the agent starts informed about this particular call: the caller's number, the number dialed, and details pulled from connected systems (a CRM lookup, say). This is wired up with a trigger attached to the route, and it complements what the agent already remembers about a returning caller: the greeting and conversation reflect both who's calling and why.

Next steps​