An iMessage API built for replies, not just deliveries

Every /v1/* request carries your workspace key in an x-api-key header. Keep it server side. Requests and responses are JSON. Errors come back as a plain sentence in an error field with a matching HTTP status. Phone numbers are accepted as US 10 digit, 11 digit or full international format, and Beam normalizes them.

The whole surface is small enough to read in one sitting:

The OpenAPI file is the contract. Messaging, presence, numbers, the CRM opt-in webhook and email are all in it. Read the API introduction for the short map, or open the OpenAPI contract for the real thing.

Use an active workspace, an assigned line and one consented test phone you control. These examples follow Send a message, Webhook signing and Event webhooks. They are a test procedure and illustrative fixtures, not a captured customer exchange.

1. Configure an HTTPS receiver in Settings, Event webhooks. Store the signing secret on your server. It is separate from the API key.
2. Run the send request below after replacing both placeholders. Save the returned message ID.
3. Read that ID with the status request. Observe the receiving phone; an accepted request or message.sent event is not a delivery receipt.
4. Reply from the test phone and verify the signature before parsing or acting on the event. Correlate the reply by workspace and its from/to phone pair.
5. Record the actual channel and status. Repeat with an Android test phone to observe RCS or SMS eligibility for your assigned line. Do not claim a fallback route from a capability lookup alone.

curl --fail-with-body -X POST https://beam.aisync.link/v1/messages \
  -H "x-api-key: YOUR_WORKSPACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"YOUR_TEST_PHONE_E164","message":"Integration test: please reply Tuesday."}'

curl --fail-with-body https://beam.aisync.link/v1/messages/RETURNED_MESSAGE_ID \
  -H "x-api-key: YOUR_WORKSPACE_KEY"

The documented send response has this shape. The ID is illustrative; use the real returned value in your status request.

{"id":"41","status":"queued","to":"YOUR_TEST_PHONE_E164"}

Verify the exact raw bytes in Node.js

Save as verify-beam.mjs. Pass a raw Buffer from your HTTP receiver and the Beam-Signature header. Run verification before JSON middleware changes the body. This rejects malformed signatures and timestamps outside a five-minute window in either direction.

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

export function verifyBeamSignature(rawBody, header, secret, now = Date.now()) {
  if (!secret || !Buffer.isBuffer(rawBody) || typeof header !== "string") return false;
  const parts = header.split(",");
  if (parts.length !== 2 || !parts[0].startsWith("t=") || !parts[1].startsWith("v1=")) return false;
  const t = parts[0].slice(2);
  const hex = parts[1].slice(3);
  if (!t.length || [...t].some(c => c < "0" || c > "9")) return false;
  if (hex.length !== 64 || [...hex].some(c => !"0123456789abcdef".includes(c))) return false;
  const seconds = Number(t);
  if (!Number.isSafeInteger(seconds) || Math.abs(now / 1000 - seconds) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(t + ".").update(rawBody).digest();
  const supplied = Buffer.from(hex, "hex");
  return supplied.length === expected.length && timingSafeEqual(expected, supplied);
}

Recognize a signed reply

This illustrative payload follows the event guide's id/type/timestamp/data envelope. The public OpenAPI webhook schema currently lists event/created_at/data instead. Confirm the envelope on your own signed test delivery before connecting production automation; the example below uses the event guide, not a claim that the two schemas are identical.

{
  "id": "evt_example_reply",
  "type": "message.received",
  "timestamp": 1787340000,
  "data": {
    "from": "YOUR_TEST_PHONE_E164",
    "to": "YOUR_ASSIGNED_LINE_E164",
    "body": "Tuesday",
    "channel": "imessage",
    "attachments": []
  }
}

The timestamp above is a fixture, not a fresh signed delivery. Do not paste it into a live verification test. Generate a current signed fixture locally or receive a real reply from your authorized test phone. The inbound payload does not promise the outbound message ID: keep your own workspace/contact correlation.

After verification, deduplicate by workspace and event ID, durably store or enqueue the event, and return a 2xx promptly. Do not treat an in-memory deduplication set as durable storage. Beam documents one attempt, a five-second timeout and no automatic event retries. Reconcile missed events with conversation history and message listing.

Acceptance, delivery and replies are separate evidence

The public contract does not document a request_key for the v1 message-send body. Do not transfer the workflow endpoint's duplicate protection to this endpoint. A timeout calls for reconciliation before another send.

Keep reseller tenants separate

Map your internal tenant ID to its Beam workspace key and webhook secret on the server. Select that mapping from an authenticated account or a workspace-specific receiver route, never from a tenant value in an unverified body. Store status and event records under the workspace as well as the contact. A second client's identical phone number must not expose the first client's history.

Before handoff, use the business texting app checklist to confirm who owns replies and the business messaging use cases to choose one pilot workflow.

Send a message (curl).

curl -X POST https://beam.aisync.link/v1/messages \
  -H "x-api-key: YOUR_WORKSPACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "RECIPIENT_E164",
    "message": "Thursday at 10:00 or 2:30. Which works better?"
  }'

Response:

{
  "id": "41",
  "status": "queued",
  "to": "RECIPIENT_E164"
}

Optional fields on the same endpoint: first_name, attachments (public HTTPS links, up to 10 on blue bubbles and 3 on texts) and effect (a full screen effect that applies on blue bubbles and is ignored on texts). Cancel a message that is still queued with DELETE /v1/messages/:id. Reference: Send a message.

Check blue bubble support before you send (curl).

curl "https://beam.aisync.link/v1/availability/RECIPIENT_E164" \
  -H "x-api-key: YOUR_WORKSPACE_KEY"

Response:

{ "phone": "RECIPIENT_E164", "imessage": true }

null means the check could not complete. Treat that as unfinished, not as proof the phone is text only. For a list, screening accepts up to 25,000 numbers per check and reuses recent results for 24 hours. Screening does not deliver a message and does not notify the person. Reference: Check a list.

Send from Node (fetch).

const res = await fetch("https://beam.aisync.link/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.BEAM_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: process.env.RECIPIENT_E164,
    message: "Thanks for reaching out. What made you start looking?",
  }),
});

const data = await res.json();
// { id: "41", status: "queued", to: "..." }

Beam exposes its workspace as MCP tools, so an AI client can read conversations, train the assistant, pause automation, send a message and book an appointment, inside the permissions you grant.

Create the connection. Sign in as a workspace owner, open Settings, Developer access, MCP and API. Name the connection and choose its permissions. Read and train are selected by default. Publishing, automation, real sending and booking require explicit permission. Copy the token immediately: it expires after 90 days and cannot be displayed again.

Two supported transports.

• Streamable HTTP at https://beam.aisync.link/mcp with an Authorization: Bearer YOUR_TOKEN header. The endpoint is stateless and returns JSON responses.
• A stdio bridge for desktop clients. Download beam-mcp.mjs, save it locally, and run it with Node.js 20 or newer. No packages required.

Claude Code.

claude mcp add --transport http beam https://beam.aisync.link/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Codex.

codex mcp add beam --url https://beam.aisync.link/mcp \
  --bearer-token-env-var BEAM_TOKEN

Cursor.

{"mcpServers":{"beam":{"url":"https://beam.aisync.link/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}}

stdio bridge.

{
  "mcpServers": {
    "beam": {
      "command": "node",
      "args": ["/absolute/path/beam-mcp.mjs"],
      "env": { "BEAM_TOKEN": "YOUR_TOKEN" }
    }
  }
}

About ChatGPT, honestly. Beam's documentation supports bearer header HTTP and the stdio bridge. Hosted connectors that require OAuth only login are not supported yet. So a ChatGPT connector that can only authenticate through OAuth will not connect to Beam today. If your ChatGPT setup can call an MCP server with a custom Authorization header, or can call an HTTP endpoint directly, point it at the same URL and token. Otherwise use the HTTP API from your own backend and let ChatGPT call your backend. Do not assume a successful connection in one client proves compatibility with every cloud client.

Permissions map to tools.

Same tools over plain HTTP. GET /v2/tools returns the tools and argument schemas available to your token. POST /v2/tools executes one. Both use the same bearer token as MCP.

curl https://beam.aisync.link/v2/tools \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"assistant_read","arguments":{}}'

Reference: MCP and developer access.

Workflow sends do not go through POST /v1/messages with a pasted phone number. A Custom Webhook step posts to /api/crm/workflows/send with a workspace bearer token, and Beam reads the destination from the GoHighLevel contact in the connected location. GHL's own Send SMS action does not select the Beam channel and keeps using your default SMS provider.

The body carries location_id, contact_id, workflow_id, from, message, request_key, consent, assistant_mode and dry_run. Keep dry_run: true until you see status: validated and queued: false, then flip it for one test contact. Repeating the same request_key returns the same message id with duplicate: true rather than a second text.

New opted-in leads can also hit the opt-in webhook:

curl -X POST "https://beam.aisync.link/t/YOUR_WORKSPACE/optin?secret=YOUR_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"LEAD_E164","contact_id":"YOUR_CRM_CONTACT_ID"}'

It responds {"queued": true, "to": "..."} and returns queued: false on a repeat call for the same number, so a re-enrolled contact never gets a second first touch. This endpoint is for people who just asked to hear from you.

It is one integration, not a bolt-on: iMessage, RCS and SMS fallback, real read receipts and typing indicators on blue bubble threads, inbound calls to a Voice AI agent, and FaceTime Audio that connects directly to that agent all run through the same connected location. Your operator sees that a lead read the message and sees them typing, which is the moment a human reply turns into a booked call.

References: Send from GHL workflows, New lead webhook, GoHighLevel iMessage setup.