Base URL: https://api.bluedialer.example
deviceId: GET /api/devices.POST /api/send.Send your key in the x-api-key header on every request. Keep it server-side; never ship it in browser or mobile code.
curl https://api.bluedialer.example/api/devices \
-H "x-api-key: $BLUEDIALER_KEY"
POST /api/send
{
"deviceId": "line_123", // required; from GET /api/devices
"to": "+15551234567", // required; E.164 number or Apple ID email
"body": "Hello!", // required unless mediaUrl is set
"mediaUrl": null // optional; public URL of an image or audio file
}
Returns 202 with the created message (status: "QUEUED"). Status then updates via webhook: SENT, then DELIVERED or FAILED. Returns 503 if the line is offline.
If the recipient isn't on iMessage, the message is sent as SMS automatically.
Sends are queued per line and go out at least a few seconds apart. Sending to someone who has replied STOP returns 403 with code: "opted_out" (see Opt-outs).
Pass mediaUrl to send an image or audio file; we download it once (public https URLs only, up to 20 MB, JPEG/PNG/GIF/WebP/HEIC, common audio and MP4/MOV; redirects aren't followed) and attach it. Inbound media arrives as message.mediaUrl on the webhook: images as JPEG/PNG and voice notes as audio/mp4, playable in any browser. Voice notes arrive with kind: "AUDIO_MESSAGE". Recipients see outgoing audio as an attachment rather than Apple's native voice-note bubble.
A line can place and receive FaceTime Audio calls. They reach iPhones, iPads and Macs (people without FaceTime can't be called this way). Audio is relayed live and never recorded. There are two ways to be on your end of a call:
connected, start, media (base64 8 kHz mu-law, 20 ms frames), mark, stop. Send media events back to speak, clear to stop what is playing (barge-in) and mark to be told when your audio has played. Send {"event":"hangup"} to end the call.POST /api/calls
{
"deviceId": "line_123",
"to": "+15551234567", // or an Apple ID email
"streamUrl": "wss://your-server.example/media"
}
→ 202 { "call": { "id": "...", "status": "REQUESTED", ... } }
GET /api/calls // recent calls
GET /api/calls/:id
POST /api/calls/:id/hangup
PUT /api/call-settings { "inbound": "off" | "softphone" | "stream", "streamUrl": "wss://..." }
Call status: REQUESTED → DIALING (outgoing) or RINGING (incoming) → CONNECTED → ENDED; or FAILED, MISSED, DECLINED. Each change is sent to your webhook as call.status, and incoming calls also send call.incoming. Our connection to your stream carries x-bluedialer-call-id, x-bluedialer-timestamp and x-bluedialer-signature = sha256=HMAC-SHA256 of callId.timestamp with your webhook secret; check it before accepting audio.
Put a Call button in your CRM: your backend exchanges its API key for a short-lived token (POST /api/softphone/token with {"user":"jane@you.com"}), and your page loads our script and calls one function. Your staff talk from the browser with a headset; incoming calls can ring there too. Your page must use HTTPS.
<script src="https://api.bluedialer.example/sdk/softphone.js"></script>
<script>
const phone = BlueDialerPhone.init({
getToken: () => fetch("/bluedialer-token").then(r => r.json()).then(d => d.token)
});
</script>
<button onclick="phone.call('+15551234567')">Call</button>
A call panel (Calling, Connected, Mute, Hang up; Answer/Decline for incoming) appears automatically, or pass ui:false and use the events (incoming, status, connected, ended, error) to build your own. Calls record who placed them (placedBy).
One call per line at a time. Calls count toward the line's new-contact limits like messages do, and each line can place up to 20 calls an hour; calls longer than 60 minutes are ended. You are responsible for calling only people who agreed to hear from you and for telling them when they are talking to an AI voice (Terms §13).
We POST JSON to your webhook URL. Respond with a 2xx quickly; non-2xx and redirects are treated as failures.
{
"event": "message.inbound",
"conversationId": "cnv_9f2",
"contactHandle": "+15551234567",
"isNewConversation": true,
"message": { "id": "msg_1", "kind": "IMESSAGE", "body": "hey", "mediaUrl": null, "createdAt": "2026-01-01T12:00:00Z" }
}
{ "event": "message.status", "messageId": "msg_2", "status": "DELIVERED", "error": null, "updatedAt": "…" }
A message the line's owner sent outside the API; same shape as message.inbound.
{ "event": "line.paused", "deviceId": "line_123", "reason": "consecutive send failures", "at": "…" }
Sent when a line is paused automatically because its sends are failing. Sends return 423 until it's reviewed.
Webhook URLs must be public https addresses. Failed deliveries (network errors, 5xx, 429) are retried after about 2 s, 15 s and 60 s, and every attempt of one event carries the same x-bluedialer-delivery header, so dedupe on it.
If a contact replies STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT, we stop sending to them from your account and the message.inbound webhook includes "optOut": "stop" so you can update your own records. START or UNSTOP re-enables sending ("optOut": "start"). Sends to an opted-out number return 403. You remain responsible for honoring opt-outs in your other channels.
Each delivery includes x-bluedialer-signature: sha256=<hex>, an HMAC-SHA256 of the raw request body using your webhook secret. Always verify before trusting a payload.
const crypto = require("crypto");
function verify(rawBody, header, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(header || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
QUEUED → SENT (we confirmed it left the line) → DELIVERED (the recipient's device acknowledged) or FAILED. SMS and some iMessages never produce a delivery receipt, so SENT can be the final state. A delivery receipt can arrive minutes after SENT.
GET /api/devices returns your lines with id, label, phoneNumber and online. GET /api/conversations and GET /api/conversations/:id/messages return history.
No per-message fees. Apple publishes no sending limits and can restrict a line at any time, so we cap new conversations per line. Staying inside the caps lowers the risk of a ban but cannot remove it. A "new contact" is a number you haven't exchanged messages with on that line in the last 30 days; replies in an ongoing conversation aren't counted against the new-contact caps.
| Limit (per line) | Value |
|---|---|
| New contacts, rolling 24 hours | 40 |
| New contacts, rolling 60 minutes | 10 |
| New line, week 1 / week 2 / weeks 3–4 (per day) | 10 / 20 / 30 |
| Messages in a row with no reply | 100 |
Check where you stand with GET /api/lines/:id/usage, which returns used, limit and remaining for each limit and whether the line is paused. Manage your card, plan or cancellation with POST /billing/portal (returns a Stripe-hosted URL).
Requests that would exceed a limit return 429 with a Retry-After header and the limit that was hit. A line whose recent sends are failing at an unusual rate is paused automatically and you're notified. A line banned because of how it was used incurs the replacement fee in Terms §7.
| Status | Meaning |
|---|---|
| 400 | Missing or invalid fields |
| 401 | Missing or invalid API key |
| 402 | Account suspended because the subscription ended |
| 403 | Recipient opted out (code: "opted_out") |
| 404 | Line not found for your account |
| 423 | Line is paused (failing sends); contact support |
| 429 | A per-line sending limit was reached; see Retry-After |
| 503 | Line is offline; message was recorded as FAILED |