Call a business for the user and have a natural conversation to get something done (book, reschedule, cancel, ask). Refuses with 422 "Not calling yet" until the category's required information is known, listing exactly what to ask the user. Returns at once with the call; follow it with GET /api/calls/{call_id}?wait_seconds=30 until finished, answering any open question right away. Credits for the maximum length are held up front; billed per minute from pickup (phone menus and conversation; hold time at half price), rounded up; unanswered calls are free.

post/api/calls

Request

  • Base URL: https://call4.me
  • URL: https://call4.me/api/calls
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A unique value per request (a UUID), kept on retries of it. A retry with the same key and body returns the call the first request made (200, with Idempotent-Replayed: true) instead of placing another; the same key with a different body is refused (422). Keys belong to the account and never expire. A request refused before anything was placed (422 "Not calling yet", 402) does not use up its key.

Request body

tostring required

the number to call, e.g. "+14155550123", "(415) 555-0123", or abroad with its country code, e.g. "+31 20 123 4567"

businessstring required

who you are calling, as a person would say it: "Nopa", "Dr. Chen's office", "Toyota of Berkeley service"

goalstring required

what the call should achieve, in plain words: "Book a table for 4 tomorrow (Sat Oct 3) around 7pm under Khami."

category'medical' | 'dental' | 'restaurant' | 'veterinary' | 'auto_service' | 'auto_sales' | 'home_service' | 'personal_care' | 'internet_new_service' | 'internet_existing_account' | 'flight_change' | 'general' required

the kind of call; decides what must be known first (see call4me_get_requirements)

detailsobject

answers to the category's fields by key, e.g. {"reason":"annual physical","patient_status":"existing","availability":"weekday mornings next week"}. Profile fields (name, DOB, phone, insurance...) are filled from the saved profile only when the call is for the profile's owner; for anyone else (on_behalf_of is another name) pass all of their details here, since the owner's are never used.

on_behalf_ofstring

who the call is for, as the caller should say it (default: the profile's full_name). The caller calls FOR this person; it never claims to be them.

factsstring

anything else the caller may share beyond the category's fields, one per line

flexibilitystring

what the caller may accept without asking: "any time 6:30-8pm", "a different day this week is fine", "up to $300". Anything outside this becomes a question to you.

timezonestring

IANA time zone of the business, e.g. "America/Los_Angeles", so "tomorrow" is unambiguous

connect_whenstring

when to ring the user and patch them into the call without being asked, e.g. "as soon as a person picks up" (skip the hold) or "if they need to speak to me". Rings their own phone: details.phone when given, else the one in their profile; a call with neither is refused. They hand the call back to the caller by pressing * or hanging up.

listen_inboolean

ring the user as soon as the business answers so they can listen in: nobody on the call hears them and the caller keeps working. They press 1 anytime to take over, or hang up to stop listening. Rings their own phone: details.phone when given, else the one in their profile; a call with neither is refused.

max_minutesinteger

optional cap on the answered call, including phone menus. Defaults to 30 minutes, or less if the available balance cannot cover it. Only credits for that cap are held. A call still on hold when it reaches the cap keeps waiting: call4me holds 15 more minutes of credits at a time while the balance covers them, up to 4 hours. One still mid-conversation at the cap gets 2 more minutes at a time to finish instead of hanging up. Set a shorter cap to leave more credits free for other calls

voice'marin' | 'cedar' | 'gleam' | 'meridian' | 'vesper' | 'willow'

caller voice (default marin); hear each at https://call4.me/voices

caller_namestring

a first name the caller introduces itself with, e.g. "Jordan", for this call only (default: the profile's assistant_name, else none: just "<user>'s assistant"). Put the caller's name and company here, never in the goal: the caller's identity comes only from these fields.

calling_asstring

a company the caller calls from, e.g. "Acme": it introduces itself as "Jordan from Acme" (or "calling from Acme" without caller_name) instead of "<user>'s assistant", and callbacks to the number it called from answer as that company. Calling for several companies: pass the company on every call and give each one its own number (from), so callbacks reach the right identity.

callback_numberstring

the number the caller gives for call-backs and on voicemail, when the user wants callbacks to ring a phone of theirs (e.g. "(415) 555-0123"). Default: the number the call comes from, so a call4me number answers the callback and finishes the task. A callback to callback_number goes straight to that phone instead, and call4me never hears it. Phone numbers in details or facts are only for finding or verifying an account, never given as the callback.

fromstring

which of the account's numbers to call from (default: a call4me number in the callee's country). May be one of the user's own verified numbers (call4me_verify_number), for businesses in its country: they see it and call back the user directly

Response

A retry under the same Idempotency-Key: the call the first request placed

idstring required
status'queued' | 'dialing' | 'in_progress' | 'completed' | 'no_answer' | 'busy' | 'failed' | 'canceled' required
finishedboolean required

true once the call ended and its recap is written; poll until then

direction'outbound' | 'inbound' required
businessstring required
numberstring required
calling_numberstring nullable required

the call4me number that rings the user when they join

goalstring nullable required
talk_minutesinteger required
coststring required
cost_centsinteger required

billed so far, in US cents; final once finished

endedstring nullable required

who ended the call and why

errorstring nullable required
created_atstring required
transcriptstring[]

Changes

No recorded changes to this operation across all 1 revision of this API.