Build on AI Phone 360

curl https://api.aiphone360.com/api/public/v1/calls?limit=5 \
  -H "Authorization: Bearer aip_live_your_key_here"

curl -X POST https://api.aiphone360.com/api/public/v1/messages \
  -H "Authorization: Bearer aip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15555550123","body":"Thanks for calling!"}'

Authorization: Bearer aip_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys secret. A key is shown once at creation — store it in a secret manager. Keys are scoped (least-privilege) and can be rotated or revoked instantly. Never embed a live key in client-side / browser / mobile code.

let cursor;
do {
  const page = await client.calls.list({ cursor, limit: 100 });
  for (const call of page.data) { /* … */ }
  cursor = page.pagination.nextCursor;
} while (cursor);

{ "success": true, "data": { …payload… }, "message": "…" }

{ "success": false, "error": { "message": "…", "code": "INSUFFICIENT_SCOPE", "status": 403 } }

TCPA / DNC is enforced server-side. A send to a number that opted out (replied STOP), or that you have no established relationship with, is blocked with a 422. This is the same compliance chokepoint the app uses — it protects your number's reputation. Pass an Idempotency-Key header so retries never double-send.

AI config

Read a curated subset of your AI configuration. Scope read:usage.

Update a curated, safe subset of config (e.g. language, timezone, call-handling mode). Scope manage:config. Sensitive settings (payments, spam, PII) are never writable via the API.

Webhooks (manage)

Scope manage:webhooks for all of these. See the Receiving webhooks guide for the delivery format.

Register an endpoint. Body: url (public HTTPS), events (array). Returns a whsec_… signing secret — store it to verify deliveries.

Send a test delivery to verify your endpoint.

Inspect delivery history and replay any delivery.

API keys (manage)

List your keys (masked). Scope read:usage.

Create a key — returns the secret once. Scope manage:config. Body: name, mode (test|live), scopes.

Revoke, or rotate with a grace window so you can roll the new key out with zero downtime.

Custom tools (manage)

Scope manage:tools. See the AI calls your systems guide.

AI agents (manage)

Scope manage:agents. Define multiple specialized AI agents for one business — e.g. a billing agent that can send a payment link and collect an invoice number, and a product-support agent that collects a serial number and searches only that product's knowledge. A main greeter agent (isDefault: true) answers every call and hands off in-call to the right specialist; the caller goes AI → AI in the same call, no redial. Define no agents and your single AI agent handles everything (default).

Create body: agentKey (lowercase id, unique per business), displayName, instructions (the specialist's focused role — knowledge comes from your knowledge base via RAG, don't paste it here), matchHints[] (caller-intent phrases the greeter routes on), tools ({ useCustomToolIds[], allowPayments, allowBooking, allowTransfer, allowKnowledgeSearch } — useCustomToolIds empty = the agent may use all your custom tools), knowledgeBaseIds[] (RAG scope — empty = all business knowledge), isDefault, enabled. Tool and knowledge-base ids must belong to your business. To make an agent collect specific fields, create a data-collection field with that agent's agentId.

curl -X POST https://api.aiphone360.com/api/public/v1/agents \
  -H "Authorization: Bearer aip_live_…" -H "Content-Type: application/json" \
  -d '{"agentKey":"billing","displayName":"Billing","instructions":"You handle billing. Collect the invoice number and offer a secure payment link.","matchHints":["bill","invoice","refund"],"tools":{"allowPayments":true}}'

Receiving webhooks

Register an HTTPS endpoint and AI Phone 360 will POST a JSON event the instant something happens. Delivery is at-least-once — dedupe on event.id. Each event:

{
  "id": "evt_…",
  "type": "call.completed",
  "createdAt": "2026-06-28T20:00:00Z",
  "businessId": "…",
  "data": { …event-specific payload… }
}

Event types

Event	Fires when
call.started	An inbound call begins.
call.completed	A call ends & post-call processing finishes (incl. summary).
transcript.ready	The transcript is available.
sms.received	An inbound text arrives.
sms.sent	An outbound text is sent.
voicemail.created	A voicemail is recorded.
contact.created / contact.updated	A contact is created / meaningfully changed.
appointment.booked	An appointment is booked.

Retries use exponential backoff; an endpoint that fails repeatedly is auto-disabled (you'll see it in delivery logs). Every delivery attempt is metered.

Verifying webhook signatures

Every delivery carries an X-AIP-Signature header: t=<unix>,v1=<hex> where v1 is HMAC-SHA256(secret, "<t>.<rawBody>"). Always verify before trusting the payload, using the whsec_ secret from when you created the endpoint. The SDK does this for you:

import { AiPhone360 } from "@aiphone360/sdk";
import express from "express";

app.post("/webhooks/aiphone", express.raw({ type: "application/json" }), (req, res) => {
  try {
    // Pass the RAW body bytes, not a parsed object.
    AiPhone360.verifyWebhook(req.body.toString("utf8"), req.headers["x-aip-signature"], process.env.AIP_WEBHOOK_SECRET);
  } catch {
    return res.status(400).send("bad signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // handle event.type …
  res.sendStatus(200);
});

Verification rejects a timestamp older than 5 minutes to stop replay attacks. Doing it manually in another language? Recompute the HMAC over `${t}.${rawBody}` and compare in constant time.

Let the AI call your systems

Custom tools let your AI receptionist call your API live during a phone call or text — to look up an order, check availability, create a ticket, anything. You describe the tool; AI Phone 360 calls your HTTPS endpoint when the conversation needs it and relays the result back to the AI.

1. Register a tool (dashboard or POST /tools) with a name, description, JSON-schema for its inputs, your HTTPS endpointUrl, and optional auth.
2. During a call, the AI decides to use it and AI Phone 360 POSTs { arguments, callSessionId, tool } to your endpoint.
3. Your endpoint responds with JSON within ~10 seconds; the AI uses it as data (never as instructions — results can't change call control flow).

Official SDK

The TypeScript/Node SDK wraps the API with types, automatic retries, cursor pagination, and webhook verification.

npm install @aiphone360/sdk

import { AiPhone360 } from "@aiphone360/sdk";

const client = new AiPhone360({ apiKey: process.env.AIP_KEY });
// mode is auto-detected from the key prefix (aip_test_ / aip_live_)

const { data } = await client.calls.list({ limit: 25 });
await client.sms.send({ to: "+15555550123", body: "Hi from our app" });
const contact = await client.contacts.create({ phoneNumber: "+15555550123", name: "Jordan" });

Errors throw a typed AiPhone360Error with code, status, and a requestId (give that to support). 429/5xx are retried automatically.