PlaceCall

Overview

PlaceCall is a hosted API that places a real outbound phone call to a US business, has an AI voice agent carry out a plain-English task on that call (an inquiry, a booking, a cancellation, a quote), and returns a structured outcome, the transcript and the recording. The agent works through phone menus and hold, and it can send the user a question in the middle of a call. When the user has no number, the API can first suggest businesses to call and write the call brief for each one. This skill teaches an agent to drive that API with curl. Adapted from the official PlaceCall skill: https://github.com/voygr-tech/placecall

When to Use This Skill

• Use when the user asks you to call a business, or to ask, book, confirm, reschedule or cancel something by phone, and the number is a US number.
• Use when the user names a need rather than a number ("find a florist in Chicago with peonies and call them"): suggest places first, then call the one the user picks.
• Use when the user asks for the status, outcome or transcript of a call placed earlier, or wants to answer a question the call agent sent mid-call.
• Do not use for SMS, email, non-US numbers, or numbers the user is not entitled to call.

How It Works

All requests go to https://api.voygr.tech over HTTPS with the header X-API-Key: $PLACECALL_API_KEY.

Step 1: Check the key and the balance

The user creates a key at https://api.voygr.tech/checkout (name and email; the key is emailed to them) and puts it in the PLACECALL_API_KEY environment variable or the agent's secure settings. Never ask for the key in chat, never print it, and never search the disk for credential files.

curl -s -H "X-API-Key: $PLACECALL_API_KEY" https://api.voygr.tech/users/me
# 200 {"customer_id":"...","credits_available":...,"max_concurrent_calls":...}

Step 2: Write the brief and confirm it

The call agent reads only the brief. Put every detail in it: what to ask, whose behalf you call on (there is no separate caller-name field), names, dates, party size, a callback number, and how to wrap up. Show the user the number and the brief and get a yes before dialling.

Step 3: Place the call

Generate a new UUID for Idempotency-Key for every call you intend to place, and keep it with that call.

curl -s -X POST https://api.voygr.tech/calls \
  -H "X-API-Key: $PLACECALL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c2a0e-0b8e-4c55-9a51-2d7d1f0b6c11" \
  -d '{
        "target_phone": "+15551234567",
        "brief": "Call this sports bar and find out (1) whether they are showing the USA vs Netherlands match today and (2) whether a reservation is needed. Read the answers back to confirm, thank them, and end.",
        "language": "en",
        "ask_user_mode": "stream"
      }'
# -> 201 {"call":{"call_id":"...","status":"dialing",...},...}

• target_phone: E.164 (+1...). 911 and other N11 codes are refused with 422.
• brief: up to 4000 characters.
• language: auto (resolves to en) or one of en, es, fr, de, hi, ru, pt, ja, it, nl, sr, tr, pl. Anything else returns 422 unsupported_language.
• ask_user_mode: always send "stream", so mid-call questions reach the events feed you poll.
• The call id is nested: call.call_id. Some deployments answer 202 with status: "queued"; follow it the same way.

For bookings, the optional structured path validates details before anything is dialled: send "intent": "booking" with slots (target_phone, name, date as YYYY-MM-DD, time as HH:MM, party_size, optional phone_to_dictate) instead of a brief. A gap comes back as 422 missing_slots with a suggested_question for each missing slot. This path returns a flat call_id. Send either a brief or intent + slots, never both.

Step 4: Follow the call by polling events

Poll; do not hold a long-lived curl -N stream open. Use the after_event_id query parameter.

ID=<call_id>; LAST=0; STOP=$(($(date +%s)+120))
while [ "$(date +%s)" -lt "$STOP" ]; do
  OUT=$(curl -s --max-time 20 -H "X-API-Key: $PLACECALL_API_KEY" \
        "https://api.voygr.tech/calls/$ID/events?after_event_id=$LAST")
  [ -n "$OUT" ] && echo "$OUT"
  N=$(printf '%s' "$OUT" | sed -n 's/^id: //p' | tail -1); [ -n "$N" ] && LAST=$N
  printf '%s' "$OUT" | grep -q '^event: outcome'  && { echo "### OUTCOME ###"; break; }

…