# Is Beam right for my business? (Documentation) > Understand the value, choose your first workflow and test it without guessing. More conversations. Less manual follow-up. Beam gives your business dedicated messaging lines, a shared team inbox and a customizable text assistant. Connect your CRM so your team can manage lead conversations without relying on employees’ personal phones. Use supported iMessage lines for the blue-message experience and configured SMS lines for other recipients. ## How can Beam help us get more replies? Beam gives you the tools to make follow-up more consistent and easier to answer: a recognizable business number, relevant assistant replies, a conversation history your team can see, and a clear next step. These are ways to improve your process, not a promise that the channel alone will double your response rate. Your audience, offer, timing and consent matter. ## What does that look like for my business? For example, a lead asks a roofing company about an estimate. The text assistant answers approved questions, asks what the customer needs and offers an available appointment from the connected calendar. A team member can take over when the request needs judgment. This is an illustrative workflow, not a customer case study or a guarantee. ## We already use GoHighLevel. Why add Beam? Keep GHL as your CRM. Beam adds dedicated messaging lines, a shared inbox and text-assistant controls to your communication setup. GHL messaging and calendar integrations require the correct location connection. Inbound call forwarding is a separate setup. Test the round trip before relying on it. Other CRMs can be integrated through the API and documented events; not every CRM has a native connection. ## Can I make the assistant sound like us? Yes. Configure your business answers, tone, qualification questions and booking behavior. Preview sample conversations before publishing. Technical teams can use MCP with Claude Code, Codex or Cursor to read configuration, save drafts, preview and publish approved changes. This is instruction customization, not model fine-tuning. The MCP currently manages the default assistant. ## Can my team stay in control? Yes. Use individual team logins, shared conversations and human takeover. Pause the built-in assistant before allowing a separate external agent to manage a conversation. Agencies use workspace-specific connections for each client, not a shared all-client token. ## What about Android, read receipts and calls? Configured SMS lines reach SMS recipients, including Android. Supported iMessage conversations can show available read signals and client reactions. Read receipts depend on channel and recipient settings. Configure inbound calls to a phone destination or supported AI receptionist endpoint. Do not describe FaceTime Audio as a verified Beam feature. ## Can it book appointments? Yes, using the calendar configured in Beam and available slots. MCP booking requires booking permission. Cancellation, rescheduling and automatic confirmation campaigns are not included in the MCP release. If other tools contact the same leads, coordinate their workflows after booking so they do not keep chasing an already-booked lead. No particular tag or suppression rule is automatically guaranteed. ## How do I test whether it works for us? Start with one workflow, such as responding to inbound estimate requests. Preview the assistant, then test a message and reply on a contact you own. Confirm the reply reaches the phone and appears in the right CRM record. For a controlled pilot, compare similar consented lead groups over the same period: unique leads who reply, qualified conversations and confirmed appointments. Do not count an API-accepted message as delivered. ## How do we start, and what does it cost? Open Beam to explore the preview and current plans in Billing. Live sending requires the applicable active plan and an assigned line; the assistant also needs an AI connection and valid business answers. Do not quote an unverified price or promise immediate activation. Begin with the quickstart, then connect your AI tool if you want developer control. ## What should we not assume? No guaranteed reply-rate multiplier, unlimited blasting or blanket registration exemption. Sending capacity, consent, opt-outs and channel requirements still apply. Documentation help does not connect your account. OAuth-only hosted AI connectors are not supported by this MCP release; use a documented compatible connection. --- # MCP and developer access (API Reference) > Connect your AI tools to train text bots and control your Beam workspace. Build on Beam Use your preferred AI coding tool or your own application to train the default text assistant, review conversations, pause automation, send texts and book appointments. Your connection is restricted to your own workspace. ## Create a connection The screenshots below show the actual Beam controls with demo data. Your workspace name will differ. Screenshots use a local preview; always connect to https://beam.aisync.link/mcp, not the local address shown in the images. - Sign in directly as a workspace owner, not Client view.- Open Settings → Developer access · MCP & API.- Name the connection and choose its permissions. Read and train are selected by default. Publishing, automation, real sending and booking require explicit permission.- Click Create connection token and copy the token immediately. It expires after 90 days and cannot be displayed again. Treat the token like a password. Store it in your client's secret environment. Never paste it into a conversation, public repository, screenshot or URL. Revoke a connection in Settings to stop future access. Removing or demoting its owner also stops access. 1. Choose the workspace and start with Read workspace and Train and preview. Click the image to enlarge. 2. Copy the newly created token into your private client configuration. This is a synthetic, masked token, not a real credential. ## Connect an MCP client ### Agencies helping clients Agency owners sign in to their agency workspace and open Settings → Developer access. Select the specific client in Workspace this connection can access before creating the token. Only directly managed clients are offered. Create one token per client. A token cannot switch workspaces, and access stops if that client leaves the agency. Client owners can also create their own tokens and revoke connections in their workspace. For clients that support Streamable HTTP with custom authorization headers, use https://beam.aisync.link/mcp and an Authorization: Bearer YOUR_TOKEN header. The endpoint is stateless and returns JSON responses. For desktop clients that support stdio servers, download the Beam bridge. Save it locally and run it with Node.js 20 or newer. No packages are required. Use this common configuration shape, adjusting the absolute path to your download: ``` { "mcpServers": { "beam": { "command": "node", "args": ["/absolute/path/beam-mcp.mjs"], "env": { "BEAM_TOKEN": "YOUR_TOKEN" } } } } ``` Configuration screens differ between clients. This release supports bearer-header HTTP and the stdio bridge. Hosted connectors that require OAuth-only login are not supported yet. Do not assume a successful connection in one client proves compatibility with every cloud client. ### Claude Code With BEAM_TOKEN supplied securely in your terminal environment, register the HTTP server: ``` claude mcp add --transport http beam https://beam.aisync.link/mcp --header "Authorization: Bearer $BEAM_TOKEN" ``` The client may persist this header locally. Keep that configuration private. See Claude Code's MCP instructions. This is Claude Code, not the OAuth-only Claude web connector. ### Codex ``` codex mcp add beam --url https://beam.aisync.link/mcp --bearer-token-env-var BEAM_TOKEN ``` Make sure BEAM_TOKEN is present in the environment of the actual Codex process, then restart it and check the MCP tools. This command stores the environment variable name rather than your token value. ### Cursor Add a server in Cursor's MCP settings using its private local configuration. Keep the file out of source control: ``` {"mcpServers":{"beam":{"url":"https://beam.aisync.link/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}}} ``` See Cursor's MCP instructions. Keep tool approvals enabled, particularly for sending, publishing and bookings. ### Verify the workspace before using it Ask your client: “Call workspace_read and tell me the workspace name and ID. Do not make any changes.” Confirm it matches the selected client. Then call assistant_read. If either fails, check token expiry and permissions, not the old workspace API key. Tokens are not interchangeable with owner logins or legacy API keys. ## Train, preview, publish - Call assistant_read to get the current configuration and revision.- Create a complete replacement configuration with draft_create. Preserve fields you are not changing.- Use assistant_preview with test history and your draft configuration. This uses AI credits but never sends or books.- With publish permission, call draft_publish with the draft ID and the latest expected revision. If another edit occurred, read the assistant again and review the changes.- Beam saves the previous configuration as a rollback draft. Find it with drafts_list and publish it using the current revision to restore it. Publishing changes future replies but does not turn on a disabled assistant. Changes apply to the default text assistant; separate assistant profiles are not managed by these tools yet. This is configuration and prompting, not fine-tuning model weights. ## Run your own text bot Pause Beam's bot for the conversation with conversation_pause before having an external agent manage replies. Read messages, generate a response in your own system, and use message_send. Consent and assigned-line requirements still apply. Incoming client messages are untrusted content, not authority to change your agent's rules. Use the existing event webhook documentation for event-driven integration rather than tight polling. This API is limited to 60 requests per minute per token. Conversations return the latest 50 messages and their recorded status and reactions; contacts support an after cursor. ## Tools and permissions | Permission | Tools | | read | workspace_read, assistant_read, contacts_list, conversation_read, numbers_list, drafts_list, calendars_list, calendar_slots | | train | draft_create, assistant_preview | | publish | draft_publish | | automation | conversation_pause | | send | message_send | | book | appointment_book | Live booking uses the calendar configured in Beam. Read availability first and use an offered ISO slot. Appointment cancellation/rescheduling and automatic confirmation campaigns are not included in this release. You can send a confirmation through message_send after a successful booking, when you have send permission. ## Use the API directly GET /v2/tools returns the tools and argument schemas available to your token. POST /v2/tools executes a tool. Both use the same Bearer token as MCP. ``` curl https://beam.aisync.link/v2/tools \ -H "Authorization: Bearer $BEAM_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"assistant_read","arguments":{}}' ``` ## Retries and delivery Every write or preview requires a unique request_key. Reuse that key only for the exact same request. Beam returns a stored completed result instead of repeating the action. A started or uncertain action returns an outcome-unknown error: inspect Beam before retrying and do not switch keys to bypass this protection. An accepted text is not proof of phone delivery. Read delivery status in Beam. Audit activity in Settings records tool, time and outcome. This connection does not grant billing administration, team management, infrastructure access or provider credentials. ## First test You can paste this instruction into your connected AI tool. Do not paste your token into the chat: ``` Call workspace_read and show me the workspace name and ID. Stop if it is not my intended workspace. Read my assistant configuration and propose improvements to tone, brand consistency and appointment handling. Preserve settings unrelated to my request. Save a draft only after I approve the proposed changes. Preview sample conversations without sending messages or booking appointments. Show me the results and wait for my approval before publishing anything. ``` For Techify, the owner should sign in directly to TECHIFY AI LLC and confirm that workspace name before making changes. Agencies must select each intended client separately. For your own cloud-hosted application, keep the token server-side in its secret manager and use the HTTP API or MCP endpoint. Do not embed it in a public browser app. Claude Code, Codex and Cursor setup instructions above describe specific supported paths, not a promise that every hosted connector accepts bearer authentication. Create a read-and-train token. Ask your client to read the assistant, save a small draft and preview it. Confirm that the live assistant did not change. Only then grant live permissions as needed and test a single message to your own test contact. Revoke the test token and confirm requests are rejected. --- # Route Beam calls into GoHighLevel (Documentation) > Choose where your Beam calls ring and enter your GoHighLevel forwarding number. ## How the call travels Your Beam number → your GHL phone number → your team or Voice AI. You only need to choose the number that should receive your calls. Beam handles the connection. This changes voice routing only, not your messaging number or SMS configuration. ## 1. Prepare the destination in GHL - Open your HighLevel sub-account. - Open Settings and Phone Numbers / Phone System. Choose a voice-capable number belonging to that sub-account and copy its full number with country code. - Configure that number's inbound call flow for the intended team, IVR, or Voice AI agent. Set working hours, ring timeouts, and a no-answer destination. - Call that GHL number directly first. Verify the intended recipient answers and both sides can hear each other. Do not forward the GHL number back to your Beam number. That creates a loop. Make sure your GHL call flow ends with your team, Voice AI, or voicemail. ## 2. Save the route in Beam - Sign into the intended Beam workspace with manager access. - Open Numbers and scroll to Inbound call routing. - Find the public Beam line your customers call. - Choose Forward to GHL / phone number. - Enter the dedicated GHL number and click Save phone route. Check the saved destination, not just the input. Example screen using a demo number. Enter your own GHL number in GHL destination phone number, then click Save phone route. Select the image to enlarge it. Changing the dropdown alone does not change the saved route. A successful save replaces that line's previous destination; existing routes on other lines stay unchanged. To restore an AI route, choose AI agent endpoint, paste the original secure inbound URL and save. Saved agent URLs are never displayed again. ## Why not paste a GHL webhook? This field takes a phone number, not a webhook URL. A workflow webhook receives data; it does not answer a live call. Enter the voice-enabled number from your GHL sub-account. ## 3. Complete a real call test - Call the public Beam number from an external phone, not just the GHL destination directly. - Confirm the intended GHL team or AI answers, two-way audio works, and caller ID is correct. Caller ID preservation depends on the upstream forwarding chain and must be tested. - Confirm the call is recorded under the correct workspace in Beam and the correct contact/call history in GHL. - Test no answer, busy, and after-hours behavior. Beam currently rings the destination for up to 25 seconds, so configure GHL answering/fallback to fit inside that window. - Repeat with a second call. A saved route or a passing software test is not evidence of handset audio or GHL logging. Forwarding adds a telephone call leg; voice usage charges may apply. It does not automatically synchronize recordings, transcripts, or workflow actions between products. Configure any required follow-up inside GHL. ## Official HighLevel references - Set up inbound call flow for Voice AI - Phone number configuration options - Twilio webhook setup and account requirements ## Troubleshooting If GHL answers directly but not through Beam, check that you saved the destination on the correct Beam line. Give support the Beam number, call time, and what happened. Never send login credentials. --- # CRM webhook delivery health (Documentation) > Understand delivery commands, activity notifications, retries, and the checks needed before launch. ## Delivery commands and notifications are different The endpoint POST /webhooks/crm/inbox distinguishes a request to send a message from a notification about a message already recorded in the CRM. - Provider commands: SMS or Email. These ask Beam to send through the configured workspace provider. They must pass signature, workspace, contact, and channel checks. Email additionally requires the separate email provider configuration. - Marketplace notification: OutboundMessage. This describes existing CRM activity. Beam records a small, deduplicated receipt and acknowledges it. It does not send the message again, copy the activity into another conversation, or change delivery status. The notification itself is not proof that a recipient received a message. - Contact notification: ContactUpdate. For an active connected workspace, Beam can fill blank names and CRM links on an existing phone contact. The phone and existing CRM link must match. It does not create contacts, change phone numbers, overwrite existing names, or turn off an existing opt-out. Affirmative CRM SMS opt-outs are respected. If the phone is missing or invalid, Beam records the notification without changing a contact. Email-only contacts and a full contact-directory import are outside this handler. Do not change an OutboundMessage notification into an SMS command to make an error disappear. That can send an existing message a second time. Other event families are not automatically accepted by this endpoint. ## If HighLevel reports a low success rate - Open the BEAM app in the HighLevel Marketplace dashboard and inspect a failed delivery. Record its event type, time, response code, and request identifier. Do not share its message body, credentials, or contact details. - Compare the response with the Beam server log. A 400 means the payload was rejected; a 401 means its signature was not accepted. A timeout or connection error needs a separate network check. - Check whether the app is sending activity notifications to the provider delivery URL. The two payload types have different purposes and fields. - After a repair, observe naturally arriving events. Notifications should receive a successful response only after their receipt is stored. A storage outage returns 503 so the sender can retry. - Verify one approved test message separately from notification health: one send, one recipient delivery, and the expected CRM timeline entry. A successful webhook response alone does not prove delivery. Do not bulk retry send commandsDo not replay production message bodies, disable signature verification, or make every request return 200 to clear an alert. Retrying a notification is not the same operation as asking a provider to send. ## Workspace and privacy boundaries Notification receipts are associated only with an active installation matching the signed location. If no active installation exists, Beam records an ignored receipt without assigning it to a workspace. Receipts store a digest and disposition, not message text, addresses, attachments, or raw payloads. A contact receipt and its permitted contact update commit together; failed storage is retried. Notification handling never sends messages or changes billing or voice routing. ## What to expect after a repair The alert covers a rolling monitoring window, so its percentage may remain low while old failures age out. Use recent successful deliveries as immediate evidence. If delivery has been disabled in the Marketplace dashboard, an authorized app administrator must check its status before declaring recovery. References: provider delivery commands, outbound activity notifications, and signature and retry rules. --- # Overview (Documentation) > A practical start-to-finish guide to Beam: reach iPhone and Android customers, manage every reply in one inbox, and move conversations from first response to booked call. 01 / Meet Beam · iMessage + CRM + AIYour CRM.Your AI.Now in blue.Dedicated iMessage lines for your business. Connect your GoHighLevel workspace, let your text assistant handle the conversation, and turn the next reply into the next appointment.Explore Beam →Take the 2-minute tour ↓iMessage on supported lines and devices. SMS where configured. One workspace for your team. Shared conversation workspaceOne shared thread for replies, ownership, AI activity, and the next step. 02 / A conversation, not another blast ## From “just looking”to “see you Tuesday.” Your leads already live in their messages. Meet them there with a recognizable business number, useful answers and a clear next step. Keep your team in control when the conversation needs a human.Illustrative conversation, not a customer result. Reply and conversion rates depend on your audience, consent, offer and follow-up.Your business Dedicated lineHey, can I ask a few questions before booking?Of course. What would you like to know?Do you have anything Tuesday afternoon?There’s a 2:30 opening. Would that work for you?Perfect, let’s do it. ♥Your team + your assistant. One thread. 03 / The blue-message experience ## A business line.A more personal conversation. Bring familiar messaging features into your sales workflow, with visibility for the people responsible for the relationship.↗ ### Dedicated iMessage lines A consistent business number for supported iMessage conversations, separate from your team’s personal phones.✓ ### Read receipts See available read signals and configure outgoing receipts. Receipt availability depends on channel and recipient settings.♥ ### Client reactions See supported reactions on messages. A reaction alone does not instruct the assistant to send another reply.↔ ### Human takeover Let your team take over a conversation, review the history and keep the relationship moving. 04 / Keep the CRM. Upgrade the conversation. ## GoHighLevel, meet Beam. Connect your client’s GHL location to bring messaging into its CRM workflow. Use the connected calendar for availability and booking, while Beam manages the messaging workspace.Lead enters CRM→Beam conversation→Qualified next step→Calendar bookingBuilding on another CRM? Use Beam’s API and documented events to build your integration. Direct setup and supported capabilities vary by CRM.Explore the API and MCP guide → 05 / Your assistant. Your way. ## Train the answers.Keep your personality. Configure your business knowledge, tone and qualification rules. Preview replies before publishing. Use AI-assisted text conversations across your configured messaging channels, including SMS.01 ### Teach Give your assistant the business context and boundaries that make an answer useful.02 ### Rehearse Test sample conversations in preview without messaging customers or creating bookings.03 ### Approve Publish approved instructions and let your team step in when needed. 06 / When they call instead ## Send inbound callsto the right place. Configure an inbound phone destination or supported AI receptionist endpoint for your line. Route callers to your GHL number or your existing agent setup, then verify the route with a live test call.Explore line setup →Incoming callYour business line↓Your team or AI receptionistOne configured destination. A clear handoff. 07 / Built for builders and agencies ## Don’t stop at the settings screen. Connect Claude Code, Codex or Cursor through MCP. Review conversations, improve assistant instructions, preview drafts and approve live actions. Or build your own workflow with the API.Each connection is scoped to one workspace. Agencies create separate connections for each client. Sending, publishing and booking require explicit permissions. Supported bearer-token and desktop connections are documented; OAuth-only hosted connectors are not supported yet.Build on Beam → Blue + greeniMessage and configured SMS coverageDedicatedbusiness lines, shared team inboxCRM + APIconnect your follow-up workflows More than blue bubbles ## Android leads count, too.Scale the follow-up, not the busywork. Use dedicated SMS lines to reach Android customers and other SMS recipients. Connect your CRM or API workflows to send personalized, consent-based follow-up, then manage replies with your team and AI assistant.● ### Green-bubble SMS Keep SMS conversations alongside supported iMessage conversations in one workspace. Channel availability depends on your assigned lines.↗ ### Capacity for your workflow Size your line capacity around your audience and sending volume. Sending remains subject to pacing, plan capacity and carrier limits, not unlimited instant blasting.Registration depends on the channel and number type. Do not assume SMS traffic is exempt from A2P registration or verification. Confirm requirements for your assigned lines before launching a campaign. Marketing consent and opt-out requirements still apply. One customer messaging system ## Reach iPhone and Android customers from one managed inbox. You choose the messaging capacity your team needs. Beam uses blue-bubble messaging when supported and standard text everywhere else, while every reply stays in the same workspace.●Customer messaging ### Send through the best available channel. Beam handles the technical line mix for you: blue-bubble messaging when supported, standard text otherwise, with one shared conversation record.See how messaging works →✓Shared inbox ### Keep every response in one place. Your team sees the customer, conversation, delivery state, owner, assistant activity, and next step without managing separate messaging systems.Explore the inbox →@Managed email ### Continue one-to-one conversations on a verified domain. Send and receive threaded email, share drafts and notes, and keep delivery health visible without giving clients provider credentials.Set up Beam Email →One plan, clear coverageYou buy customer messaging capacity—not separate technologies. Agencies and operators can still see the exact line mix they need for fulfillment and support. Start without guessing ## From account to active line in three clear steps. You do not have to configure everything before you see the product. Build the workspace first, then activate only when the plan and number are right. 01 ### Create your workspace Use your work email and business name. Beam opens a private preview with safe sample data. Nothing sends.Create preview → 02 ### Explore the operating system Try the inbox, see AI-to-human handoff, connect your CRM, and set your area-code preferences.Take the product tour → 03 ### Select your plan and activate In Billing, select the currently published Starter, Team, or Scale plan. Payment creates a tracked request; a dedicated line is assigned before sending unlocks.See activation rules → Built for the moment a lead responds ## Not another campaign tool. The system behind the reply. Beam keeps each relationship in one thread while your team, assistant, CRM, and calendar work from the same recorded context.See the message routing map →↗ ### Lead-to-inbox continuity Use dedicated business numbers so the conversation stays recognizable when a lead replies.✦ ### AI that knows when to hand off Let the assistant qualify and book, while your team can take control at any time.⌁ ### Operational reporting Read recorded delivery, reply, pacing, and appointment signals, not invented opens.◌ ### Built with guardrails New outbound-first conversations are paced; active replies keep moving normally. Your team and AI share a source of truth ## Ask Claude or Codex exactly how to build your next workflow. Every docs page prepares a prompt grounded in Beam's full documentation and API contract. It deliberately excludes account access, client records, and credentials.Open the AI guide →View the agent playbook Ready when you are ## Open a workspace. See the difference before you commit. Create a private preview, then choose the plan and capacity that matches your real sales motion.Create your free preview → --- # Launch a client workspace (Documentation) > The exact Super Admin checklist that turns a new Beam workspace into a verified client launch. One source of truthThe full launch checklist is in Beam under Platform, Client launches. This page is the team playbook. A workspace is not called live until the recorded checks are complete. ## What the client needs to do Explore first. Preview owners can open Inbox, Analytics, Grow, Screening, Assistant, Email, Numbers, Billing, and Settings. The sample conversation with Alex is a private practice exercise: Alex is fictional, no message leaves Beam, and no phone or customer is contacted. It lets you try a reply, team takeover, call handling, and booking before connecting a real number. Agencies also see Clients and their own agency branding. Live sending and paid services stay locked until the matching plan is active. Super Admin controls are never exposed to a client. - Choose the plan. Billing must be confirmed before sending can unlock. - Connect their CRM, if they use one. Choose the one client account during authorization. - Forward each public business line. The client line forwards to Beam's shared inbound gateway. The forwarding provider must preserve the number originally dialed. - Approve the assistant. The client owner reviews draft-mode behavior before live assistant sending is enabled. ## What the Beam team verifies 1. Create the workspace and owner sign-inWhen an agency creates a client workspace, enter the client owner's real email. Beam does not send an invitation or reveal a reusable owner key. Give the client the normal Beam sign-in link; they enter that address and request their own six-digit code. An owner email belongs to one owner identity, so resolve an existing-account conflict instead of creating a second ambiguous sign-in. 2. Confirm billing and line assignmentBeam shows the real payment state and active assigned lines. Do not mark this complete based on an expected plan or a pending number request. 3. Assign the inbound receptionistEvery active Beam line needs its own approved inbound agent endpoint. Calls are never routed by guessing. 4. Confirm forwardingCall each public client number from a separate phone. Confirm the shared gateway receives the original dialed-line identity and routes to the correct receptionist. 5. Run the messaging testSend one inbound text. It must appear once in Beam. Send one intentional reply and confirm the recipient receives it once. 6. Run the CRM test, when connectedSend one message from the CRM to Beam and one reply from Beam to the same CRM contact. Both directions must stay on the same record. 7. Test the assistant and takeoverStart in draft mode. Verify business rules, calendar actions, and handoff behavior. A human reply must immediately pause the assistant for that conversation. 8. Approve the launchOnly a Super Admin can approve a completed launch. The approval records who approved it and when. It does not replace the safety controls already enforced by billing and number assignment. ## When to stop Do not approve a launch with a guessStop and mark the step blocked if a call does not reach the assigned agent, a message is duplicated or missing, a CRM record is unclear, or the assistant takes action without a confirmed result. Add the blocker to Client launches so the next operator has the real context. ## Client-facing next steps After launch, the client uses the Inbox for conversations, Numbers to view their assigned lines, Settings for their connection status, and the Assistant page to review their business rules. Platform launch details remain visible only to Super Admin. --- # Quickstart (Documentation) > Learn the authenticated send flow and the readiness checks that must pass first. ## 1. Get your API key Sign in with your email, then open Settings. API keys are for technical integrations only. Keep them server-side. ## 2. Send a message curlJavaScriptPythonCopy ``` curl -X POST https://beam.aisync.link/v1/messages \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "message": "Hey Sarah, thanks for reaching out. What made you start looking?", "first_name": "Sarah" }' ``` ``` 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: "+15551234567", message: "Hey Sarah, thanks for reaching out. What made you start looking?", first_name: "Sarah", }), }); console.log(await res.json()); ``` ``` import os, requests res = requests.post( "https://beam.aisync.link/v1/messages", headers={"x-api-key": os.environ["BEAM_KEY"]}, json={ "to": "+15551234567", "message": "Hey Sarah, thanks for reaching out. What made you start looking?", "first_name": "Sarah", }, ) print(res.json()) ``` You get back a message id and status: "queued". Beam checks whether the recipient's phone supports blue bubbles, picks the right channel, and sends at a human pace inside business hours. ## 3. Watch the inbox Open your Beam inbox. The conversation appears as soon as the message sends, and the reply lands right under it. That is the whole loop. Where did my message go?If you sent outside business hours, it is waiting for the morning window. Check it any time with Get a message. ## Next steps - Connect your CRM so every new lead gets this automatically. - Turn on the human touch: reactions, typing, read receipts. - Read Best practices before writing your first-touch template. --- # Connect your CRM (Documentation) > Keep contacts, calendars, and one-to-one messages connected to Beam without splitting the conversation. ## What you are building When a lead opts in, your workflow calls Beam. Beam checks their phone, sends the right kind of message from your number, and tags the contact so the rest of your automation knows what happened. | Tag | When it appears | | imessage-sent | The first blue-bubble message went out. | | beam-sms-sent | The lead's phone does not support blue bubbles, so a text went out instead. | | imessage-replied | The lead replied. This is your hottest signal. Trigger your AI call here. | ## Part 1: connect contacts and calendars Open the client accountCopy its account or location ID from the CRM's business settings. Create a restricted credentialGive it only the contact and calendar permissions Beam needs. Enter it in Beam Settings; it is encrypted and is never shown again. Save and verifyBeam checks the live account before showing Connected. A stored credential without a successful read-back stays Not connected. ## Part 2: let the team reply from the CRM inbox Click Connect CRM inboxUse the secure installation screen to choose this client account. No password or token is pasted into chat or exposed in the browser. Choose the Beam channel in a conversationBeam appears as an additional inbox channel. The CRM's existing phone workflows remain separate and unchanged. Run the same-contact testText the Beam line from an authorized test phone, then reply from the CRM. Both directions must stay on one CRM contact and the same Beam conversation. Conversation-first limits still applyA CRM reply enters Beam's normal send queue. A brand-new outbound-first conversation uses one unit; replies, follow-ups, inbound-first conversations, and opt-outs never add another unit. Blue and text capacity remain separate. Honest message statesThe CRM receives only pending, delivered, or failed states backed by Beam's recorded send path. Beam does not invent open or read status. ## Part 3: wire the lead flow For follow-ups or custom text at any workflow step, use Send from GHL workflows. The opt-in example below sends only the configured first introduction and skips already-contacted leads. Copy your webhook URL from Beam SettingsIt is unique to your workspace and carries its own secret. One click copies it. Open your CRM opt-in workflowUse the workflow that fires when a new lead comes in (form submitted, survey completed, or contact created). Add a Custom Webhook actionMethod POST, paste the URL, and map the request body below to your CRM contact fields. Save and test with your own numberRun one test contact with your own phone. You should get a message within a few minutes and see the imessage-sent tag appear on the contact. Webhook URLRequest bodyCopy ``` https://beam.aisync.link/t/YOUR_WORKSPACE/optin?secret=YOUR_WEBHOOK_SECRET ``` ``` { "phone": "{{contact.phone}}", "first_name": "{{contact.first_name}}", "contact_id": "{{contact.id}}" } ``` Duplicate protectionRepeated copies of the same accepted event reuse the existing Beam message instead of creating a second send. ## React to replies Build a second workflow triggered by the imessage-replied tag. This is where results compound: start your voice workflow while the lead is already holding their phone. See Voice, paired with messaging. Keep the first message personalThe first touch is a conversation starter from a real person, not a broadcast. Short, casual, ends with a question. Read Best practices before changing the template. --- # The Inbox (Documentation) > Every conversation across every number, in one place your team can answer. ## Threads The left panel lists every conversation, newest activity first. A channel badge identifies email, blue messaging, SMS/MMS, or calls. Email threads retain their subject and recipients. Unread counts stay until someone on your team opens the thread. ## Reading and replying Open a thread to see its full history, delivery state, attachments, notes, assignment, provider events, and attributable assistant or human actions. Email compose includes recipients, subject, draft state, and reply threading. ## The human touch, built in - Typing indicator. While you type a reply to a blue-bubble contact, they see the real typing bubbles on their phone. - Read receipts. Opening a thread with new messages sends a real read receipt. The lead sees "Read", exactly like texting a friend. - Reactions. Hover any of their messages and tap a reaction. A real tapback lands on their message. See Reactions, typing and read receipts. ## Photos and attachments Photos a lead sends appear right in the thread. Click to open the full size. ## Opt-outs If a contact replies STOP, the thread locks: Beam marks them opted out and the composer is disabled for that contact. This is automatic and required by law. See Compliance. ## Stats that matter The header shows sent, replied, and reply rate. Reply rate is the one number that predicts everything else: revenue and number health both follow it. Above 20% on warm leads is strong. --- # Reactions, typing & read receipts (Documentation) > The three signals that make a conversation feel human. Beam sends the real thing, not a simulation. ## Why this matters People decide within two messages whether they are talking to a person or a machine, and they stop replying to machines. Typing bubbles, read receipts, and tapback reactions are the three signals phones use to show a live human on the other end. Beam sends all three, for real, on blue-bubble conversations. ## Typing indicator Start typing a reply in the inbox and the lead's phone shows the typing bubbles. Stop typing and they fade, just like a real conversation. Nothing to configure. ## Read receipts When your team opens a thread with new messages, Beam sends a real read receipt. The lead sees "Read" under their message. Combined with the typing indicator, the lead watches you read their message and start replying, seconds apart, which is exactly what a fast human on an iPhone looks like. ## Reactions Hover a lead's message in the inbox and pick a tapback: | Reaction | What lands on their phone | | ❤️ love | A heart on their message | | 👍 like | A thumbs up | | 👎 dislike | A thumbs down | | 😂 laugh | A "HAHA" | | ‼️ emphasize | An exclamation emphasis | | ❓ question | A question mark | Reacting with a ❤️ to a lead saying "sounds great" keeps the conversation warm without another message. It is also available in the API so your automations can do it. Blue bubbles onlyThese three features are part of the iMessage channel. Texting (SMS) does not support them, so Beam only offers them on blue-bubble threads. --- # Photos & attachments (Documentation) > Send images and files in both directions. ## Receiving Photos and files a lead sends show up right in the inbox thread. Images render inline, other files show as a link. ## Sending via the API Add an attachments array of public HTTPS links to Send a message. Beam delivers them with the message. curlCopy ``` curl -X POST https://beam.aisync.link/v1/messages \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "message": "Here is the before and after from last week", "attachments": ["https://yoursite.com/results.jpg"] }' ``` ## Limits | Channel | Attachments per message | Notes | | Blue bubble | Up to 10 | Images, video, PDF and more | | Text (MMS) | Up to 3 | About 5MB total. JPEG, PNG and GIF are the safe bets | - Links must be public HTTPS URLs ending in a file extension. - JPEG and PNG deliver most reliably everywhere. Avoid WEBP and SVG. Email attachments use a stricter policyEmail compose accepts up to 10 approved files, 10 MB each and 20 MB total. Beam checks type, size, ownership, and authorized download before an attachment enters a conversation. --- # Numbers & warm-up (Documentation) > Your dedicated lines: how to get them, and how Beam keeps them healthy. ## Your numbers The Numbers tab shows every line in your workspace, its channels, and its current warm-up pace. Each conversation belongs to exactly one number: the first number a contact hears from is their number forever, so their entire history stays in one thread on their phone. ## Adding a number The Numbers tab shows your readiness state. Confirmed payment creates one tracked request for the selected plan allocation. A platform administrator then assigns the dedicated lines; only an active assignment unlocks sending. Area codes are preferences, never a promise. Need your established business number to appear on outbound calls? Complete the separate verified caller ID checklist. It does not change Beam messaging or inbound routing. Health scoresBeam grades available numbers before they are offered. A score is an operational signal, not a delivery guarantee: use only lines whose provider lease and recorded health are confirmed. If health is unavailable or at risk, stop and ask the platform team to verify the line before use. ## Warm-up: why your new number starts slow A brand-new number that sends 200 messages on day one looks exactly like spam to the systems that watch for it. Beam ramps every new line gradually: a conservative daily cap that grows over weeks of healthy sending. You will see the current pace on each number's card. ## Scaling with more lines One line comfortably handles dozens of new conversations a day. Need more? Add lines and Beam spreads new contacts across them while keeping every existing relationship pinned to its original number. ## What can hurt a number - Blast-style identical messages to many people - Messaging people who never asked to hear from you - Sudden volume spikes - Low reply rates over a sustained period The full story is in Number health. --- # Inbound call routing (Documentation) > Route inbound calls to an AI voice agent or your team while calls and texts stay on one CRM contact. ## One caller, one contact Beam uses the caller's phone number as the shared identity. When the same person calls and texts, both activities stay on one Beam conversation and resolve to the same CRM contact. ## Set up call routing Finish workspace activationCall routing stays unavailable until your workspace is active and a Beam messaging line has been assigned by an operator. Open NumbersOpen Inbound call routing for the assigned Beam line. Beam does not ask you for a forwarding number or phone-provider credentials in this workspace. Copy the RizzDial Inbound URLIn RizzDial, go to AI Agents, open the three-dot menu beside the correct agent, choose Endpoints, select Inbound, and choose Copy URL. Do not use the Outbound URL. Paste and connectPaste the copied Inbound URL into that Beam line's Inbound receptionist endpoint field and choose Connect. Treat the URL as a secret: never paste it into chat, notes, or a spreadsheet. Configure the shared ingress onceYour operator connects the shared inbound line to Beam. The forwarding system must include the original public-line identity with every call so Beam can select the right receptionist. Keep call behavior in the receptionistTransfers, appointment booking, and fallback behavior stay in the receptionist's own settings. Beam selects which receptionist handles the call; it does not override the receptionist's conversation logic. Place a real test callSetup is complete only when the selected receptionist answers, the call appears on the same contact as that caller's texts, and Beam records the final outcome. ## What Beam records - The caller and inbound line - Which inbound receptionist was selected for the public line, without displaying its saved connection URL - Connected, completed, busy, no answer, failed, or canceled outcomes - Call time and duration when available - The matching Beam conversation and CRM contact No account credentials neededA Beam-managed line uses Beam's server-side connection. Never paste phone-service credentials into chat, email, tickets, or screenshots. A selected receptionist is not live proofPlace one safe real call and confirm the selected receptionist answers, the call lands on the same contact as that caller's texts, and Beam records the final outcome before using the number with leads. --- # Show your business number on calls (Documentation) > Set a verified caller ID for outbound voice calls without changing Beam messaging or inbound routing. Voice onlyA verified caller ID changes the number a recipient sees on an outbound voice call. Some teams call this caller-ID masking. It does not change the sender for Beam blue messages, SMS/MMS, email, inbound-call routing, or consent obligations. ## When to use this Use it when your team places calls from an existing business number and wants customers to recognize that number. Keep the Beam-assigned line attached to the Beam conversation; do not replace it or paste external carrier credentials into Beam. ## Choose the right place to set it up | If the client places calls from… | Set up the verified caller ID in… | Keep in Beam | | A HighLevel sub-account | That client's HighLevel sub-account | The Beam-assigned messaging line and its inbound receptionist mapping | | A direct Twilio account | That client's Twilio account | The Beam-assigned messaging line and its inbound receptionist mapping | Do not add an agency's or another client's number to the wrong sub-account. The person or business that owns the number must complete verification. ## HighLevel setup - Switch to the correct client sub-account. - Open Settings → Phone Numbers and add a verified caller ID. - Enter the business number. The number owner answers the verification call and enters the one-time code. - Open the configuration for the outbound voice number and select Use verified number as caller ID for outbound calls. - Place one safe call to a team member. Confirm the displayed number, intended agent behavior, and Beam timeline. ## Direct Twilio setup - In the correct account, open Numbers and Senders → Verified caller IDs. - Add the business number and complete the verification call or code. - Use the verified number only as the From identity for outbound voice calls. - Run one safe outbound-call test before using it with leads. ## Do not mistake this for number masking - It does not let an unowned number send Beam SMS or blue messages. - It does not make inbound calls arrive in Beam; inbound forwarding and the Beam receptionist mapping remain separate. - It does not change the selected Beam line for an existing customer conversation. - It does not replace messaging registration, consent, opt-out, or caller-identification requirements. ## Verification checklist - Confirm the client owns and can answer the business number. - Complete verification in the correct client account or sub-account. - Attach it to the intended outbound voice number only. - Call a safe team phone and confirm the displayed caller ID. - Keep the result in the client's launch checklist. If the test fails, leave it off and use the assigned number until corrected. Official setup references: HighLevel verified caller ID and Twilio outgoing caller IDs. --- # How routing works (Documentation) > The path every message takes: from your CRM or inbox, through channel selection and pacing, to the lead's phone and back. ## The whole system on one picture New lead CRM workflow webhook Your team Inbox reply or new message API POST /v1/messages Beam engine channel check · warm-up pacing business hours · opt-out guard sticky number pinning Blue bubble their phone supports it Text (SMS) selected before sending The lead's phone Replies inbox · assistant · CRM tags Your CRM tags trigger the AI call ## Outbound: how a channel is chosen - Capability check. On first contact, Beam checks whether the lead's phone supports blue bubbles, and remembers the answer. - Line selection. Auto chooses an appropriate assigned line before sending. For a manual message, your team can choose a specific Blue or Green line in the From menu. - Sticky pinning. The first number a contact hears from is theirs forever. Their entire relationship lives in one thread on their phone. - Pacing gate. First touches pass through warm-up caps, business hours, and human-spaced timing. Replies in active conversations skip the gate, because answering fast is human. - Uncertain delivery stays uncertain. Beam does not automatically re-send a blue-bubble message or switch it to SMS after an ambiguous provider update. A teammate makes any intentional follow-up from the inbox. ## Inbound: how replies come back Replies flow into Beam on an instant event feed and a bounded reconciliation sweep. Beam stores a canonical message identity so the same physical message is shown once even if both paths observe it. An inbound reply lands in the inbox, can wake the assistant when that workspace has deliberately enabled it, and stops any approved follow-up sequence. ## Where your CRM fits Beam is the messaging brain; your CRM stays the system of record. Tags (imessage-sent, imessage-replied, bot-booked-call, bot-handoff) fire your existing workflows, including the AI voice call the moment a lead replies. Setup: Connect your account. --- # The Assistant (Documentation) > A practical, safe guide for owners and teams to train one Beam assistant for text and email before it speaks to a real lead. Start hereOne owner sets up and approves the assistant. Teammates use the inbox, take over when needed, and coach it from a real conversation. The assistant starts off, and nothing in the Playground is ever sent. ## Who does what | Person | What they do | | Workspace owner | Connects the AI account, adds business context, chooses the calendar and safety policy, tests it, then approves live behavior. | | Team member | Works conversations in Inbox, takes over when context or judgement is needed, and adds coaching feedback when a reply needs improvement. | | Client | Reviews the assistant's tone and business facts in their own workspace. They never need access to another client's data or your AI account. | ## Setup, in the order that works 1. Connect your OpenRouter accountIn Assistant, paste an OpenRouter API key and select a model. The key is used server-side for your workspace and is never shown back to your team. OpenRouter usage remains on your own account. 2. Explain the business like you would to a new hireDescribe what you sell, who buys it, typical price range, what makes a lead a fit, what happens next, and what must never be promised. Beam creates a starting playbook: a persona, qualification questions, common objections, and a booking approach. Review it before you go live. 3. Add owner rules in plain languageUse House Rules for business-specific corrections such as “Do not quote pricing until you know what service they need” or “Hand off all cancellation requests.” Rules apply to both text and email. Test every important rule in the Playground. 4. Pick the calendar and handoff conditionsChoose the real calendar the assistant may use. Add the situations where it must stop and hand a conversation to a person, such as legal questions, refunds, unusual pricing, or an angry customer. 5. Test before enablingUse the Playground's Text and Email tabs. Try a price question, a request for a human, a booking request, and an objection. It is a rehearsal only: it cannot send, queue, or create an appointment. 6. Start with draftsFor email, choose Draft only first. Review a few real drafts in Inbox. Enable live assistant behavior only after the owner is satisfied with the tests and the team knows when to take over. ## How the Playground works The Playground uses the workspace's actual playbook and active House Rules. Choose Text to see message bubbles or Email to see a threaded email draft. Type as a customer or start from a common scenario. Each simulated inbound can produce at most one assistant reply, and the result is never delivered to a contact. A simple approval testBefore enabling live behavior, run these four prompts in both channels: “What does this cost?”, “Can you call me tomorrow?”, “I need a human”, and “Please stop.” The assistant should answer facts it knows, avoid invented commitments, hand off the human request, and respect the stop request. ## How it sells - Uses the right format for the channel. Text replies are brief and conversational. Email replies use short, useful paragraphs and retain the email subject and thread context. - Books like a closer. Frames the call as valuable, proposes two concrete time windows, confirms the exact day and time in the lead's own words. Never sends a calendar link. - Never books the wrong day. A live clock rides along with every reply, the #1 failure of the bots you've used before. - Knows when to stop. An angry lead, legal topic, refund decision, stop request, or human takeover pauses assistant activity for that conversation. Your team can take the wheel from Inbox at any time. ## Real calendar booking Pick a booking calendar in the Assistant tab (any calendar in your connected CRM: round-robin, team, or personal) and the assistant becomes a true setter: - It only offers times that are actually open. Before every reply it reads the calendar's live availability for the next six days and proposes two real windows in natural words. - Agreement creates a real appointment. The moment the lead commits to a time, the appointment lands on the calendar, confirmed, with the contact attached. Round-robin calendars distribute it across your team automatically. - It never claims a booking it didn't make. The thread is only marked booked after the calendar confirms the appointment. If the calendar write fails after a lead agreed, the assistant pauses itself and alerts your team to lock it in manually. Without a calendar selected, the assistant works in tag-only mode: it confirms a window in words and tags bot-booked-call so your own workflow does the booking. ## Follow-ups that do not annoy people Automated follow-ups are off by default. An owner must deliberately enable them and choose up to three delays in hours. A reply, opt-out, handoff, or human takeover stops the sequence. Beam never treats an uncertain delivery state as permission to send the same message again. ## Daily team workflow - Work new conversations from Inbox. - If a reply needs judgement, click takeover and reply as a human. The assistant stops on that thread. - If the assistant's behavior needs changing, use Coach your assistant in the conversation or add a House Rule in Assistant. - Review assistant drafts before sending until the workspace owner is comfortable with the results. - Use the assistant only for contacts with appropriate consent and always honor opt-outs. Do not turn on live replies to “see what happens”Use the Playground and draft mode first. If you see a duplicate, a missing message, an unclear delivery result, or a reply that needs a human, pause the assistant and resolve the issue before continuing. ## When it books The appointment is on your calendar, the contact gets tagged bot-booked-call in your CRM with the agreed window in the notes, your team channel gets a notification if alerts are on, and an assistant.booked event fires to your webhooks. The loop from first text to booked call runs without a human touching it, and every message is in the inbox if you want to watch it work. --- # For AI agents (Documentation) > 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. --- # Team & workspaces (Documentation) > Seats with their own logins, thread assignment, team-channel alerts when the assistant books or hands off, and separate workspaces for every client. ## Seats Every teammate gets their own login key (Settings → Team seats). Two roles: - Owner: everything, including Settings, the Assistant, seats, and number management. - Rep: the inbox and numbers view. Reps answer conversations; they can't change workspace configuration. Keys can be rotated or deactivated at any time from Settings. A deactivated seat stops working instantly. ## Thread assignment - Assign any conversation to a seat from the dropdown in the conversation header. - Replying to an unassigned thread claims it for the sender, so ownership is always visible and two reps don't work the same lead. - The inbox filters by All / Mine / Unassigned, and each thread shows its owner's name in the list. ## Team-channel alerts Paste an incoming-webhook URL in Settings → Team notifications and the team channel gets notified the moment: - the assistant books a call (with the agreed time and the assigned rep's name), - the assistant hands off a conversation that needs a human, - a booking write fails after a lead agreed to a time, so someone locks it in manually. For anything richer, subscribe to event webhooks and route them yourself. ## Delivery honesty Beam verifies every outbound message against carrier-side delivery records within minutes. A message that dies shows Not delivered under its bubble instead of silently looking fine. Workspaces can choose (Settings → SMS fallback) whether a dead blue-bubble message is automatically re-sent as a text from the SMS line, or left for a human, keeping the experience blue-bubble-only. ## Workspaces for clients and resellers Each client or reseller runs in its own workspace: separate inbox, numbers, assistant, team, CRM connection, and API key. Nothing crosses between workspaces. Creating a workspace takes one call (or one click for platform operators) and returns the owner's login key and the workspace API key, ready to hand over. Message queues drain per number in parallel, so one busy workspace never slows another. --- # Set up Beam Email (Documentation) > Provision tenant-owned domains and mailboxes without exposing platform provider credentials. ## Who owns what Beam owns and operates the email transport. An agency can manage several client accounts, and each account can have several verified domains and mailboxes. Every domain, mailbox, user, thread, event, and usage entry belongs to exactly one workspace. No client provider accountsClients never bring provider credentials and never see Beam infrastructure, another workspace, or raw provider identifiers. ## Domain onboarding - An agency or platform administrator enters a dedicated sending domain for the client.- Beam returns a branded DNS checklist containing only the records the domain owner must add.- After DNS changes propagate, choose Verify. Beam requests verification and then reads the domain back before it reports Ready. A pending or needs-attention state is not permission to send. Keep the domain paused until sending and, when required, receiving both show ready. ## Mailboxes Create one or more mailbox identities under a verified domain. Each mailbox has a local part, display name, and inbound/outbound controls. Replies remain on the mailbox and RFC thread that received the message. ## Platform sending inventory A platform operator can enable verified, unassigned Beam-owned domains for the platform Inbox composer. Beam performs a fresh provider read-back, creates a neutral hello@domain identity, and keeps any domain already owned by a client workspace unavailable outside that workspace. ## Agency operations Agencies can deliver the DNS checklist in their own brand, monitor verification and delivery health, configure the client's allowance, and enter the client through Beam's audited support-access flow. --- # Email in the managed inbox (Documentation) > Compose, receive, reply, assign, and audit email beside every other Beam channel. ## Compose and reply Choose a verified mailbox, recipients, subject, message, and optional attachments. A new message creates an email thread; a reply preserves its message references and subject history. Save a draft when the message is not ready to send. ## Inbound replies Beam verifies the inbound event before it fetches the message body and attachments. The reply is matched to the owning workspace, mailbox, contact, and thread. If identity is ambiguous, Beam stops instead of guessing. ## One conversation record Email appears beside blue messaging, SMS/MMS, calls, and future channels. Badges identify the channel. Delivery state, attachments, internal notes, assignment, assistant activity, human actions, and provider events appear in the attributable timeline. ## Human takeover Taking over immediately pauses the email assistant for that conversation. The pause survives refreshes and workers. A teammate must deliberately resume it. --- # Email assistant and handoff (Documentation) > Use the existing Beam assistant safely for email drafting, sending, qualification, and booking. ## Safe starting mode Live email sending starts disabled. The assistant may prepare drafts until the workspace owner explicitly enables autonomous sending. Configuration stays per client: knowledge, rules, office hours, qualification questions, calendar actions, and handoff conditions. ## Reply safeguards - One inbound email can create at most one assistant reply.- New inbound activity cancels a stale queued reply.- An uncertain send is never resent automatically.- Human takeover pauses the assistant immediately. ## Bookings The assistant uses the workspace's verified calendar integration. Beam records the real appointment ID returned by the calendar. If the calendar does not confirm the appointment, the assistant must not claim it is booked and should hand the conversation to a person. --- # Delivery, suppression, and troubleshooting (Documentation) > Understand real provider-backed email states and resolve domain or recipient problems safely. ## Delivery states | State | Meaning | | Queued | Accepted by Beam and reserved against the workspace cap. | | Accepted or sent | The transport accepted the outbound attempt. | | Delivered | A provider delivery event was recorded. | | Delayed | Delivery is still being attempted; Beam does not create a second send. | | Bounced, complained, suppressed, or failed | A real terminal provider event was recorded. | | Delivery unknown | The transport result was uncertain. Beam holds for review and never blindly retries. | ## Suppressions Beam blocks a suppressed recipient before sending. Bounce and complaint events update the workspace event ledger and delivery health. Agencies see only their clients; clients see only their workspace. ## Verified does not mean inboxed A verified domain has the required sending authentication, but mailbox providers also score domain history, sending patterns, recipient engagement, content, and complaints. Start a new domain at low, consistent volume, use a recognizable sender identity, send relevant person-to-person content, and increase volume gradually. If a recipient finds a wanted Beam message in spam, they should mark it not spam rather than repeatedly resending it. ## Attachments Outbound email accepts approved file types within the per-file and total limits. Inbound files are fetched only from the approved transport host, stored tenant-scoped, and downloaded through an authorized Beam route. ## Troubleshooting - Check domain sending and receiving health.- Confirm the mailbox is active.- Check plan pause, monthly usage, hard cap, and recipient suppression.- Read the exact timeline event. Do not resend a delivery-unknown message. --- # Email plans, usage, and caps (Documentation) > Understand Beam-managed email entitlements without exposing infrastructure pricing. ## Beam-managed billing Beam owns provider billing. Each workspace has a configurable included monthly outbound allowance, hard cap, optional overage policy, and pause state. Agencies may configure a resale markup within platform policy. Existing SMS and blue-messaging allocations do not change. ## Stripe billing truth A direct client chooses an Email plan in Beam Billing and completes Beam's secure Stripe checkout. The plan does not unlock outbound email merely because a browser returns from checkout: Beam waits for Stripe's signed invoice.paid event, then activates the matching email entitlement. A payment failure, cancellation, or inactive email subscription pauses outbound email only. Inbound mail, the unified inbox, notes, and audit trail remain available; SMS/MMS and blue messaging are not paused or detached by an email payment event. Super Admin publishes immutable Stripe prices from the platform Pricing Manager. Publishing a new price never silently migrates an existing subscriber. Until a plan is deliberately published and checkout is enabled, the client UI makes no charge and shows that activation is unavailable. ## Simple launch plans | Plan | Monthly | Included outbound | Safety cap | Optional overage | | Email Starter | $12 | 2,000 | 2,500 | $4 / 1,000 | | Email Growth | $35 | 10,000 | 12,500 | $4 / 1,000 | | Email Scale | $89 | 30,000 | 40,000 | $3 / 1,000 | Overage is off until deliberately enabled. When it is off, Beam pauses new outbound email at the safety cap while inbound replies and the existing inbox remain available. Allowance does not roll over. ## What consumes allowance One actual transport-accepted outbound email attempt consumes one unit. Beam reserves a unit while the attempt is in flight to prevent concurrent sends from exceeding the cap. Acceptance or an uncertain transport result keeps that unit. Failed reservations, cancellations, retries, duplicate requests, and repeated provider events do not consume another unit. ## Who can change it Super Admin can configure every allowance, cap, overage, provider-cost, markup, base-price, and pause value. Agencies can configure permitted client resale controls. Clients see their plan, usage, cap, overage state, and pause state read-only. Agency-managed client collection is not presumed: Beam records the client commitment, while any Stripe Connect or invoicing workflow must be deliberately enabled and verified for that agency. Cost-covering, not provider resaleThese are Beam-managed service plans. Provider plan names, account limits, credentials, and infrastructure pricing stay platform-side. Super Admin can revise the catalog when real portfolio cost changes without changing email send code. --- # Email API and webhook rules (Documentation) > Technical invariants for tenant-safe sends, raw-body verification, event deduplication, and domain read-back. ## Send rules Every send is authorized against the workspace, domain, mailbox, recipient suppression state, and current entitlement. Callers provide a stable request key. Reusing it returns the existing message and must not create a new send or usage unit. ## Webhook rules Beam verifies the exact raw request body and signature before parsing. Provider event IDs are unique in Beam's ledger, so repeat delivery cannot apply the event twice. Events may arrive late or out of order; terminal state never regresses. ## Domain verification A domain update is a signal to perform a server-side read-back. Only that explicit read-back can move Beam's domain state to verified. The browser never receives provider credentials or raw provider IDs. ## Retention and audit Beam stores the normalized event facts required for delivery health and audit. It does not expose raw provider payloads to clients. Every draft, send, suppression, handoff, calendar action, and provider event remains attributable. --- # Managed email API (API Reference) > Connect a backend, Claude, or another agent to tenant-safe domains, mailboxes, threads, and sends. ## One key, one workspace Send the workspace API key in x-api-key on every /v1/email/* request. The key resolves the workspace on Beam's server. There is no tenant id in the request body and no way to ask for another workspace. Server-side onlyNever put a workspace key in browser JavaScript, a public agent prompt, a client-side Claude artifact, source control, logs, or screenshots. Store it in the calling system's secret manager. ## Available operations | Method | Path | Purpose | | GET | /v1/email/plan | Read plan, usage, cap, and the public catalog. | | GET / POST | /v1/email/domains | List or provision a workspace-owned domain. | | POST | /v1/email/domains/:id/verify | Request verification and perform provider read-back. | | GET / POST | /v1/email/mailboxes | List or create identities on an owned domain. | | GET | /v1/email/threads | List email threads for the workspace. | | GET | /v1/email/threads/:id | Read one owned thread and its timeline. | | POST | /v1/email/messages | Start a one-to-one email thread. | | POST | /v1/email/threads/:id/messages | Reply on an owned thread. | | POST | /v1/email/threads/:id/takeover | Pause or deliberately resume the assistant. | ## Send example curlJavaScriptCopy ``` curl -X POST https://beam.aisync.link/v1/email/messages \ -H "x-api-key: $BEAM_WORKSPACE_KEY" \ -H "content-type: application/json" \ -d '{"domain_id":"12","mailbox_id":"18","to":"lead@example.com","subject":"Following up","text":"Hi Maya — here is the information you asked for.","request_key":"crm-contact-847:follow-up-1"}' ``` ``` const response = await fetch("https://beam.aisync.link/v1/email/messages", { method: "POST", headers: { "x-api-key": process.env.BEAM_WORKSPACE_KEY, "content-type": "application/json" }, body: JSON.stringify({ domain_id: "12", mailbox_id: "18", to: "lead@example.com", subject: "Following up", text: "Hi Maya — here is the information you asked for.", request_key: "crm-contact-847:follow-up-1" }), }); ``` ## Idempotency and delivery truth request_key is required for sends. Reuse the same key for a retry of the same business action; Beam returns the original record and does not consume another allowance unit. A 202 response means queued, not delivered. Use the thread timeline and signed events for final state. Never automatically retry delivery_unknown. ## Claude and agent use Give the agent the LLM documentation corpus and OpenAPI contract, but inject the workspace key only into a protected server tool. Require approval for domain changes and live sends. Human takeover must call the takeover endpoint before the agent stops working the thread. --- # HighLevel and CRM integration (Documentation) > Map each Beam workspace to one HighLevel sub-account without reusing the SMS provider identity. ## Account boundary One Beam client workspace maps to one verified HighLevel location. Agency authorization may select client locations, but Beam exchanges and stores a location-scoped installation for each workspace. A token for one location cannot read, write, or sync another client. ## Separate email provider Email uses its own conversation-provider identity and dedupe keys. It never reuses the existing SMS/blue provider id or guesses a provider from the contact. The email adapter remains behind the platform feature flag until a controlled sub-account proves both directions exactly once. Implementation references: HighLevel conversation providers, signed provider outbound events, and location-scoped OAuth. ## Contact and thread matching - Normalize the email address inside the Beam workspace.- Match the workspace's existing CRM contact id when present.- Otherwise search the connected location by normalized email.- Create an email-only contact only when no unambiguous match exists.- Preserve the RFC email thread separately even when SMS and email belong to the same unified contact timeline. ## Recommended workflow - Connect the client location from Beam Settings.- Verify the returned location matches the intended sub-account.- Enable email activity sync for only that test workspace.- Send one CRM-originated email through Beam with a stable request key.- Reply to it and confirm Beam and HighLevel each show one event on the same contact.- Test a duplicate webhook and a human takeover before enabling the next client. CRM is the synced record, not the transportAll sends still pass through Beam's tenant-owned domain authorization, entitlement cap, suppression checks, outbox, and provider event ledger. --- # Changelog (Documentation) > What is new in Beam. ## September 1, 2026 - Managed email plans. Three clear monthly commitments now show included outbound volume, the safety cap, and optional overage. Agencies can add a transparent markup; clients see their plan and usage read-only. - Email developer API. Workspace-key endpoints now cover owned domains, mailboxes, threads, sends, replies, plan state, and human takeover with durable idempotency. - HighLevel email bridge. A separate, fail-closed email provider path is ready for controlled sub-account testing without changing the existing SMS provider. - Agent-ready documentation. The generated OpenAPI contract and LLM corpus now explain safe email use for backends, Claude, and other agents. ## August 21, 2026 (evening) - Real calendar booking. The assistant reads live availability from your CRM calendar (round-robin included), only offers open times, and creates the confirmed appointment the moment a lead agrees. - Team seats & assignment. Per-teammate logins with roles, thread assignment with claim-on-reply, and All / Mine / Unassigned inbox views. - Team-channel alerts. Instant team notifications on booked calls and human handoffs. - Delivery truth. Every send is verified against carrier-side records; dead messages show "Not delivered" within minutes, with optional automatic SMS fallback (workspace choice). - Workspaces. Spin up isolated client or reseller workspaces in one click, each with its own keys, numbers, team, and assistant. Send queues drain per number in parallel. ## August 21, 2026 - The human touch shipped. Tapback reactions, live typing indicators, and marking inbound messages read for the sender. Beam does not claim recipient-read status for outbound texts. - Attachments. Inbound photos render in the inbox. Outbound attachments via the API on both channels. - Full-screen effects. Send confetti, lasers, balloons and more on blue-bubble messages via the API. - Cancel a queued message before it goes out. - One-click number adding from the Numbers tab. - These docs. Three sections, search, dark mode, copy buttons. ## August 20, 2026 - Beam launched. Smart-channel sending (blue bubble with automatic text handling), the inbox, automatic CRM first touch with tagging, warm-up pacing, reply tracking, and automatic opt-outs. --- # Support (Documentation) > We are here to help. ## Fastest: your support channel Post in your dedicated support channel and a real person answers, usually within the hour during business hours (9am to 6pm Central, Monday through Friday). ## What to include - What you were trying to do - The phone number involved (if it is about a specific conversation) - The message id (if it came from the API) - A screenshot if something looks wrong in the inbox ## Urgent delivery issues If replies suddenly stop across your whole workspace, flag it in the support channel with URGENT in the message. Number reputation issues are time-sensitive and we treat them that way. --- # Introduction (API Reference) > Build on Beam's API. ## Base URL Base URLCopy ``` https://beam.aisync.link ``` ## Authentication Every request carries your workspace key in the x-api-key header. Keep it server-side. Never ship it in a web page or a mobile app. curlCopy ``` curl https://beam.aisync.link/v1/messages/41 \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ## Requests and responses - The API accepts JSON. Set Content-Type: application/json on every POST. - Responses are JSON. Success returns the resource; errors return { "error": "what went wrong" } with a matching HTTP status. - Phone numbers are accepted as US 10-digit, 11-digit, or full international format, and normalized automatically. ## Endpoints | Endpoint | What it does | | POST /v1/messages | Send a message | | GET /v1/messages/:id | Get a message and its status | | DELETE /v1/messages/:id | Cancel a queued message | | GET /v1/messages/list | List recent messages | | GET /v1/conversations/:phone | Full history with a contact | | POST /v1/reactions | React to a contact's message | | POST /v1/typing | Show the typing indicator | | POST /v1/read | Send a read receipt | | GET /v1/contacts/:phone | Contact details and opt-out state | | GET /v1/availability/:phone | Blue-bubble support check | | GET /v1/numbers | The workspace's lines | | POST /t/:workspace/optin | New-lead webhook for CRM workflows | ## Real-time events Beam also pushes signed event webhooks to your endpoint the moment replies, bookings, handoffs, and opt-outs happen. Verify them with webhook signing. ## Be a good citizen Do not poll GET /v1/messages/:id in a tight loop; once every few seconds is plenty. Sends you queue are paced for deliverability, so a burst of API calls never turns into a burst of texts. --- # Send a message (API Reference) > One endpoint sends everything. Beam picks the best channel per contact, paces the send, and delivers. POST https://beam.aisync.link/v1/messages | Field | Type | Description | | to | string, required | The recipient's phone number. | | message | string, required | What to say. Plain text; sent exactly as written. | | first_name | string, optional | Saved to the contact the first time you message them. | | attachments | string[], optional | Public HTTPS file links. Up to 10 on blue bubbles, 3 on texts. See Photos & attachments. | | effect | string, optional | Full-screen effect on blue bubbles: confetti, lasers, balloons, fireworks, celebration, love, slam, loud, gentle, spotlight, echo, invisible_ink, shooting_star. Ignored on texts. | curlJavaScriptPythonCopy ``` curl -X POST https://beam.aisync.link/v1/messages \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "message": "Hey Sarah, you are booked for Tuesday at 2. See you then!", "effect": "confetti" }' ``` ``` 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: "+15551234567", message: "Hey Sarah, you are booked for Tuesday at 2. See you then!", effect: "confetti", }), }); const data = await res.json(); // { id: "41", status: "queued", to: "+15551234567" } ``` ``` import os, requests res = requests.post( "https://beam.aisync.link/v1/messages", headers={"x-api-key": os.environ["BEAM_KEY"]}, json={ "to": "+15551234567", "message": "Hey Sarah, you are booked for Tuesday at 2. See you then!", "effect": "confetti", }, ) print(res.json()) # { "id": "41", "status": "queued", "to": "+15551234567" } ``` ### Response 200 OKCopy ``` { "id": "41", "status": "queued", "to": "+15551234567" } ``` Queued means protected, not slowBeam sends from a live queue that paces every number: warm-up limits, business hours, human-like spacing. Most messages go out within minutes. If the recipient has opted out you get a 403 and nothing sends. ## How the channel is chosen Beam checks whether the recipient supports blue bubbles. If yes, the message goes as iMessage, with automatic text fallback if a blue-bubble delivery fails mid-flight. If not, it goes as a text. Either way it comes from the contact's pinned number, so their whole conversation lives in one thread. --- # Get a message (API Reference) > Fetch a message and its delivery status. GET https://beam.aisync.link/v1/messages/:id curlResponseCopy ``` curl https://beam.aisync.link/v1/messages/41 \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "id": "41", "direction": "outbound", "channel": "imessage", "body": "Hey Sarah, you are booked for Tuesday at 2. See you then!", "status": "sent", "from_number": "+15559876543", "attachments": [], "sent_at": "2026-08-21T15:04:11.000Z", "created_at": "2026-08-21T15:01:02.000Z" } ``` ## Statuses | Status | Meaning | | queued | Accepted, waiting in the pacing queue. | | sent | Handed to the network. channel tells you blue bubble or text. | | delivered | Delivery confirmed against carrier records (texts and blue bubbles). | | failed | The send did not go through. | | cancelled | You cancelled it before it went out. | | no_channel | No active number could reach this contact. | The real success signal is the replyDelivery statuses are useful, but the metric that matters is whether people answer. Watch the reply rate in your inbox header. --- # Cancel a message (API Reference) > Stop a queued message before it goes out. DELETE https://beam.aisync.link/v1/messages/:id curlResponseCopy ``` curl -X DELETE https://beam.aisync.link/v1/messages/41 \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "id": "41", "status": "cancelled" } ``` - A queued message cancels instantly and never sends. - A sent message that is still working its way through the network is cancelled on a best-effort basis. If it already reached the phone, you get a 409. - Cancelling never unsends: once a message is on someone's screen, it is there. --- # React to a message (API Reference) > Land a real tapback on a contact's message. POST https://beam.aisync.link/v1/reactions | Field | Type | Description | | to | string, required | The contact's phone number. | | tapback | string, required | love, like, dislike, laugh, emphasize, or question. | | message | string, required | The exact text of the contact's message you are reacting to. Beam finds their latest message matching it. | | action | string, optional | add (default) or remove. | curlResponseCopy ``` curl -X POST https://beam.aisync.link/v1/reactions \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "tapback": "love", "message": "sounds great, lets do it" }' ``` ``` { "status": "added" } ``` - Works on blue-bubble contacts with an existing conversation. Anything else returns a clear error. - A well-placed ❤️ on "sounds great" keeps a conversation warm without sending another message, and costs the lead nothing to receive. --- # New-lead webhook (API Reference) > The endpoint your CRM workflow calls when a new lead opts in. POST https://beam.aisync.link/t/:workspace/optin?secret=YOUR_WEBHOOK_SECRET This is the automation entry point: one POST per new lead, and Beam handles everything else. It is designed for CRM webhook actions (see the CRM guide) but anything that can POST JSON can call it. | Field | Type | Description | | phone | string, required | The lead's phone number. | | first_name | string, optional | Used to personalize the first-touch template. | | contact_id | string, optional | Your CRM contact id. With it, Beam tags the contact and writes reply notes back to your CRM. | curlResponseCopy ``` curl -X POST "https://beam.aisync.link/t/YOUR_WORKSPACE/optin?secret=YOUR_WEBHOOK_SECRET" \ -H "Content-Type: application/json" \ -d '{ "phone": "+15551234567", "first_name": "Sarah", "contact_id": "abc123" }' ``` ``` { "queued": true, "to": "+15551234567" } ``` ## Behavior - Once per lead. A repeat call for the same phone number returns queued: false and sends nothing. - Personalized. The workspace's first-touch template runs with the lead's first name. - Channel-smart. Blue bubble if the phone supports it, text if not, tagged either way. - Paced. First touches respect warm-up limits and business hours. Opt-in leads onlyThis endpoint is for people who just asked to hear from you. Pointing it at a cold list is the fastest way to lose a number, and consent laws make it your legal problem. See Compliance. --- # Typing & read receipts (API Reference) > Show the real typing indicator and send real read receipts from your own automations. ## Show typing POST https://beam.aisync.link/v1/typing · body: {"to": "+1555...", "action": "start" | "stop"} curlCopy ``` curl -X POST https://beam.aisync.link/v1/typing \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "+15551234567", "action": "start"}' ``` The lead sees live typing bubbles until you send stop or a message. The pattern that feels most human: typing on, wait a few seconds scaled to message length, send. (Beam's inbox and assistant already do this automatically; this endpoint is for your own automations.) ## Send a read receipt POST https://beam.aisync.link/v1/read · body: {"to": "+1555..."} curlResponseCopy ``` curl -X POST https://beam.aisync.link/v1/read \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "+15551234567"}' ``` ``` { "status": "sent" } ``` The lead sees "Read" under their message. Read receipt plus typing plus a reply seconds later is exactly what a fast human looks like. Blue bubble onlyBoth endpoints work on iMessage contacts with an existing conversation. Texting has no typing or read concepts, and Beam returns a clear error rather than pretending. --- # History & listing (API Reference) > Read full conversation history with a contact, or list recent messages across the workspace. ## Conversation history GET https://beam.aisync.link/v1/conversations/:phone · optional ?limit=50 (max 500) curlResponseCopy ``` curl "https://beam.aisync.link/v1/conversations/+15551234567" \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "phone": "+15551234567", "messages": [ { "id": "41", "direction": "outbound", "channel": "imessage", "body": "Hey Sarah...", "status": "sent", "sender": "human", "ts": "2026-08-21T19:16:02.000Z" }, { "id": "42", "direction": "inbound", "body": "first time! kind of nervous lol", "status": "received", "ts": "2026-08-21T19:21:44.000Z" } ] } ``` The sender field tells you who wrote each outbound message: human (inbox or API) or bot (the assistant). Useful for QA and analytics. ## List messages GET https://beam.aisync.link/v1/messages/list · filters: ?to=+1555..., ?status=queued|sent|failed, ?limit=50 (max 200). Newest first. curlCopy ``` curl "https://beam.aisync.link/v1/messages/list?status=queued&limit=20" \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` Prefer webhooks for real-timePolling these endpoints works, but for reacting to new messages as they happen, use event webhooks and keep listing for reconciliation and reporting. --- # Contacts & channel lookup (API Reference) > Look up a contact's details, opt-out state, and whether their phone supports blue bubbles. ## Get a contact GET https://beam.aisync.link/v1/contacts/:phone curlResponseCopy ``` curl "https://beam.aisync.link/v1/contacts/+15551234567" \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "phone": "+15551234567", "first_name": "Sarah", "imessage_available": true, "opted_out": false, "pinned_number": "+15559876543", "created_at": "2026-08-21T19:14:59.000Z" } ``` pinned_number is the line this contact will always hear from. opted_out: true means every send to them returns 403, permanently, unless they text back in. ## Check blue-bubble support GET https://beam.aisync.link/v1/availability/:phone works for any number, even before the first message. curlResponseCopy ``` curl "https://beam.aisync.link/v1/availability/+15551234567" \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "phone": "+15551234567", "imessage": true } ``` Use it to pre-segment a list (blue-bubble leads vs texting leads) before a campaign, or to badge contacts inside your own CRM. null means the check could not complete; try again later rather than assuming. --- # Numbers (API Reference) > List the workspace's dedicated lines and their warm-up state. GET https://beam.aisync.link/v1/numbers curlResponseCopy ``` curl https://beam.aisync.link/v1/numbers \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ``` { "numbers": [ { "e164": "+15559876543", "channels": ["imessage"], "active": true, "daily_cap": 25, "hourly_cap": 12 }, { "e164": "+15551112222", "channels": ["sms", "mms"], "active": true, "daily_cap": 25, "hourly_cap": 12 } ] } ``` daily_cap and hourly_cap are the current warm-up limits on first touches from each line; they grow as the number earns trust. Replies in active conversations are never capped. Adding lines happens in the Numbers tab (see Numbers & warm-up). --- # Event webhooks (API Reference) > Beam pushes signed events to your endpoint the moment things happen: replies, sends, bookings, handoffs, opt-outs. ## Setup Settings → Event webhooks → paste any HTTPS endpoint → Save. Beam generates a signing secret, shown right there. Every event is a POST with a JSON body and a Beam-Signature header. Respond with any 2xx quickly and process async. ## Envelope Every eventCopy ``` { "id": "evt_8c1f2a9d64b34e0f9a12", "type": "message.received", "timestamp": 1787340000, "data": { ... event specific ... } } ``` ## Event catalog | Type | When | data | | message.received | A contact texted you | from, to, body, channel, attachments | | message.sent | Any outbound went out (first touch, inbox, assistant, API) | id, to, from, body, channel, sender | | message.failed | An outbound could not be delivered | id, to, body | | contact.opted_out | A contact texted STOP | phone | | assistant.booked | The assistant booked a call | phone, window, appointment_id, slot | | assistant.handoff | The assistant needs a human | phone, reason | ## Example: reply notifications in your own system Node/Bun receiverCopy ``` Bun.serve({ port: 3000, async fetch(req) { const raw = await req.text(); if (!verifyBeamSignature(raw, req.headers.get("Beam-Signature"), process.env.BEAM_WEBHOOK_SECRET)) { return new Response("bad signature", { status: 401 }); } const event = JSON.parse(raw); if (event.type === "assistant.booked") { // ping the sales floor, update the CRM, fire the AI call... notifyTeamChannel(`🎉 call booked with ${event.data.phone}: ${event.data.window}`); } return new Response("OK"); }, }); ``` Delivery guaranteesEvents are pushed once with a 5 second timeout and no automatic retries in this version. For anything you cannot afford to miss, reconcile with History & listing on a schedule. Signature verification: Webhook signing. --- # Webhook signing (API Reference) > Verify that events really came from Beam using the Beam-Signature header. ## The scheme - Header: Beam-Signature: t=,v1= - Signed payload: t + "." + raw_body (the exact raw bytes, never re-serialized JSON) - Algorithm: HMAC-SHA256 with your signing secret (Settings → Event webhooks) - Reject events older than 5 minutes to block replays, and compare with a constant-time function JavaScriptPythonCopy ``` import crypto from "node:crypto"; function verifyBeamSignature(rawBody, header, secret) { const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header ?? ""); if (!m) return false; const [, t, v1] = m; if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; const expected = crypto.createHmac("sha256", secret) .update(`${t}.${rawBody}`).digest("hex"); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); } ``` ``` import hmac, hashlib, re, time def verify_beam_signature(raw_body: bytes, header: str, secret: str) -> bool: m = re.match(r"t=(\d+),v1=([a-f0-9]+)", header or "") if not m: return False t, v1 = m.group(1), m.group(2) if abs(time.time() - int(t)) > 300: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, v1) ``` Use the raw bodyVerify against the exact bytes you received. Parsing the JSON and re-serializing it will produce different bytes and a failed signature, even for a genuine event. --- # Errors & statuses (API Reference) > Every error is a plain sentence telling you what to fix. ## Error format Example errorCopy ``` { "error": "'to' must be a valid phone number" } ``` ## HTTP status codes | Code | Meaning | | 200 | Success. | | 400 | Something in your request needs fixing. The error says exactly what. | | 401 | Missing or wrong workspace key. | | 403 | The contact opted out. Beam will not message them. | | 404 | That message or contact does not exist in your workspace. | | 409 | The action no longer applies, for example cancelling a message that already delivered. | | 502 | The network rejected the action. Safe to retry once after a short wait. | ## Message statuses queued → sent → delivered (texts), or failed / cancelled / no_channel. Full table in Get a message. --- # Overview (Knowledge Base) > What Beam handles for you, and what stays your responsibility. This is not legal adviceConsult your legal counsel to make sure your communications comply with the laws that apply to you. ## Activation and compliance A workspace can send only after payment is confirmed and a platform administrator assigns an active line. Availability, timing, and area-code preference fulfillment are not guaranteed. Your legal and consent obligations still apply regardless of the channel or line source. What replaces the paperwork is behavior: the systems that watch messaging traffic judge numbers by how they act. Beam's pacing, opt-out handling, and warm-up exist to keep your behavior unmistakably legitimate. Hold up your end by messaging only people who asked to hear from you. ## What Beam handles automatically - Opt-outs. STOP, unsubscribe, quit, cancel, or end from a contact immediately blocks all future sends to them. The API returns 403 if you try. - Pacing and hours. No 3am messages, no machine-gun bursts, no day-one blasts from fresh numbers. - One thread per contact. Consistent sender identity, which both people and filters reward. ## What stays yours - Consent. Laws like the TCPA in the US govern who you may message. Opt-in from your own forms, bookings, and inbound texts is the standard to hold. - Content. What you say and what you sell through the channel. See Prohibited content. - Identity. Say who you are early in a conversation with someone new. ## The practical rule Message people who expect to hear from you, say who you are, honor every opt-out instantly (Beam does), and keep records of how each contact opted in. Do those four things and you are ahead of the vast majority of business texters. --- # Prohibited content (Knowledge Base) > Categories that get filtered or banned no matter how well the message is written. ## Blocked categories Messaging networks filter some subjects aggressively, and no amount of good copy gets around it. Do not run campaigns in these areas on Beam: - High-risk financial offers: payday loans, debt relief and debt collection, cryptocurrency promotions, get-rich-quick schemes - Multi-level marketing recruitment - Gambling and sweepstakes - Cannabis, CBD, vaping, and tobacco - Adult content - Firearms sales - Selling or brokering leads to third parties. The business that earned the opt-in is the business that gets to message. ## Filtered language Even in clean categories, classic promo words trip filters. The pattern to avoid is pressure plus prize: | Filter bait | Human version | | "FREE! Act now! Limited time!" | "Want me to hold a spot for you this week?" | | "You WON a $500 bonus" | Do not. There is no human version of this. | | "CLICK HERE for 50% off" | Ask a question first. Share the offer after they reply. | ## Links - No link shorteners. They are blocked almost everywhere. - Full HTTPS links to your own domain only. - Best of all: no link in the first message. Send it after they reply. Unsure about your campaign?Ask us in your support channel before sending. Two minutes of checking beats a burned number. --- # Best practices (Knowledge Base) > The messages that get replies are the messages that keep numbers healthy. Here is how to write them. ## The golden rule Reply rate is everything. It drives your revenue (replies become calls become sales) and it drives deliverability (networks trust numbers people answer). Every practice below exists to earn a reply. ## Write like one person texting another - Short. Two or three sentences. If it needs a paragraph, it should be a call. - Personal. Their name, and a reference to what they actually did: "saw your request come through a minute ago". - End with an easy question. Something answerable in five words. "What made you start looking?" beats "Would you like to schedule a consultation to discuss our services?" - Sound human. Contractions, casual tone, even the occasional "hmm" or "btw". Polished corporate prose reads as automated. ## Timing - Beam already keeps sends inside business hours. The best window of all is the minutes right after a lead opts in, which is exactly when the CRM webhook fires. - Replies to an active conversation are always fine: answering fast is human. ## The follow-up rhythm No reply does not mean no interest. A gentle bump a day later ("hey, still want me to send that over?") routinely doubles total replies. Two follow-ups over a week is the ceiling: past that you are training the contact to ignore you, and the filters notice too. ## Use the human touch React to their replies with tapbacks, let the typing indicator show while you write, and let read receipts land. See the guide. Conversations that feel human get answered. ## What a healthy conversation looks like ExampleCopy ``` You: Hey Sarah, James here. Saw your request come through a minute ago. What made you start looking into this? Sarah: honestly our current system keeps dropping leads You: ❤️ (reaction on her message) You: yeah that is the exact thing we fix. want me to call you in a few and show you how it works? Sarah: sure ``` Personal, short, question-led, reaction used well, and it ends in a call. That is the pattern. --- # Number health (Knowledge Base) > Trust takes weeks to earn and an hour to lose. How reputation works and how Beam protects yours. ## How a number earns trust Every network scores sending numbers the way email providers score senders. High reply rates, steady volume, and two-way conversation build trust. Volume spikes, identical broadcast copy, and ignored messages destroy it. A flagged number silently stops reaching phones, and there is no appeal hotline. ## What Beam does automatically - Warm-up pacing. New numbers start with a conservative daily cap that grows over weeks of healthy sending. - Business hours. Waking-hours sending only. - Human timing. Sends are spaced irregularly. Perfectly even intervals are a machine fingerprint, so Beam never produces them. - One number per relationship. The first number a contact hears from is theirs forever. - Automatic opt-out. STOP ends messaging to that contact instantly. - Health-graded inventory. Numbers are scored before you ever lease them. ## Reading your signals - Reply rate (inbox header): above 20% on warm leads is healthy. Below 10% means fix the message or the list, not add volume. - Numbers tab: per-line health and current warm-up pace. - Sudden silence: if replies stop across the board, tell us immediately in your support channel. Early is fixable. ## The failure story to avoid It always goes the same way: someone connects a big cold list, blasts identical copy from a fresh number, gets no replies, and the number is dead within days. Every rule on this page is the inverse of that story. The one-sentence versionSend personal messages to people who expect them, let Beam handle the pacing, and your numbers stay healthy for years. --- # Check a list first (Documentation) > Screen any list for blue-bubble reachability before you build a campaign, so you never burn a number messaging phones that cannot receive blue messages. ## Why this exists Before you text a list, you want to know which numbers can actually receive blue-bubble messages. Sending blue messages to phones that cannot receive them wastes attempts, distorts your reply rate, and damages the sending number's reputation. Checking is read-only: nothing is delivered to anyone, and nobody on the list sees anything. Run this before every campaign. It takes seconds and it is the cheapest insurance you have. ## The team workflow Open ScreeningIn Beam, open the Screening tab. Paste the listOne number per line, or paste a CSV export straight from your CRM. Beam finds the phone column, skips the header row, and understands (212) 555-0199, +1 212 555 0199, and 2125550199 equally well. Name it and checkGive it a name you will recognize later, then press check. Progress updates live. Download the blue-bubble listExport just the blue-bubble numbers for your blue campaign, or export everything to split blue and text traffic into separate sequences. ## What the results mean | Result | What it means | What to do | | Blue bubble | This number can receive blue-bubble messages. | Safe for your blue campaign. | | Text only | A real number, but it cannot receive blue messages. | Send as a normal text instead. | | Not a valid number | Not a usable phone number: bad formatting, too few digits, or a stray value from a spreadsheet. | Remove it, or fix the source record. | | Couldn't check | The check could not be completed for that number right now. | Leave it out of the blue campaign, or re-run the list later. Never assume it is text-only. | Why "couldn't check" is its own resultGuessing "text only" when a check does not complete would push a blue-bubble lead onto the text path permanently. Beam reports uncertainty honestly instead of guessing. ## Reading the blue rate The percentage on a finished list is the share of real, reachable numbers that support blue bubbles. Invalid numbers and unchecked numbers are excluded so a messy export does not make a healthy list look bad. A typical consumer list in the United States lands somewhere around half. A very low rate usually means the list skews toward business landlines or was poorly sourced. ## Cleaning a list with an AI assistant Lists rarely arrive clean. If yours has duplicates, mixed formats, or extra columns, paste it into any AI assistant with this instruction, then paste the result into Screening: PromptCopy ``` Here is a contact list. Return ONLY the phone numbers, one per line, with no header, no names, no extra columns, and no commentary. Format every number in E.164 (like +12125550199). Assume US (+1) when no country code is present. Remove duplicates. Skip any row without a usable phone number. ``` Then paste those lines into the Screening tab and check them. You can also send the list straight through the API below if you would rather automate the whole path. ## Limits - Up to 25,000 numbers per check. - Recent results are reused for 24 hours, so re-checking the same list is instant and does not re-run every number. - Checking never sends a message and never notifies the person. --- # Check a list (API Reference) > Screen a list of numbers for blue-bubble reachability before sending to it. Check whether numbers can receive blue-bubble messages, before you message them. This is read-only: nothing is delivered and nobody is notified. See Check a list first for the team workflow. ## Check a list POST https://beam.aisync.link/v1/screen | Field | Type | Notes | | numbers | array of strings | The numbers to check. Either this or list is required. | | list | string | Pasted text or CSV. Beam picks the phone column and skips a header row. | | name | string, optional | A label so you can find this check later. | | wait | boolean, optional | Lists of 25 or fewer return results inline by default. Set false to always get a job id back instead. | curlJavaScriptPythonCopy ``` curl -X POST https://beam.aisync.link/v1/screen \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "October leads", "numbers": ["+12125550199", "(480) 555-0134", "5551234567"] }' ``` ``` const res = await fetch("https://beam.aisync.link/v1/screen", { method: "POST", headers: { "x-api-key": process.env.BEAM_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ name: "October leads", numbers: ["+12125550199", "(480) 555-0134"], }), }); const data = await res.json(); ``` ``` import os, requests res = requests.post( "https://beam.aisync.link/v1/screen", headers={"x-api-key": os.environ["BEAM_API_KEY"]}, json={"name": "October leads", "numbers": ["+12125550199", "(480) 555-0134"]}, ) data = res.json() ``` ### Small list, answered inline ``` { "job_id": "12", "id": "12", "name": "October leads", "status": "done", "total": 3, "checked": 3, "progress": 100, "summary": { "blue": 1, "text_only": 1, "invalid": 1, "unknown": 0 }, "blue_rate": "50.0%", "results": [ { "raw": "+12125550199", "phone": "+12125550199", "result": "blue" }, { "raw": "(480) 555-0134", "phone": "+14805550134", "result": "text_only" }, { "raw": "5551234567", "phone": "+15551234567", "result": "invalid" } ] } ``` ### Larger list, checked in the background ``` { "job_id": "13", "status": "running", "total": 4820 } ``` ## Get results GET https://beam.aisync.link/v1/screen/{job_id} Returns progress and counts. Add ?results=1 for every row, and &only=blue to return just one group (blue, text_only, invalid, unknown). curlCopy ``` curl "https://beam.aisync.link/v1/screen/13?results=1&only=blue" \ -H "x-api-key: YOUR_WORKSPACE_KEY" ``` ## Result values | Value | Meaning | | blue | Can receive blue-bubble messages. | | text_only | A real number that cannot receive blue messages. Send a normal text. | | invalid | Not a usable phone number. | | unknown | The check could not be completed. Do not treat this as text-only; re-check later. | ## Limits - 25,000 numbers per job. - Results are reused for 24 hours, so repeated checks of the same numbers are instant. - blue_rate counts only real, reachable numbers, so invalid rows never drag the number down. --- # How much can I send (Knowledge Base) > Real sending limits per number, why inbound-first has no ramp, and how to size a campaign before you promise a client anything. ## The short answer One warmed number safely handles 50 to 100 new cold contacts per day. Before it is warmed, treat 40 per day as the ceiling. This is a channel limit, not a Beam limit, and no amount of budget removes it. Sizing ruleNew cold contacts per day, divided by 50, equals the minimum number of lines you need. Ten thousand contacts in one week is not a one-number campaign. It is either roughly a hundred lines, or one line and a month of patience. ## Inbound-first has no ramp limit Everything above describes you messaging them first. When the contact texts you first, the ramp does not apply. There is no warm-up ceiling on answering someone who reached out, and a contact who started the conversation cannot report it the way they can report an unsolicited message. This is why the strongest plays put the first message in the lead's hands: a form that opens their Messages app, a QR code, an ad call-to-action, or a missed-call text-back. See Getting leads to text first. ## Reply rate is the health metric Keep replies above roughly 70%. A list that does not reply is a list that is about to cost you a number. A couple of spam reports will undo weeks of ramp, so slow down the moment reply rate slips rather than pushing through it. ## How many numbers a client needs | Lines | New cold contacts per day | | 1 | 50 to 100 | | 3 | 150 to 300 | | 5 | 250 to 500 | For text-message sending specifically, run two or three lines for any meaningful volume and keep one line in reserve. A new sender with an untested list often discovers the hard way that the list is worse than they thought, and a reserve line means that discovery does not take the campaign down with it. ## Before you promise a client a timeline - Ask whether the play is inbound-first or cold outbound. Recommend inbound-first. - If cold, do the sizing math above and put it in writing before signing. - Screen the list so you know the blue-versus-text split. - Request lines with lead time. Provisioning timing and specific area-code availability are confirmed by the operator, not guaranteed. - Start at 40 per day per line and climb only while reply rate holds. --- # Getting your numbers (Documentation) > How numbers are provisioned, how long it takes, how many you need, and how area codes affect response rates. ## How it works Your workspace runs on dedicated business numbers assigned to your account. You do not connect a personal phone or manage hardware. Choose how much customer messaging capacity you need and your preferred area codes. Beam handles the technical line mix so you can reach iPhone and Android customers from one managed inbox. The simple versionYou are buying customer messaging capacity, not separate technologies. Beam uses blue-bubble messaging when supported and standard text everywhere else. Your plan may use more than one assigned number behind the scenes, but your team manages it as one messaging setup. - Open Billing → Customer messaging. A signed-in company or agency owner chooses a published plan by total messaging capacity and adds up to three preferred area codes. Most customers do not need to choose a technical line type. Review the monthly total before opening checkout. Email is purchased separately. - Complete payment once. Beam waits for a verified payment confirmation. Returning from checkout alone does not prove payment. If confirmation is pending, refresh status rather than paying again. - Track Your number requests. The paid request records the workspace, total messaging capacity, and area-code preferences. Payment does not assign a number immediately. - The fulfillment team assigns the right mix. An authorized agency or platform operator confirms payment, sources the required capabilities, and assigns verified available numbers to the correct workspace. Beam rejects unpaid, wrong-workspace, unavailable, and excess assignments. - Verify before going live. Check the assigned numbers in Numbers. Attach the approved receptionist, then run the message and call checks in Launch a client workspace. Agencies can track their own and their direct clients' requests. A client owner signed in normally pays Beam directly for these plans, even when an agency created the workspace. Opening Client view does not authorize a charge: the client must sign in with their own email to purchase. This is not agency Stripe rebilling or automatic resale collection; those require a separately configured and verified collection arrangement. ## Lead time | Request | Typical turnaround | | Standard lines, no area-code preference | Confirmed by the operator after sourcing | | A specific area code | Confirmed after availability is checked | | A larger block for a launch | Give as much notice as you can | Area codes are preferences, not reservations. There is no guaranteed delivery date at checkout. The fulfillment team confirms availability and timing after sourcing; request larger blocks early. ## How many you need Size your plan on daily conversation volume, not total list size. See How much can I send for the arithmetic. If you are unsure, choose the closest published plan and share your expected daily volume; the fulfillment team will translate that into the right technical mix. ## Area codes and customer trust Choose area codes based on where your customers recognize your business. Beam treats them as preferences because inventory changes. The fulfillment team confirms the closest available fit after payment. Technical detail for agencies and operators For text messages, a local number matters. A number from another state texting about a local service reads as spam to a lot of people, and response rates show it. Our client data favors Texas numbers, and matching the recipient's region is worth asking for. For blue-bubble messages, area code matters much less. The first thing the recipient registers is that it is a blue bubble from someone with a contact card, not where the number is from. Set a contact card and the geography question mostly disappears. ## Keeping a line healthy - Respect the daily ceiling while a line is warming. - Watch reply rate; below roughly 70% is a warning, not a rounding error. - Never send the same text to a large batch at once. Vary it. - Keep a spare line available so one degraded number does not stop a campaign. If a line does degrade, we move the conversation to a healthy line and the thread continues. Nothing is lost. --- # Writing messages that land (Knowledge Base) > Formatting and tone rules for messages sent from Beam, including what AI-written text gets wrong. ## Keep formatting minimal Bold, italics, and heavy punctuation are supported but they read badly in a text thread. A message with several bold phrases and underlines looks like a newsletter, not a person. Plain sentences win. If an AI writes your messagesInstruct it explicitly to avoid markdown. A model left to its own devices will produce bold headers and bullet lists inside what is supposed to be a text message, and the recipient can tell instantly. ## Rules worth putting in your assistant's instructions - One or two sentences per message. If it needs a paragraph, it needs a call. - No markdown, no bullet points, no headers. - Contractions always. Lowercase-casual is fine. - One question at a time. - Never send links in a first message. - Vary the wording between recipients. Identical text sent to many people at once is the clearest spam signal there is. ## On deliberate imperfection A little informality reads as human. Overdone, it reads as illiterate, and it is your sales rep's name on the message. If you want an assistant to write loosely, give it specific examples of what that means, rather than a general instruction to make mistakes. A misplaced letter in a long word is human. Mangled basic words are not. ## What good looks like ``` hey, saw you grabbed the guide. what made you start looking into this? yeah we handle the follow-up so leads don't sit. want me to walk you through how it'd work for your setup? monday around 11 or wednesday at noon, which is easier? ``` Short, specific, one question, no formatting, no links. --- # How numbers are assigned (Documentation) > Every lead gets one permanent number while your pool rotates behind the scenes, so volume spreads without a lead ever seeing two numbers. One lead, one number. Your pool does the rest. ## The problem this solves If every lead texts the same number, that number absorbs all the volume and its reputation collapses. But if a lead texts one number and gets a reply from a different one, they see two strangers in their Messages app and stop trusting you. So the rule is simple: each lead is assigned exactly one number, permanently. The rotation happens across leads, never inside a conversation. ## How it runs The lead taps your buttonBefore their Messages app opens, your page asks Beam which number to use. Beam picks the line carrying the fewest conversations, records the pairing, and returns a ready-made link with the first message already written. They send the first textBecause they opened the conversation, there is no warm-up ceiling on your reply, and the thread cannot be reported the way a cold message can. Every reply uses that same numberFollow-ups, the assistant, a rep in the inbox, a reminder weeks later: all of it leaves from the number they already know. ## What each side sees | | The lead | You | | Numbers | Exactly one, forever | Your whole pool | | Threads | One conversation | Every conversation in one inbox | | When you add a line | Nothing changes | New leads start using it | ## Sizing the pool A number is not a bucket you can fill. Each line safely opens a limited number of new conversations per day. | Lines | New cold conversations per day | | 1 | 50 to 100 | | 3 | 150 to 300 | | 5 | 250 to 500 | | 10 or more | 500 to 1,000 | The exception worth building aroundThose limits apply when you message first. When the lead texts you first, the ceiling does not apply at all. That is the difference between needing a hundred numbers and needing three. See The text-us-first funnel. Sizing rule: take the number of new cold conversations you need to start per day, divide by 50, and that is your minimum line count. Leads who come to you barely count against it. ## The rules underneath - Sticky by contact. A phone number is paired to a line the first time we see it, and the pairing is never reshuffled. - Least busy wins. New leads go to the line carrying the fewest conversations, so a burst spreads instead of piling up. - Blue preferred. If the lead can receive blue-bubble messages they get a blue line, otherwise the text line. - Inbound re-pins. If someone texts a different line of yours, that thread moves to the line they actually used. Nobody is answered from a number they did not write to. - A shared reserve, not spares. Keep a small pool in reserve rather than a dedicated backup per client. When a line degrades, a thread moves and the conversation continues. --- # How your assistant writes (Documentation) > The formatting rules every Beam assistant follows, why each one exists, and the research behind them. The difference between a text that gets a reply and one that gets ignored is usually how it is written, not what it says. Every assistant on Beam follows the same set of writing rules. They are on automatically, they are not switchable, and they are tuned for one thing: getting a reply. This page explains each one and the evidence behind it, so you can see why your assistant writes the way it does. Two kinds of rulesThese control how your assistant writes and apply to every business on Beam. Your own house rules control what it says, and you write those yourself. Where the two disagree, formatting wins. ## Never end a text with a period This is the single most effective rule on the list, and the best evidenced. Researchers at Binghamton University showed people short text exchanges where the reply was a word like "Okay", "Sure" or "Yeah". When that reply ended in a period, readers rated it significantly less sincere than the identical word without one. A follow-up study found the same thing and added that it reads as abrupt. The detail that makes this convincing: when the same messages were shown as handwritten notes, the effect vanished. The period is not doing grammar in a text message, it is doing tone, and the tone it conveys is annoyance. ``` Sounds good. <- reads as irritated Sounds good <- reads as friendly ``` Gunraj et al., Texting insincerely: The role of the period in text messaging, Computers in Human Behavior, 2016. Follow-up: Punctuation in text messages may convey abruptness. Period, 2017. ## Spell everything correctly, and never fake a typo A popular piece of advice says to have your AI misspell a word now and then so it seems human. The research says this is a bad trade, and we do not do it. A 2022 study had a hundred people rate short messages for trustworthiness. Spelling errors cost about three points of trust each, and the damage stacked: two errors cost roughly six points, five errors cost thirteen. There was no free allowance where the first mistake was harmless. Your customer is deciding whether your business is competent enough to hand money to. There are better ways to sound human than looking careless, and the rest of this page is those ways. Witchel et al., Spelling Errors in Brief Computer-Mediated Texts Implicitly Lead to Linearly Additive Penalties in Trustworthiness, Frontiers in Psychology, 2022. ## Sentence case, not all-lowercase Writing entirely in lowercase reads as relaxed and friendly between friends, and it is genuinely how a lot of people text. But the same research that documents that habit also documents people switching back to capitals in professional situations. A business texting a customer entirely in lowercase risks reading as careless rather than casual, particularly to older customers. Sentence case with the final period removed is the safe middle: it looks like a person, not like a form letter. ## Keep it short, and vary the length A study of real text messages found an average of about 65 characters, roughly fourteen words, when people had 160 available. Nobody was running out of room. They were choosing to be brief. More useful than the average is the variation. The spread was nearly as large as the average itself, which means real conversations are lumpy: a four-word message next to a longer one, then a fragment. Messages that are all a similar length are one of the clearest signs of automation, which is why your assistant deliberately varies. Thurlow, Generation Txt? The sociolinguistics of young people's text-messaging, 2002, corpus of 544 real messages. ## No emoji unless the customer uses one first A 2026 study found that messages without emoji made the sender appear most competent and professional. Positive emoji helped only alongside neutral or good news, and notably failed at the thing people most often use them for: softening bad news, where they made the sender seem insincere. So your assistant stays clean by default, and never puts an emoji next to a price or a disappointment. If your customer opens with one, it can mirror them. Collabra: Psychology, Emojis at Work: The Effects of Emoji Use on Perceptions of Competence and Appropriateness, 2026. ## No em dashes, semicolons, or bold text None of these appear in normal texting. A semicolon in a text message is the punctuation of a press release, and bold text does not even render in most messaging apps, so it arrives as stray asterisks. The em dash deserves a note because it has become famous as an AI giveaway. The honest version: measurements do show AI using it around three times more often than people, but the human range is wide enough that plenty of real writers use it more. It is a weak signal, not proof. We remove it anyway, because in a sixty-character text it has no job to do and a large share of your customers now read it as machine-written. ## Avoid the words that give AI away Some words have become so associated with AI writing that they now work against you. The clearest case is measured: an analysis of millions of research abstracts found the word "delve" appearing 28 times more often after AI writing tools became common. Your assistant avoids that whole family, including seamless, robust, elevate, leverage, unlock, meticulous, and openers like "I would be happy to", "Certainly", and "Great question". It also avoids lists of three ("faster, easier, and more affordable"), which is a rhythm AI falls into constantly and people rarely use in a text. Kobak et al., Delving into LLM-assisted writing in biomedical publications through excess vocabulary, Science Advances, 2025. ## One exclamation mark at most The same research that found periods read as insincere found the opposite for exclamation marks: a reply with one was rated more sincere. It is a genuine warmth signal, which is exactly why it stops working when overused. One per message, never two, never three. ## What this looks like in practice ``` Before: "Hello! I would be happy to help you with that. Our seamless solution delivers faster, easier, and more affordable results. Let me know if you have any questions!" After: "hey! depends on what you need honestly. most of our clients run between 1-3k a month depending on call volume" "are you handling a lot of inbound leads right now?" ``` Shorter, no sign-off, no em dash, no marketing vocabulary, no closing period, and two messages of different lengths instead of one block. That is the whole difference, and it is applied to every message your assistant sends without you doing anything. ## What you still control These rules govern style. Everything about substance is yours: what you sell, what to mention, what never to bring up, which questions to ask first, what words you use for your own business. See Coaching your assistant for how to set those, and try any change in the test chat before a real customer sees it. --- # The text-us-first funnel (Documentation) > Put a button on your site that opens the visitor's Messages app with their first message already written. The safest and highest converting way to start a text conversation. The best first text is the one they send you. ## Why this beats messaging them first When a lead sends the first message, three things change in your favor at once. No warm-up ceilingCold outbound is capped at roughly 50 to 100 new contacts per number per day. Replying to someone who texted you has no such ceiling. See How much can I send. They cannot report it the same wayA conversation the contact started does not carry the same reporting path as an unsolicited message. Your number stays healthy. Speed to reply collapses to secondsThe conversation is already open when your assistant answers. Lead response research consistently finds that contacting within five minutes rather than thirty makes qualification dramatically more likely (MIT and InsideSales, 15,000+ leads). Your reply lands in seconds. ## What the numbers say The clearest published test of a website text button comes from a pest control company running it for 36 days against an identical page without one: 12.58% of visitors converted with the text widget versus 4.17% without, roughly a threefold increase in leads. Phone call volume stayed flat, which matters more than the headline: the texts were additional leads, not calls in disguise. Note that this is a vendor case study without published significance testing, so treat it as strong directional evidence rather than a guarantee. A number to be skeptical ofYou will see "98% of texts get opened" everywhere in this industry. We could not trace it to any primary study. Texting genuinely outperforms email on attention, but that specific figure is folklore, and we would rather you hear that from us than repeat it to a client who checks. ## Set it up Open the Grow tabBeam shows you a working version of the form, running on your own numbers. Change the button text and what the lead is asking about, and watch it update. Copy the snippetTwo lines of HTML. Paste them into a landing page, a thank-you page, or a popup. The key in that snippet is safe to publish: it can only request a number to text. Let Beam pick the numberEvery visitor is assigned the least busy line in your workspace, so a burst of traffic spreads across your numbers instead of overwhelming one. Someone who texted before always gets the same number back. Turn the assistant onThe whole advantage is speed. An inbound message that waits four hours for a human is worse than no button at all. ## Where to put it, strongest intent first | Placement | Why it works | | Missed call text-back | They already dialed you. Highest intent that exists, and it needs no button at all. | | Your Google business listing | Active local buying intent, already on a phone. | | Mobile ad destination | No landing page to bounce from. The tap goes straight to a conversation. | | Landing page, sticky on mobile | The placement in the test above. Sticky bar, not just a hero button. | | Pricing and service pages | People are mid-decision and full of questions. "Text us your question" fits perfectly. | | Thank-you page | Turns a form fill into a live conversation before they cool off. | | QR on print, signage, vehicles | No keyboard needed. Lower volume, good intent. | ## Button copy Lead with the reply rather than the action. "Text us, we reply in minutes" tells them what they get; "Text us now" only tells them what to do. Only promise a response time you actually keep. - Good: "Text us, we reply in minutes" · "Text us your question" · "Text With Us" - Avoid: "Subscribe via SMS" and "Join our list" read as marketing and invite an instant STOP. "Chat with us" promises web chat and breaks the expectation when Messages opens. Underneath, a small line helps: "Opens your messaging app. No spam, reply STOP anytime." ## Device hints and safe handoff The form asks only for a short service interest, name, and phone. Beam treats the browser signal as a hint, never proof: an iPhone hint selects an active iMessage-capable line for that workspace, an Android hint selects SMS, and desktop or unknown clients stay on the compatible-line fallback. The visitor always sees an explicit SMS alternative. Beam saves the lead first, then confirms the matching workspace CRM contact when that connection is configured. The result says synced, not connected, or unavailable; it never claims a CRM handoff that did not happen. A desktop visitor can use your configured booking link, or a separately configured SMS opt-in path. A service inquiry is not marketing consent, and Beam does not send an outbound message from this embed. ## How many fields to ask for Ideally none. The tap is the conversion, and their phone number arrives with the message anyway, so asking for it first is charging friction for something you are about to get free. Ask the qualifying questions in the conversation, where each answer is easy. Add one field only when leads are expensive and your team's time is the bottleneck. Every extra field costs roughly 4% of completions on average. That said, more fields is not automatically worse: qualifying fields filter out tire kickers, so judge on booked conversations rather than taps. ## The prefilled message Keep it short, first person, and specific: Hi! I'd like info about window replacement. The lead is the sender, so anything that reads like your marketing team wrote it gets deleted before they hit send. Under about 60 characters stays fully visible in their compose box. ## What to measure Taps flatter a dashboard. The number that matters is how many taps became real conversations, because some people see the compose screen and change their mind. Beam counts the conversation side for you: everything that arrives shows up in the inbox. ## What goes wrong - Nothing happens on desktop. Tapping a text link on a laptop often does nothing at all, silently. Beam's widget detects this and shows the number to text instead. - Slow first reply. The entire advantage is speed. Automate it. - Treating an inbound text as marketing permission. It is not. See Consent and opt-outs. - Asking for too much before the tap. - A robotic prefilled message written in your voice instead of theirs. - Promising an instant answer from an assistant that cannot actually answer anything. --- # Consent and opt-outs (Knowledge Base) > What an inbound text does and does not permit, what has to appear near your text button, and how Beam handles opt-outs. Not legal adviceThis page is a practical summary of how Beam behaves and what the rules generally require. Text messaging carries statutory damages per message in the United States, so have your own counsel review your specific setup and language. ## The distinction that matters most When someone texts you first, you may reply about the thing they asked about. That is implied consent, and it is why the text-us-first funnel is both safer and simpler. That permission does not extend to marketing. Someone asking "how much is a new roof?" has not agreed to join a promotional list. Sending them campaign blasts later requires separate, express written consent, captured on its own. This is the single most common and most expensive misunderstanding in text marketing, and it is worth being strict about internally. ## What belongs near your text button - Who you are. - What texting you is for. - "Message and data rates may apply." - "Reply STOP to opt out, HELP for help." - Links to your privacy policy and terms. - Message frequency, if you are signing them up for something recurring rather than a one to one conversation. Beam's widget includes a default consent line. Replace it with wording your counsel approves. ## How Beam handles opt-outs Beam stops messaging a contact the moment they ask, and it does not require them to know a magic word. STOP, UNSUBSCRIBE, QUIT, CANCEL, END, REVOKE, and REMOVE all work, and so does ordinary language like "please stop texting me", "take me off your list", or "don't contact me again". This matters legally: since April 2025, a request to stop has to be honored when it arrives by any reasonable means, not only as an exact keyword. Beam deliberately errs toward opting someone out. Losing one conversation to a false positive is a much better outcome than continuing to message somebody who asked you to stop. An opted-out contact is blocked at the send layer, so nothing further goes out, including assistant replies and scheduled follow-ups. A contact.opted_out event fires to your webhooks so your CRM can record it. ## What Beam does not do for you - It does not write your privacy policy or terms. - It does not capture marketing consent. If you intend to run campaigns, collect that separately and keep the record. - It does not decide whether your list was properly sourced. A purchased list is a purchased list no matter how good the tooling is. ## Keep the record For any consent you rely on, keep the timestamp, what the person saw when they agreed, and the message they sent. Beam stores every inbound message with its timestamp, which is exactly the artifact you want if a complaint ever arrives. That inbound text, sent from their own phone, is a strong record. ## Quiet hours Beam only sends during your workspace's sending window, 9am to 8pm by default, and the assistant answers between 8am and 10pm. Marketing messages generally must respect 8am to 9pm in the recipient's local time. --- # Messaging first (Knowledge Base) > When you message someone before they have messaged you, and how to do it safely. ## When you need it New-lead first touches, appointment reminders, booking confirmations: proactive messages the contact expects even though they have not texted you yet. This is most of what Beam does, and the entire pacing system exists to make it safe. ## Where the risk comes from To the systems watching traffic, a first message to a stranger looks the same whether they opted in on your form or landed on a purchased list. Consent lives in your records, not in the network's view. That is why volume, pacing, and personalization matter so much on first touches: they are how legitimate traffic looks different from spam. ## The safe pattern - Reserve first touches for expected messages. A lead who filled your form two minutes ago expects you. A list from last year does not. - Personalize every one. Name plus context. Identical copy to hundreds of people is the classic spam signature. - Let the warm-up work. Beam caps new-contact volume per number per day and grows it slowly. Want more volume? Add lines, and Beam spreads new contacts across them. - Once they reply, you are in a conversation. Replies are unlimited and unpaced: answering people fast is what humans do. ## A real example, start to finish Sarah fills out a medspa's Facebook lead form at 2:14pm. The CRM workflow fires the new-lead webhook: What the CRM sends BeamCopy ``` POST https://beam.aisync.link/t/YOUR_WORKSPACE/optin?secret=... { "phone": "+15551234567", "first_name": "Sarah", "contact_id": "ghl_abc123" } ``` Beam checks her phone (blue bubble: yes), and at 2:16pm the first touch lands. Here is the whole conversation: The conversationCopy ``` 2:16pm You: Hey Sarah, this is Jamie from Glow Aesthetics. Saw your question about lip filler come through. Have you had it done before or would this be your first time? 2:21pm Sarah: first time! kind of nervous lol 2:21pm You: ❤️ (reaction on her message) 2:22pm You: totally normal, most of our first-timers say the same. honestly the consult is the easy part, no needles, just a conversation. want me to grab you a spot this week? 2:25pm Sarah: sure, what do you have? 2:26pm You: we've got tomorrow at 2 or thursday morning around 10, which works better? 2:27pm Sarah: thursday 10 works 2:27pm You: perfect, you're set for thursday at 10am with Erica. she'll text you a reminder the day before. see you then! ``` Notice what made that work: the first touch referenced what Sarah actually did, asked one easy question, the reaction kept it warm without a wall of text, the call was framed as painless, and the booking was two concrete times, never a link. Contact tagged imessage-sent at 2:16 and bot-booked-call at 2:27, so the CRM handled the calendar and the reminder automatically. ### First-touch templates that work Swap the specifics for your business. Every one references what the lead did, stays under 160 characters, and ends with an easy question: Med spaHome servicesB2B / agencyCopy ``` Hey {first_name}, this is Jamie from Glow Aesthetics. Saw your question about {service} come through. Have you had it done before or would this be your first time? ``` ``` Hey {first_name}, Mike here with Comfort Air. Got your request about the {service}. Quick question so I send the right tech, is this a repair or a replacement? ``` ``` Hey {first_name}, James here from {company}. Saw you grabbed the {lead_magnet}. What's the main thing you're trying to fix right now? ``` ## The payoff A first touch that lands within minutes of an opt-in, personalized, from a healthy number, is the single highest-converting message in the entire funnel. Protecting the number is what keeps that machine running. --- # Getting leads to text first (Knowledge Base) > The safest message is a reply. Engineer your funnel so leads message you first. ## Why inbound-first wins When a lead texts you first, everything changes: replies to them are unlimited, unpaced, and carry essentially zero reputation risk. The conversation starts with their consent baked in, on their initiative, which is the strongest position possible. ## 1. The "Text us" link Every phone understands sms: links. Tapping one opens the lead's messaging app with your number and the message already typed. All they do is hit send: LinkHTML buttonCopy ``` sms:+15559876543?&body=Hey! I want the pricing breakdown ``` ``` 💬 Text us, we answer in minutes ``` Put it on your landing pages, your booking confirmation pages, your email signatures. On mobile traffic this outperforms forms because it is two taps and zero typing. ## 1b. The funnel form that starts the text The strongest version of the "Text us" link: a small form in your funnel collects the lead's name, and one tap opens their messaging app with a personal message already written, from them, with their name in it. They hit send, and the conversation exists, started by the lead. Drop this into any funnel page that accepts custom HTML: Full funnel snippet (copy-paste)Copy ```
``` What lands in your Beam inbox: "Hey, it's Sarah Miller. I'm interested in the AI sales system." Sent by her, from her real number, which means: instant consent trail, unlimited unpaced replies, and the assistant can engage on the spot. The phone field is optional for the text itself (their number arrives with the message automatically) but collecting it also feeds your CRM form tracking if your funnel captures the fields. Make it your ownChange the two variables at the top: your Beam number, and what they're interested in. If your funnel already knows the product from the page they're on, set BEAM_PRODUCT per page ("Botox specials", "the HVAC tune-up", "the webinar replay") and every inbound text tells you exactly which funnel it came from. ## 2. The QR code Encode the same sms: link in a QR code for anything physical: event banners, mailers, business cards, packaging. Scanning opens a ready-to-send text: Data to encodeCopy ``` sms:+15559876543?&body=SAW YOU AT THE EXPO, send me the info ``` Any QR generator works. Make the prefilled body specific to where the code lives ("SAW YOU AT THE EXPO") and you also learn which placement drives the texts. ## 3. The ad with a text call-to-action Instead of driving ad clicks to a form, drive them to a text: "Text PRICING to (555) 987-6543 and get the full breakdown in 2 minutes." The lead's first touch is their own message, your reply rate is near 100% by definition, and you captured a phone number that actually answers texts. ## 4. The voice handoff Your voice receptionist ends every call with "I am texting you the details right now." Beam sends the recap, and the lead's reply opens a two-way thread you can work forever: After-call recap via APICopy ``` curl -X POST https://beam.aisync.link/v1/messages \ -H "x-api-key: YOUR_WORKSPACE_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "message": "Great talking just now! Here is the recap I promised. Any questions, just text me back here." }' ``` ## 5. The missed-call text-back Someone calls, nobody picks up. Your automation fires a Beam message within seconds: "Sorry we missed you! What can I help with? Faster to text anyway." A missed call becomes an open thread instead of a lost lead. Wire it exactly like the new-lead webhook, triggered by your CRM's missed-call event. ## The hybrid most businesses run First touches to fresh opt-in leads (paced, personalized), plus inbound-first everywhere you can engineer it. Over time the inbound share grows, and the number gets healthier as it does, because nothing builds reputation like people texting you first. --- # FAQ (Knowledge Base) > Quick answers to the questions everyone asks. ## General ### Do leads see anything other than my brand? No. They see a normal conversation from your dedicated number. There is no branding, no watermark, and nothing that says a platform is involved. ### Is this a mass-blast tool? No, and that is deliberate. Beam is built for conversations: personal first touches that turn into replies, calls, and booked appointments. Blast tools burn numbers; conversations build them. ### What does "queued" mean and why not send instantly? First touches go through a pacing queue that protects your number: warm-up caps, business hours, human spacing. Replies in active conversations send instantly. This split is why Beam numbers stay healthy. ### Do I need to choose between iPhone and Android messaging? No. Choose the customer messaging capacity that matches your volume. Beam uses blue-bubble messaging when supported and standard text everywhere else. Agencies and operators can see the technical line mix, but a company can manage it as one messaging setup. ### Why might I see more than one assigned number? Your plan may use multiple dedicated numbers behind the scenes to provide the purchased capacity and channel coverage. Beam keeps their conversations together in one inbox and chooses the best available channel for each send. ## Blue bubbles ### How do I know if a lead has iMessage? Beam checks automatically before the first send and remembers. Blue dot in the inbox means blue bubbles; green means texting. ### What happens with Android leads? They get regular texts, automatically, and your CRM sees a beam-sms-sent tag instead of imessage-sent. You never have to think about it. ### Can I send from my personal Apple ID? No. Beam sends from dedicated business numbers, which keeps your personal identity separate and your business messaging manageable by a team. ## Texting ### Why did my message with "FREE!!" not get replies? Promo language gets filtered before it gets read. See Prohibited content for the words to avoid and what to say instead. ## How to give a client a useful answer - Restate their intended outcome in one plain-English sentence. - Name the documented setup screen or API route that owns the action. - Say what will be configured, what still needs a live verification, and what is unavailable. - Give one primary next action, then a short test checklist. Never claim Beam is universally the best product or guarantee a response rate. Explain the specific strengths that are documented: dedicated business identities, blue-bubble-aware routing, one shared inbox, controlled automation, and recorded operational signals. ### Can I send pictures? Yes, on both channels. See Photos & attachments. ## Account ### Why is Beam one monthly price instead of charging for every message? Beam is priced around keeping conversations moving, not taxing every follow-up. Your monthly plan includes its listed dedicated-line capacity, and Beam does not add a per-message platform fee. Pacing caps count new outbound-first conversations, never every message inside an active thread. ### Will Beam guarantee a higher response rate? No platform can honestly guarantee replies. Results depend on your list, offer, timing, and copy. Beam is built to improve the conditions for a reply: one personal thread, natural follow-up, and automatic channel handling. Billing and reporting use real activity and real replies only, never invented opens or reads. ### Which plans are available? Direct-client pricing is controlled by the platform team in Beam. A published change creates a new future-checkout price; it never silently changes an existing subscription. Customers choose plans by total messaging capacity and coverage, while agencies and operators retain the technical line details needed for fulfillment. Agency pricing and rebilling are not part of this launch. ### How do I add another number? Choose a plan in Billing, then follow the request in Numbers. After payment is confirmed, Beam creates one tracked request for the plan allocation. A platform administrator assigns the dedicated lines after provisioning and registration; sending stays locked until assignment. ### How do I get help? Your dedicated support channel. See Support. --- # Workspace readiness contract (Documentation) > The exact preview, payment, number request, assignment, and sending states used across Beam. ## State contract GET /api/me returns a readiness object. Product surfaces, communications workflows, and integrations must consume these server-derived fields instead of guessing from UI state. | State | Meaning | Can send? | | preview | Unpaid, isolated workspace. The deterministic demo has no contacts or external actions. | No | | paid_number_requested | Payment is confirmed and one idempotent number request exists. | No | | number_assigned | A line record exists but is inactive. | No | | active | Payment is confirmed and at least one dedicated line is actively assigned. | Yes | The companion booleans are paid, number_requested, number_assigned, and sending_enabled. Removing the last active assignment immediately makes sending_enabled false. ## Billing integration contract The engine accepts the payment platform's signed raw event at POST /webhooks/billing. A hosted-checkout browser return never proves payment. Only a verified paid-invoice event moves a preview to paid/requested and creates the single tracked allocation request. Events are durably deduplicated. Replaying the same event or receiving another paid invoice for the same allocation still produces one request. A new paid allocation after a portal plan change produces one new adjustment request. The webhook never leases or assigns a line. ## Area-code preferences POST /api/onboarding/preferences accepts { "area_codes": ["713", "469"] }. Send zero to three unique, three-digit codes. They guide sourcing only and are never guaranteed. ## Release verification - Create a preview through the public signup and confirm it has zero contacts, messages, and numbers. - Run every demo branch and confirm no message, contact, number, or capacity row changes. - Replay one signed paid-invoice fixture and confirm exactly one request exists while sending stays locked. - Assign one available platform line as super-admin and confirm sending_enabled: true. - Remove the assignment and confirm all send entry points return 423 sending_locked. --- # Agency rebilling (Documentation) > The protected reseller billing model: client separation, connected payment accounts, pricing floors, and the release checks required before an agency can collect live payments. Launch statusAgency rebilling is a separate payment flow from Beam direct billing. Do not enable it for a client until the agency payment connection, connected-account webhook events, client checkout, and upstream cost protection have each passed a real controlled test. ## The model in one sentence An agency owns the client relationship and can charge its client through its own connected payment account; Beam remains the operating system and does not unlock a client line until the agency's own required upstream payment and line-cost protection are confirmed. ## What the agency controls | Agency controls | Beam protects | | Client workspace creation, its brand, client-facing price, invoice presentation, and access to the client inbox. | Minimum pricing, dedicated-line assignment, sending lock state, audit history, and the ability to pause unsafe activity. | | Whether a client is offered Starter, Team, Scale, or a permitted client-specific price. | Public plans cannot be set below $79/month; an SMS/MMS line cannot be set below $35/month. Existing subscribers never change silently. | | Its own customer payment collection and customer communication. | The agency's wholesale obligation to Beam. A successful client payment does not substitute for the agency's own confirmed coverage. | ## Agency setup flow Connect the agency payment accountThe agency owner completes the provider-hosted connection. Beam stores only the account reference and connection state; it never asks the agency to paste a secret key into the client workspace. Create a client workspaceThe client gets an isolated inbox, numbers, assistant, CRM connection, analytics, users, and API credentials. Agency access is logged and expires. Publish the client priceThe agency chooses a standard plan or an approved client-specific price above the enforced floor. A new future-checkout price is created; it does not rewrite an existing subscription. Send the branded checkoutThe client completes the agency-owned checkout. A browser return is not proof of payment; the signed payment event is. Confirm coverage, then assign the lineBeam verifies the necessary agency and client payment states, creates one tracked provisioning request, and a platform operator assigns the dedicated line. Sending stays locked until assignment. ## Non-negotiable protection rules - No funded payment, no new line. A checkout page, client promise, or successful browser redirect never activates a line. - Payment failure pauses sending first. The client does not keep sending while a failed payment remains unresolved. The documented grace and quarantine process follows. - Never lower the floor to win a deal. A client-specific price may go up but must not go below the established plan and SMS/MMS minimums. - Every impersonation and price action is audited. Agency client view, price publishing, payment state changes, provisioning, assignment, and removal need an actor and timestamp. - Connected payment events are verified. Use the provider's signed Connect webhook, dedupe events, and check live versus test mode before changing state. ## Real launch checklist - Connect a sandbox agency account and verify the server stores only the account reference, not a secret in browser storage or a client workspace. - Create a sandbox client checkout from that account and verify the charge, subscription, and webhook identify the correct agency and client. - Replay the same signed payment event and prove that only one allocation request exists. - Fail a renewal and prove sending locks immediately, then verify the documented recovery and quarantine behavior. - Disconnect the agency payment account and prove new checkout and line assignment fail closed, while the audit record remains. - Repeat the complete flow in controlled live mode with one internal agency client before selling the feature publicly. Do not hand this off as "connected" until every checklist item passes.Direct Beam checkout can be live while agency rebilling is still unavailable. These are different payment surfaces with different webhooks, account boundaries, and liability. --- # Ask the Beam documentation (Documentation) > Use Claude or Codex with Beam's current docs and API contract, so implementation guidance stays grounded instead of sounding plausible. ## Start with your use case Select Ask Claude or Ask Codex and describe your question. First prepare and copy the brief, then use the Open link and paste into a new conversation. The copied text includes the Beam overview, MCP guide and current page. The assistant does not need to fetch the website to read these sources. For deeper questions, download and attach the full documentation and API contract. Downloads are not automatically attached. Public documentation context onlyThe handoff never contains a workspace key, contact, phone number, webhook secret, appointment ID, or client record. It does not grant an assistant access to your Beam account. ## Use this exact request PromptCopy ``` I use Beam for [my business and lead source]. I want to [outcome]. Use the Beam docs as the source of truth. Tell me: 1. The simplest safe setup. 2. Which parts are configured versus still needing live verification. 3. The exact test I should run before using this with real leads. 4. Any data, permission, credential, or compliance risk I need to handle. ``` Replace only the bracketed words. A good assistant will ask one necessary follow-up question rather than make an assumption that changes the outcome. ## Choose the right assistant | Button | Best for | What happens | | Ask Claude | Explaining a workflow, comparing approaches, drafting payloads, or debugging an integration concept. | Opens Claude and copies the documentation prompt. Paste it into the new conversation if a prefilled prompt is unavailable. | | Ask Codex | Implementing or reviewing the integration inside a real repository with tests and local files. | Opens Codex and copies the complete documentation handoff. Paste it into a new task, then select the correct project. | Mobile and restricted sessionsThe Open link uses the assistant's website. Your phone decides whether to open an installed app or the browser. Beam cannot force this. If clipboard access is blocked, select and copy the visible prepared brief manually. This handoff is documentation only, not a connection to your account. ## Questions that get useful answers - “When a lead replies, book a real appointment and send the confirmed appointment ID to my webhook.” - “Show me the smallest server-side integration that sends one message and verifies its recorded delivery state.” - “Audit my webhook handler for signature verification, tenant isolation, retries, and duplicate events.” - “Explain which analytics are available now and which outcomes are explicitly unavailable.” ## Truth rules carried into every prompt The generated prompt tells the assistant to use documented capabilities only, distinguish configured from verified behavior, keep credentials server-side, derive tenant authority on the server, and never invent delivery, read, billing, calendar, or webhook outcomes. --- # Operator, agency, and analytics guide (Documentation) > Workspace switching, audited client view, line assignment, metric definitions, integration health, and launch limitations. ## Workspace roles - Platform operators see all workspaces, readiness, line inventory, provisioning requests, delivery activity, and the operational cycle anchored to the 21st. - Agency owners see their agency plus direct client workspaces. Agency authority comes from the workspace role, never from guessing based on child records. - Client owners manage their inbox, setup, lines, team, assistant, API, and event webhooks. Representatives retain inbox and line visibility without credential controls. ## Platform team sign-in A current platform administrator adds each platform teammate in Settings → Platform admin team. Each person then opens the platform sign-in link and requests their own six-digit email code. Platform access is individual, auditable, and can be deactivated without changing anyone else's session. Do not share a platform key. ## Audited client view Select Open client workspace from the Clients or Platform view. Beam verifies the client belongs to the agency, issues a hashed 30-minute session, and records the actor, source workspace, target, reason, and expiry. A persistent banner identifies client view and provides an immediate exit. Client view includes the full inbox, analytics, and configuration status. Persistent login keys, API keys, signing secrets, lead-webhook secrets, and account-changing controls remain hidden. Exiting ends the session and records the end event. Expired or ended credentials fail closed. ## Line assignment and readiness - A confirmed payment record creates one idempotent provisioning request. It never buys or assigns a line. - A platform operator selects an available inventory line and assigns it to the requested workspace. - The assignment is recorded with actor and request context. A paid self-serve workspace becomes active only when an active assignment exists. - Removing the assignment deactivates the line, clears contact pins, records the removal reason, and locks sends immediately. Area codes are sourcing preferences, not guarantees. Pacing always counts new outbound-first conversations, never messages. ## Analytics definitions | Metric | Exact meaning | | Outbound-first | A contact whose first successfully sent message is outbound, with no earlier inbound message, inside the selected window. | | Inbound-first | A contact whose first recorded inbound message occurs before any successful outbound message. | | Messages sent | Outbound rows recorded as sent or delivered. Attempts also include queued and failed rows. | | Replies | The first inbound response after an outbound-first conversation. Response time uses recorded send and inbound event times. | | Failures | Recorded failed or no-ready-line attempts, grouped into plain-language reasons. | | Opt-outs | Current contact state. Period change is unavailable until a canonical opt-out timestamp exists. | | Booked | A distinct real calendar appointment ID. Duplicate events and tag-only states do not count. | The analytics trend charts plot daily recorded sent, delivered, failed, and inbound activity for the selected window. Funnel stages are operational signals, not a claim that every booking was caused by one particular message. Recipient read status is shown only when a channel supplies a real read event. Beam does not infer an open rate for texts. Rescheduled, cancelled, no-show, and completed outcomes remain unavailable until real calendar outcome updates are synchronized. ## API and event-webhook health Configured means a key or HTTPS endpoint exists. It does not mean healthy. API usage health, event-webhook delivery health, and calendar outcome sync remain labelled unavailable until their attempts and read-backs are persisted. ## Billing, revenue, and profit truth Super Admin shows the stored billing status, sending state, plan, cancellation-at-period-end flag, recovery deadline, and current period end when the accepted Billing contract is integrated. Catalog MRR is calculated from the recorded direct-client plan and recorded number add-ons. It is contracted recurring value, not proof of cash collected. Number add-on MRR is shown separately. Revenue from bundled lines is not split out because the catalog does not assign independent revenue to each bundled line. Profit remains Unavailable until real per-line costs and invoice adjustments are stored. Beam does not manufacture a margin from inventory counts. ## Launch truth - Agency display name and HTTPS logo are available. Custom domains are not active. - Agency pricing and rebilling terms are not published or implemented. - A paid database record is not live billing proof. Production payment events require signed delivery and a successful read-back. - Masked screenshots and live behavior must be captured from the integrated release using safe real data. --- # Terms of Service (Documentation) > The terms that govern use of Beam. Last updated: August 31, 2026 These Terms of Service govern your use of Beam, a messaging operations platform provided by MetaTechAI. By creating an account, connecting an integration, or using Beam, you agree to these terms. ## Your account and your data You are responsible for keeping account credentials confidential and for the activity of people you authorize to use your workspace. You may only upload, connect, or process data that you are permitted to use. If you use Beam for a client, you are responsible for having the authority to act for that client. ## Messaging and calls You must comply with applicable laws, carrier requirements, consent requirements, and the rules of any service you connect to Beam. Do not use Beam to send unlawful, deceptive, abusive, or unwanted communications. You are responsible for your messages, call routing choices, assistant instructions, recipient consent, and opt-out handling. Beam may limit, pause, or disable sending or routing when required for safety, compliance, service integrity, or to prevent misuse. ## Third-party services Some features depend on third-party services that you choose to connect, including messaging, phone, calendar, CRM, payment, or AI services. Your use of those services is governed by their own terms. Beam is not responsible for third-party availability, actions, policies, or changes to their APIs. ## Payments and subscriptions Paid plans, add-ons, and any approved custom pricing are described at checkout or in your account. You authorize the applicable charges for the plan and services you select. Pricing changes apply only as disclosed before the relevant charge. Existing subscriptions are not changed automatically unless you approve a change or the applicable agreement allows it. ## Availability and support Beam is provided on an as-available basis. We work to keep the service reliable, but do not guarantee uninterrupted availability, delivery, a specific business outcome, or that an assistant will be correct in every situation. You should review critical communications, routing, and automation before relying on them. ## Suspension and termination You may stop using Beam at any time. We may suspend or terminate access when necessary to protect users, comply with law, prevent fraud or abuse, or enforce these terms. We will make reasonable efforts to provide notice when practical. ## Changes We may update these terms as Beam evolves. If a change is material, we will provide reasonable notice through Beam, email, or this page. Continued use after the effective date means you accept the updated terms. ## Contact Questions about these terms can be sent to support@aisync.link or 480-486-1869. --- # Privacy Notice (Documentation) > How Beam handles account, workspace, and communication data. Last updated: August 31, 2026 This Privacy Notice explains how MetaTechAI handles information when you use Beam. ## Information Beam processes Beam processes information needed to operate the service. This can include account and workspace details, team-member information, contact records, message and call records, appointment references, integration settings, usage and event logs, and support communications. The exact data depends on the features and services you connect. ## How we use information We use information to provide and secure Beam, operate messaging and routing features you configure, synchronize connected services, provide support, prevent misuse, maintain records, improve reliability, and comply with legal obligations. ## Customer data and connected accounts If you add contacts, conversations, or connect a third-party account, you instruct Beam to process that data for your workspace. You are responsible for giving required notices, obtaining consent, and ensuring you have a lawful basis to use that data. Beam uses connection credentials only to provide the connection you authorize. ## When information is shared We share information with service providers that help operate Beam, such as hosting, communications, payment, analytics, and support providers. We may also disclose information when required by law, to protect rights and safety, or in connection with a corporate transaction. We do not sell personal information. ## Security and retention We use reasonable administrative, technical, and organizational safeguards designed to protect information. No system is completely secure, so you should protect your credentials and notify us promptly of suspected unauthorized access. We retain information for as long as needed to provide Beam, meet legal obligations, resolve disputes, and enforce agreements. ## Your choices You can update account information in Beam and may request access, correction, or deletion of personal information where applicable. Some information must be retained for legal, security, billing, or operational reasons. To make a request, contact us using the details below. ## Children Beam is not intended for children and should not be used to knowingly collect personal information from children. ## Changes and contact We may update this notice as our service or legal requirements change. The current version will be posted here with its effective date. Privacy questions or requests can be sent to support@aisync.link or 480-486-1869. --- # Send from GHL workflows (Documentation) > Trigger Beam texts from a GoHighLevel workflow, test without sending, and avoid duplicate messages. Keep your triggers, delays and conditions in GoHighLevel. Let Beam send the message from your assigned business line. AvailabilityThe Custom Webhook integration is the setup described below. A selectable Marketplace action named Send with Beam still requires publisher configuration and GHL publication; do not assume it is available just because Beam appears in your conversation inbox. Test your own contact before enabling any customer workflow. ## Choose the right action | What you want | Use | | Manually reply inside GHL | Select Beam in the conversation inbox. | | Send your chosen message from a workflow | Custom Webhook to the workflow endpoint below. | | Send Beam's configured first introduction to a new lead | The existing opt-in webhook. It skips already-contacted leads, so it is not a follow-up action. | GHL's regular Send SMS action does not select an additional Beam conversation channel. It continues using your default SMS provider. Do not switch that default just to configure this integration. ## Before you start - Connect the correct GHL location in Beam Settings → CRM inbox messaging.- Have an active assigned Beam line and a test contact in that same GHL location.- In Beam Settings → Developer access, create a workspace-specific token with Send real messages. Also grant Control automation only if you want the workflow to pause the assistant.- Keep the token in the workflow's authorization header. Never include it in screenshots, contact fields, public URLs, or this guide. Tokens expire and can be revoked; update the header when rotating one.- Confirm the contact has consented. Beam also checks GHL DND and local opt-out state. ## Add the workflow step In GHL → Automation → Workflows, open a draft test workflow. Add Custom Webhook and name the step Send with Beam. GHL may charge separately for premium workflow actions. | Setting | Value | | Method | POST | | URL | https://beam.aisync.link/api/crm/workflows/send | | Authorization header | Bearer YOUR_BEAM_WORKSPACE_TOKEN | | Content-Type header | application/json | Use this JSON body. Replace the location ID and sender with your own values; use GHL's contact-value picker for contact ID and first name. The sender must include its country code. ``` { "location_id": "YOUR_GHL_LOCATION_ID", "contact_id": "{{contact.id}}", "workflow_id": "welcome-v1", "from": "+15551234567", "message": "Hi {{contact.first_name}}, thanks for reaching out. How can we help?", "request_key": "{{contact.id}}.welcome-v1.step-1", "consent": true, "assistant_mode": "preserve", "dry_run": true } ``` Recipient safety: Beam retrieves the phone number from this exact GHL contact in the connected location. You do not paste a separate destination number. A conflicting duplicate-contact mapping stops the send for review. ## First validate, then send one test - Keep dry_run: true. Run only your own test contact. Expect status: validated and queued: false. No message is sent and the assistant is not paused.- Change dry_run to false and run that test contact. Expect a Beam message ID and status: queued. This is acceptance, not delivery.- Verify one message arrives on your phone from the selected line. Check Beam's status and the same contact's GHL timeline.- Repeat the exact same request with the same send key. It should return the same message ID with duplicate: true, without another text.- Only then add the step to your real workflow. Keep the workflow draft until your test passes. Never bulk-enroll clients as a test. ## How send keys prevent duplicates The key identifies one intended message, not just one contact. The example sends the welcome step once per contact. A later step needs a different suffix, such as step-2. For recurring reminders, include a stable appointment or business-event ID selected through GHL's value picker, plus the reminder step. Re-enrolling the same event must reuse its key. Do not generate a new timestamp or random key on every retry. If you reuse a key with different text or settings, Beam returns request_key_conflict instead of guessing. Check the existing message before creating a new send. Keys remain scoped to the workspace and workflow identifier. ## iMessage, text and replies Beam chooses iMessage when the recipient is eligible and your selected line supports it; otherwise it uses text when that line can reach the recipient. This action does not force iMessage or guarantee RCS. Sender capability and recipient reachability still matter. Sending hours, line pacing, billing readiness and opt-outs still apply. assistant_mode: preserve leaves your current assistant setting alone. Use pause only when GHL or another agent should own replies; it requires Control automation permission and pauses only this contact. There is no automatic unpause. Stop follow-ups when a contact replies using your tested GHL workflow rules. Do not run two automated responders in the same conversation. Outbound acceptance does not prove inbound replies are working. Validate inbound and CRM sync separately before relying on reply-triggered workflows. ## If a step fails | Error | Next action | | unauthorized / permission_denied | Check token expiry, workspace and send permission. | | crm_contact_not_verified / crm_location_not_connected | Check the location connection and contact ID. | | sender_not_available | Choose an active line assigned to this Beam workspace. | | contact_opted_out | Stop; do not bypass the opt-out. | | duplicate_crm_contact_requires_review | Resolve the duplicate CRM contact identity before retrying. | | rate_limited / request_failed | Wait and retry with the same key. Check Beam before assuming no send occurred. | ## Share and screenshot Pin this guide for your team. Capture the workflow step with the Authorization value hidden, the successful validation response, and the received test message. Do not include customer conversations or tokens in training screenshots. ## Official GHL references - Conversation providers and workflow limitations- Creating a native Marketplace workflow action- Marketplace installation and premium-action requirements