Developers
API and webhooks
Beamvia's REST API (/api/v1) lets your own systems send messages, read and update conversations and contacts, and tell Beamvia about events (an order shipped, a payment failed). Webhooks push inbox events to your server as they happen. Every endpoint, with examples in cURL, JavaScript, Python and PHP, is in the API reference.
API keys
- Open Settings › API keys → New key.
- Give it a Name and pick its Scopes (leave out what it should not do).
- Copy the key. It's shown only once; only its hash is stored.
Send it as Authorization: Bearer YOUR_API_KEY. Responses use the envelope { status, message, data }. Each key shows its requests and messages today and when it was last used; Revoke key makes requests with it fail immediately. Needs the api.manage permission and a plan with API access.
| Scope | Allows |
|---|---|
message:send | Send messages |
conversation:read / conversation:write | Read conversations; change status, handler, priority, tags |
contact:read / contact:write | Read contacts; create and update them |
channel:read | List channels |
webhook:manage | Create and delete webhooks |
event:write | Send events |
plugin:read / plugin:write | Call installed plugins' API actions |
Endpoints
Plans set an API request quota per channel type and a daily message quota.
Events
Send an event when something happens in your system. It lands in the contact's latest conversation and Beamvia reacts the way you choose:
| Reaction | Effect |
|---|---|
AI (default) | The AI agent reads the event once and tells the customer what matters (falls back to TEAM when a person handles the conversation) |
TEAM | A private note for your team; nothing is sent |
MESSAGE | Sends your template to the customer right away, no AI cost |
Event data is shown to the AI as external data: HTML stripped, long text cut, instructions inside never followed, and it can never confirm a high-risk action. Send an id to make it idempotent. See Events.
Webhooks
Settings › Webhooks → New webhook: an Endpoint URL (HTTPS) and the Events to deliver.
| Event | When |
|---|---|
MESSAGE_CREATED | A message was received or sent |
MESSAGE_UPDATED | A message status changed (sent, delivered, read, failed), or a customer's file was fetched again with Retry |
CONVERSATION_UPDATED | Status, handler, priority or tags changed |
CONTACT_UPDATED | A contact's profile or identities changed |
- Respond with any 2xx within 10 seconds.
- Signature: each delivery carries
X-Beamvia-TimestampandX-Beamvia-Signature:sha256=+ HMAC-SHA256 oftimestamp.bodywith the webhook's signing secret. Reject old timestamps. - Retries: non-2xx answers and timeouts are retried 5 times with backoff. After 50 failures in a row the webhook is switched off.
Each webhook shows its last delivery and status.
Customer files expire. A received file's link stops working after 7 days at most (404), with no event when it does, so copy what you need. A file that wasn't stored arrives with an empty url and driveId: null. See Channels › Customer files.
API history
Settings › API history lists requests to the API, webhook deliveries, and your Telegram and WhatsApp calls, with their bodies, for 30 days. Use it to debug an integration.
FAQ
Is there a sandbox?
Use a test workspace with a spare number; nothing separates test and live keys.
Can I send to a number that never wrote to me?
The API can send to any WhatsApp number, but cold messages raise the risk that WhatsApp restricts your number. See WhatsApp › Staying safe.
How do I verify a webhook?
Compute HMAC-SHA256 of timestamp.body with the webhook secret and compare it to X-Beamvia-Signature (after sha256=), and reject old timestamps.