Place a phone call
place_callUse this when the user needs something from a US or Canadian business that takes a phone call: book, cancel, get prices or availability, check an order or whether a repair is done, reach a person or wait on hold, ask for an upgrade, ask an office how to do something, or ask a vendor if they're free on a date. Places a real call: a voice assistant speaks for the user and works phone menus. Don't use it for personal numbers, emergencies, or just finding a number (find_business). Returns right away with call_id, plus warnings worth telling the user (the place looks closed right now, it's late there, low balance); then call get_call(call_id, wait_seconds=45) repeatedly until status is "ended" and outcome is present. Required: phone and goal (unless retrying with setup_code). Put the user's name in on_behalf_of, everything the business may ask for in details (name, callback number, account or order numbers, the car, dates), and pre-approved decisions in if_asked. Anything missing becomes a mid-call question the business waits about 45 seconds for. If status is "needs_setup" (first real call only), show message_for_user, then call wait_for_setup(setup_code). That isn't an error. Free demo lines (fictional, no setup, no charge): Maple Street Pizza (469) 770-7412, Oak Street Auto (469) 402-2653, Cedar Lane Tire & Brake (469) 437-9838, Elm Avenue Garage (469) 300-6608, Ironwood Fitness (469) 253-8241. $1 per answered call (first 2 min), then 40¢/min; unanswered calls are free. Businesses only: no personal numbers or emergencies.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "place_call"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | What the call should get done and what counts as done, 1-3 plain sentences, e.g. "Book a table for 4 this Friday between 7 and 8:30pm and get a confirmation number." | |
| phone | No | The business's phone number, US or Canada, any format, e.g. "(469) 770-7412" | |
| call_at | No | Schedule the call instead of dialing now: an ISO 8601 time with a UTC offset, within 7 days, e.g. their opening time ("2026-11-03T09:05:00-06:00"). Returns a batch_id to follow with get_batch. | |
| details | No | Facts the assistant may share when asked: names, account or order numbers, the car, dates, preferences, budget. Never card numbers, SSNs or passwords. | |
| if_asked | No | Pre-approved answers so the business doesn't wait on you, e.g. "If they offer another time, anything 7 to 8:30pm is fine. A deposit up to $25 is OK." | |
| language | No | Language to open in (e.g. "Vietnamese", "Korean"). Default English, and the assistant switches to Spanish by itself if they answer in Spanish. Pass it when the business likely speaks another language (a Vietnamese nail salon, a Korean market), since other languages are only understood when set up front. | |
| questions | No | Specific things to find out, one per item. Each comes back in answers, in this order, e.g. ["How much is a large pepperoni?", "Is there parking?"] | |
| setup_code | No | From a needs_setup response, to retry once the user finished the link | |
| account_key | No | A saved cfm_... key, if you have one | |
| after_hours | No | Only for places open late (24-hour pharmacy, hotel): call even 10pm-7am at the business | |
| constraints | No | Limits, e.g. "Don't agree to anything over $200" or "Only Saturday mornings" | |
| transfer_to | No | The user's own phone. If set and the goal says to connect them, the assistant patches them in once a person answers (after menus and hold). Best for banks, carriers and insurers that verify the account holder. | |
| max_cost_usd | No | Most this call may cost, e.g. 3 = about 7 minutes. The call ends by itself at that point, so a long hold can't run up the bill. Minimum $1. Omit for the normal 30-minute cap. | |
| on_behalf_of | No | The user's name, as the business should hear it. For a work call, add the company ("Sam at Ridgeline Print Co"): suppliers and vendors look accounts up by company. Just a name: it's said in the first sentence ("calling for <this>"), so account numbers or descriptions of the order go in details | |
| business_name | No | Business name, used in the greeting | |
| callback_number | No | A number where the business can reach the user. Pass it when they may follow up (a quote after a visit, a callback): the assistant gives it as soon as they say they'll get back to the user. Optional: without one, the business gets CallForMe's line and a 4-digit extension for this call, and its message comes back in get_call (callbacks) and the account tool. | |
| voicemail_message | No | Message to leave on voicemail. Omit to hang up on voicemail (free when it goes straight to voicemail). |