phonecall

Let your agent make phone calls. A Grok Voice agent places the call through Twilio and sounds like a person. When it needs a decision, it asks your agent mid-call and keeps the line open. When the call ends, you get a summary and the full transcript.

Quick start

You need:

• a Cloudflare account

• an xAI API key

• a Twilio account with a voice number (trial accounts can only call verified numbers)

• Node 20 or later

git clone https://github.com/anomalyco/phonecall && cd phonecall
npm install
npx wrangler deploy   # prints your Worker URL: https://phonecall.<you>.workers.dev
npm run setup         # asks for your keys, connects your number to xAI, stores the secrets
npm link              # puts the phonecall CLI on your PATH

Make a test call. A second AI plays the other side, and nobody is dialed:

phonecall call --simulate "You run the counter at a busy pizza place." \
  --brief "Order a large pepperoni for pickup at 7pm." --watch

Then call a real number:

phonecall call +14155550100 --watch \
  --brief "Book a table for 2 on Friday around 7pm. Anything from 6:30 to 8 is fine."

Related MCP server: Twilio Call Service MCP Server

Use it from an agent

The Worker is also an MCP server at /mcp. In OpenCode, add this to opencode.json:

{
  "mcp": {
    "phonecall": {
      "type": "remote",
      "url": "https://phonecall.<you>.workers.dev/mcp",
      "oauth": false,
      "timeout": 90000,
      "headers": { "Authorization": "Bearer {file:~/.config/phonecall/token}" }
    }
  }
}

Other MCP clients need the same URL and an Authorization: Bearer <token> header. The token is in ~/.config/phonecall/token. phonecall_watch can take up to 50 seconds, so allow at least that much time per tool call.

An agent calls phonecall_start, then calls phonecall_watch repeatedly. What it does next depends on the type phonecall_watch returns:

• input_request: the caller is on the line waiting for an answer. Reply within about a minute.

• running: nothing new yet. Watch again.

• done: the call is over, and the report is included.

CLI

call also takes these options:

• --for sets who the call is for.

• --as sets the caller's name (default Sam).

• --voice picks eve, ara, rex, sal or leo.

• --max-minutes caps the call length (default 10).

• --answer-timeout sets how many seconds the caller waits for an answer (default 60).

Writing a brief

The brief is the only thing the caller knows. Include:

• the goal

• the facts it may share

• what it may decide on its own

• what to ask you about first

For example:

Move my dentist cleaning at Bright Smile Dental from Thursday Nov 12 at 2pm
to any weekday morning next week. My date of birth is March 3, 1990, if they
need it. Don't agree to any fee without asking me.

Anything outside the brief turns into a question for you. The caller never makes up details. It never pays for or signs up to anything unless the brief allows it.

How it works

• Twilio dials the number. When someone answers, TwiML <Dial><Sip> connects the call to xAI's SIP endpoint. An X-Job-Id header tells the Worker which job the call belongs to.

• A Durable Object per call joins the call over xAI's realtime WebSocket (Grok Voice 3.0). It gives the voice agent a prompt (src/prompt.ts) and four tools: send_dtmf, request_input, check_messages and end_call.

• Questions go to whoever is watching. Answers reach the voice agent as a check_messages tool result, which it relays straight away.

• When Twilio reports that the call has ended, Grok 4.7 writes the report from the transcript.

• Simulated calls dial a second xAI SIP number, where another Grok session plays the other side. That number comes from the fictional 555-0100 to 555-0199 range, so it can't be a real line.

Configuration

npm run setup stores everything as Worker secrets. Nothing is kept in the repo.

You can also set AGENT_NAME, VOICE and SUMMARY_MODEL with npx wrangler secret put to change the defaults (Sam, eve, grok-4.7).

Running npm run setup again replaces the xAI registration and SIP credentials. It makes a new API token unless PHONECALL_TOKEN is set in your environment. Run npm run setup -- --no-sim to skip the simulator number.

Good to know

• A call costs about $0.10 a minute: Grok Voice is $0.08, and Twilio outbound plus SIP is about $0.02 in the US.

• The caller never claims to be human. If someone asks, it says it's an AI assistant.

• Rules on AI calls vary by place. For example, the FCC treats AI voices as artificial voices under the TCPA. Check the rules that apply to you before calling people.

• Setup leaves your Twilio number's incoming-call settings alone. Calls back to that number go wherever they went before.

License

MIT