Build a phone agent with the Voiceflint API

1. Create the agent

Start from a preset and add one tool. Tools are JSON Schema functions; when the model calls one, Voiceflint POSTs the arguments to your URL and speaks the response.

curl -X POST https://voiceflint.com/api/v1/agents \
  -H "Authorization: Bearer vf_live_..." -H "content-type: application/json" \
  -d '{
    "name": "Front desk",
    "preset": "balanced",
    "region": "us-east",
    "systemPrompt": "You are the front desk for Acme Dental. Book cleanings on weekdays 9-5. Confirm the day and time back before booking.",
    "tools": [{"name": "book", "description": "Book a cleaning", "url": "https://example.com/book",
      "parameters": {"type": "object", "properties": {"day": {"type": "string"}, "time": {"type": "string"}, "name": {"type": "string"}}, "required": ["day", "time", "name"]}}]
  }'

2. Attach a number

Numbers are added under Numbers in the dashboard with your carrier's SIP credentials (Telnyx or Twilio). Point the number at the agent; inbound calls dispatch to the agent's region automatically. The list call confirms routing:

curl -H "Authorization: Bearer vf_live_..." https://voiceflint.com/api/v1/numbers

3. Place an outbound call

Outbound calls are refused when outbound is switched off in Settings, when the number is on your do-not-call list, outside the local calling window you configured, or over the 24-hour frequency cap. The response includes the call id.

curl -X POST https://voiceflint.com/api/v1/calls \
  -H "Authorization: Bearer vf_live_..." -H "content-type: application/json" \
  -d '{"agentId": "<agent id>", "to": "+14155550123", "metadata": {"crmId": "42"}}'

4. Read the receipt

When the call ends, the call resource carries one line per model at list price, the managed-key fee, telephony and the platform fee, plus a per-turn latency waterfall and the transcript.

curl -H "Authorization: Bearer vf_live_..." https://voiceflint.com/api/v1/calls/<call id>

5. Receive the webhook

Add an endpoint under Keys. Every completed call is POSTed as JSON with an HMAC-SHA256 signature over the raw body. Verify it before trusting the payload:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

6. Test without a phone

Enable the widget on the agent page and drop the script tag on any page; the same agent answers in the browser, and the call shows up with the same receipt. Simulated callers under Evals let you run scripted personas against the prompt after every change.

Questions

Is there an SDK?

The API is plain HTTPS with JSON; the widget script covers browser calls. Typed SDKs are next once the surface settles.

How do I use my own keys from the API?

Add provider keys under Keys once; set keyMode to byok on the agent. Those model lines then show $0 on every receipt.