Beecasts API

The console signs you in with a secure, HTTP-only session cookie. For server-to-server requests, create a key under API Keys and send it as a bearer credential.

curl "$BEECASTS_API/v1/sessions" \
  -H "Authorization: Bearer $BEECASTS_API_KEY"

Keep the full key in a secret manager or environment variable. The full value is shown once when created or rotated; the console cannot reveal it later. Never place it in source control, browser code, URLs, or support screenshots.

1. Open Sessions and choose Add session.
2. Enter a workspace label. Adding the phone number is optional: if you do, only the WhatsApp account with that number can link. Then scan the QR code with WhatsApp on that phone.
3. Keep the phone online while linking completes. If the QR code expires, request a fresh one from the session detail page.

A disconnected device can stop sends and scheduled broadcasts. Reconnect it from the session detail page and review its recent status before retrying messages.

Choose a connected session, enter the recipient’s phone number, and select a message type. You do not need to create a Contact first. The optional contactId links the number to a saved workspace contact for context. The API queues one attempt and returns its message identifier; delivery status updates later from the provider.

curl -X POST "$BEECASTS_API/v1/messages/send" \
  -H "Authorization: Bearer $BEECASTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"ses_…","recipient":"6281234567890","type":"text","body":"Hello"}'

For images, audio, video, and documents, upload the media through the API and pass the returned workspace media URL. A failed delivery still counts as a queued attempt toward the active allowance; inspect its message detail before retrying.

Build a broadcast from saved contacts or direct phone numbers. A saved contact is optional; matching contacts add names and custom fields for personalization.

Select a connected session, review the recipient count and message, then start now or schedule the broadcast. A paused campaign can be resumed, and failed recipients can be reviewed from campaign progress.

You are responsible for following applicable messaging rules and respecting recipient preferences.

Create separate keys for each integration and grant only the resources it needs. Read scopes allow list and detail calls; write scopes allow mutations such as sending, retrying, or managing that resource.

• Use a distinct key per service so access can be revoked without interrupting unrelated integrations.
• Rotate a key after suspected exposure. Rotation revokes the old credential and displays the replacement once.
• Review last-used time, expiry, and scopes on the API Keys page; revoke unused credentials.

Webhook deliveries include X-Beecasts-Event, X-Beecasts-Delivery, and X-Beecasts-Signature. Verify the sha256=… HMAC over the exact raw request body using the endpoint secret before processing an event.

To protect against replayed deliveries, verify X-Beecasts-Signature-V2 instead. It is the HMAC over <X-Beecasts-Timestamp>.<raw body>, where the timestamp is in Unix seconds. Reject deliveries whose timestamp is more than a few minutes old.

Return a successful 2xx response after the event is durably accepted. Failed deliveries are retried with a growing backoff, up to 8 attempts. Use the Webhooks page to inspect attempts and manually retry a failed delivery after fixing the receiver.

Make the receiver idempotent using the delivery ID: a retry can contain the same event more than once.

Open Logs to filter workspace API traffic by route, request ID, status, or key. The detail view includes timing and redacted request metadata to help trace failures.

Use the request ID when coordinating with an operator. Logs do not show full API secrets; avoid copying request payloads that may contain personal data into external tickets.

The Free plan includes 500 messages per calendar month in WIB (UTC+7). Inbound messages, direct outbound messages, and broadcast recipients share this allowance. API request counts are shown separately and do not use message allowance.

Outbound attempts count when accepted into the queue. Failed delivery does not refund an attempt. Inbound messages continue to be recorded after the allowance is exhausted, while new sends, retries, and broadcast recipients pause or fail until the next month or until an active paid plan applies.

Free text messages and media captions include the italic Powered by beecasts.com footer. Images, videos, and documents need a caption on Free; audio-only messages require a paid plan. Billing and Usage show the effective plan and current period totals. Check available capacity before scheduling a large broadcast.

Beecasts is an independent integration platform and is not affiliated with or endorsed by WhatsApp or Meta. WhatsApp and Meta names and marks belong to their respective owners.

Connection and delivery behavior depends on the linked WhatsApp account and may change when the provider changes its service or policies.