Getting started

Introduction

Current documentation

Build on Beam's API.

Base URL

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.

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.