msgbubblesDocs

msgbubbles API

msgbubbles is a unified messaging API: send and receive iMessage, SMS, and WhatsApp from a real business phone number through one REST endpoint and one webhook URL. No Apple hardware, carrier accounts, or phone numbers to operate on your side.

Base URL

All endpoints live under /v1:

https://api.msgbubbles.com/v1

Requests and responses are JSON (attachments upload via multipart/form-data). Every request is authenticated with your API key — see Authentication.

Response format

Every successful response wraps its payload in a data envelope and carries a request_id (also returned as the X-Request-Id header) — quote it when reporting an issue:

Success envelope
{ "data": { /* the resource, or an array for lists */ }, "request_id": "req_…" }

Lists add a sibling has_more for cursor pagination, and errors share one shape too — see Errors & limits.

Quickstart

1. Get an API key

API keys are issued when your account is set up, in the form sk_live_… (or sk_test_… for test mode). The key is shown exactly once — store it in a secret manager.

2. Find your sendable numbers

Each account has one or more provisioned numbers. List them, and the channels each one serves, with:

List your numbers
curl https://api.msgbubbles.com/v1/numbers \
  -H "Authorization: Bearer sk_live_…"
Response
{
  "data": [
    {
      "handle": "+18005551111",
      "channels": ["imessage", "sms"],
      "label": null,
      "status": "online",
      "allocation": "dedicated"
    }
  ]
}

3. Send a message

Send a message
curl -X POST https://api.msgbubbles.com/v1/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{
    "to": "+15555550123",
    "from_handle": "+18005551111",
    "text": "hello from msgbubbles"
  }'

The API answers 202 with the message in status queued; delivery happens asynchronously. iMessage vs. SMS is decided per recipient automatically — blue or green bubbles, you send the same request. See Messages for the full request shape, statuses, and follow-up actions like editing and reactions.

4. Receive replies and receipts

Register a webhook and msgbubbles POSTs you message.received, message.delivered, message.read, and more — each delivery signed so you can verify it came from us. See Webhooks.

Configure your app

Keep your msgbubbles settings in server-side environment variables. In a Next.js app, put them in .env.localfor local development and in your host’s environment settings for production:

.env.local
MSGBUBBLES_API_KEY=sk_live_…
MSGBUBBLES_PHONE_NUMBER=+18005551111
MSGBUBBLES_WEBHOOK_URL=https://example.com/api/msgbubbles/events
MSGBUBBLES_WEBHOOK_SECRET=whsec_…
VariableWhat it holds
MSGBUBBLES_API_KEYYour sk_live_… key, sent as the bearer token on every request.
MSGBUBBLES_PHONE_NUMBERThe number you send from, passed as from_handle. Use a handle from GET /v1/numbers.
MSGBUBBLES_WEBHOOK_URLThe public URL you register with POST /v1/webhooks. Only the code that registers or updates the webhook needs it. localhost is rejected, so in local development register a public tunnel URL instead.
MSGBUBBLES_WEBHOOK_SECRETThe signing secret returned when you register the webhook. Your webhook handler verifies every delivery with it. Update it whenever you set or rotate the secret.

Don’t give these a NEXT_PUBLIC_ prefix. Next.js copies NEXT_PUBLIC_ values into the JavaScript it sends to the browser, which would publish your API key. Read them only in server code, such as route handlers and server actions:

lib/msgbubbles.ts
export async function sendText(to: string, text: string) {
  const res = await fetch("https://api.msgbubbles.com/v1/messages", {
    method: "POST",
    headers: {
      authorization: "Bearer " + process.env.MSGBUBBLES_API_KEY,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      to,
      from_handle: process.env.MSGBUBBLES_PHONE_NUMBER,
      text,
    }),
  });
  if (!res.ok) throw new Error("msgbubbles send failed: " + res.status);
  return (await res.json()).data;
}
app/api/msgbubbles/events/route.ts
import { verify } from "@/lib/verify-msgbubbles"; // verify() from the Webhooks page

export async function POST(request: Request) {
  // Verify the raw body. The signature covers the exact bytes we sent.
  const rawBody = await request.text();
  const header = request.headers.get("x-msgbubbles-signature") ?? "";
  if (!verify(process.env.MSGBUBBLES_WEBHOOK_SECRET!, rawBody, header)) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(rawBody);
  // Dedupe on event.message_id + event.type, then handle the event.
  return new Response(null, { status: 200 });
}

MSGBUBBLES_PHONE_NUMBER is the only one of these tied to a specific line. Whenever the number you send from changes, such as when you get a dedicated line or move from a shared (pooled) line to a dedicated one, set it to the new number and redeploy. The API key and webhook belong to your organization, so they stay the same. See Switching from a pooled line to a dedicated one for what else changes.

What you can build on

  • Messages — send text, effects, replies, tapback and emoji reactions; edit and unsend on iMessage.
  • Attachments — images, video, files, and native voice-note bubbles.
  • Conversations — threads are tracked for you; create and manage group chats (iMessage or group MMS), mark threads read, show typing indicators.
  • Webhooks — signed event deliveries with automatic retries.
  • OTP verification — phone sign-in where the user texts you the code, over iMessage, SMS, or WhatsApp. A separate product with its own host and keys — see OTP verification.