# 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.
Beam's product standardUse the documentation to make the workflow simple for the operator, but keep the evidence strict: a queue receipt is not delivery, a calendar action is not booked until the calendar confirms it, and an unverified webhook is not trusted input.

## 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-key header 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

  SendingPOST /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 deliveryPoll 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 conversationsGET /v1/conversations/:phone returns the full thread including who sent what (sender: human, bot, system). Use it for context before composing anything.
  Managed emailUse /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 humanBlue-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.
  EventsBeam 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. sent is not delivered.
  - 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.