For AI agents
A strict, AI-ready operating guide: source files, account boundaries, reliable message verification, and the rules that keep a Beam integration safe.
Beam is designed so an AI can help a team without inventing product state, exposing credentials, or making a delivery claim it cannot prove. If you are an AI agent reading this, this is your operating map.
Ingest the docs
- llms-full.txt: every documentation page in one plain-text file. Read it once and you know the whole product.
- openapi.json: the complete API contract, OpenAPI 3.1. Every endpoint, schema, status enum, and the signed-webhook format.
- llms.txt: the lightweight index if you prefer to fetch pages on demand.
Authenticate
Two credentials exist. Ask the workspace owner for the least-privileged one and keep it on the server:
- Workspace API key (Settings → API key): use it as the
x-api-keyheader on every/v1/*endpoint. This is the key for sending, reading conversations, reacting, and checking delivery. - Login key (a seat's personal key): powers the web inbox at beam.aisync.link. Owner keys manage settings, seats, the assistant, and calendars; rep keys work conversations.
Operating playbook
Sending
POST /v1/messages with to and message. Beam handles channel choice, pacing, number pinning, and opt-outs. Never assume delivery from a 200: the send is queued.
Verify delivery
Poll GET /v1/messages/:id until status is delivered or failed, or subscribe to event webhooks. failed means the lead did not get it, react accordingly instead of pretending.
Reading conversations
GET /v1/conversations/:phone returns the full thread including who sent what (sender: human, bot, system). Use it for context before composing anything.
Managed email
Use /v1/email/* for domains, mailboxes, threads, sends, replies, plan state, and human takeover. Use a stable request_key for every email action and never choose a From address that is not returned by the workspace mailbox endpoint.
Being human
Blue-bubble contacts support /v1/typing, /v1/read, and /v1/reactions. Use them the way a person would: typing before a reply, a read receipt when you have seen a message, a tapback when words are unnecessary.
Events
Beam pushes signed events (message.received, assistant.booked with the appointment id, assistant.handoff, ...) to any HTTPS endpoint. Verify Beam-Signature before trusting a payload: HMAC-SHA256 of "t.body" with the signing secret.
Rules that keep you out of trouble
- Respect
opted_out. A 403 on send means stop messaging that contact, permanently, no workarounds. - Queued outreach follows recipient-local sending hours and line pacing. A genuine inbound text opens a one-hour reply window on that same workspace, contact, and assigned line. Fresh customer texts renew it. During that window, conversational inbox/CRM replies and the assistant may respond outside sending hours; opt-outs, workspace readiness, line limits, and saved AI response delays still apply.
- In a Beam conversation, use Turn off after-hours replies to close this exception until you enable it again. Normal sending hours still apply; this is separate from pausing the assistant. Re-enabling does not create a new hour: it only restores the time remaining since the customer's latest text. Old queued messages from before that text are not released by the exception.
- Campaign, API, and identified workflow messages do not receive the reply-window exception. CRM delivery callbacks without automation markers are treated as conversational; keep quiet-hour controls enabled in your CRM workflows as well. Connection status alone does not prove a message arrived: verify the phone and CRM conversation during testing.
- Never send the same text to many recipients. Vary every message; identical blasts destroy deliverability for the whole workspace.
- Report delivery honestly to your human.
sentis notdelivered. - The AI assistant built into Beam may already be answering a conversation (messages with
sender: "bot"). Check before you double-text a lead. - Email live-send autonomy starts off. An external agent must honor draft-only mode, stop on human takeover, and never retry an uncertain email result.