API documentation

Base URL: https://api.bluedialer.example

Fastest path: hand the implementation prompt to your coding agent. It builds everything below (sending, webhooks, opt-outs, limits) into your software for you. Your dashboard shows usage, messages and webhook settings.

Quickstart

  1. Create an account, then buy a line. Your API key appears immediately after payment.
  2. List your lines to get a deviceId: GET /api/devices.
  3. Send a message with POST /api/send.
  4. Set a webhook URL to receive replies and delivery status.

Authentication

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"

Send a message

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).

Photos & voice notes

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.

Voice calls (FaceTime Audio)

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:

  • Softphone: a person talks from the dashboard's Calls tab with a headset. Incoming calls ring every open dashboard tab when you set incoming calls to "Ring this dashboard".
  • Stream (for AI voice agents): we connect to your WebSocket and send the call's audio in the Twilio Media Streams format: 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.

Click-to-call in your own app

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).

Webhooks

We POST JSON to your webhook URL. Respond with a 2xx quickly; non-2xx and redirects are treated as failures.

message.inbound

{
  "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" }
}

message.status

{ "event": "message.status", "messageId": "msg_2", "status": "DELIVERED", "error": null, "updatedAt": "…" }

message.sent_from_other_device

A message the line's owner sent outside the API; same shape as message.inbound.

line.paused

{ "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.

Opt-outs (STOP)

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.

Verify signatures

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);
}

Message status

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.

Lines

GET /api/devices returns your lines with id, label, phoneNumber and online. GET /api/conversations and GET /api/conversations/:id/messages return history.

Limits

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 hours40
New contacts, rolling 60 minutes10
New line, week 1 / week 2 / weeks 3–4 (per day)10 / 20 / 30
Messages in a row with no reply100

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.

Errors

StatusMeaning
400Missing or invalid fields
401Missing or invalid API key
402Account suspended because the subscription ended
403Recipient opted out (code: "opted_out")
404Line not found for your account
423Line is paused (failing sends); contact support
429A per-line sending limit was reached; see Retry-After
503Line is offline; message was recorded as FAILED