Developers / API

Tenant session APIs for the control plane use /v1/emails, /v1/sms, and /v1/whatsapp (WhatsApp Cloud send, list, status, timeline) and /v1/account/whatsapp-cloud-line (tenant Meta phone number id override; session + members:read / members:write). External integrations use scoped API keys against /v1/public/emails, /v1/public/sms, and /v1/public/whatsapp (scopes send:whatsapp / read:whatsapp; see OpenAPI). Customer webhooks deliver email lifecycle events, sms_* and whatsapp_* delivery signals, and sms_opt_out when subscribers add or remove handset opt-outs. Artifacts include OpenAPI, Postman, and webhook verification guidance for implementation-safe adoption.

SMS sends now require a tenant-approved sender ID in request payloads (senderId on POST /v1/sms/send). Tenants submit sender ID requests via POST /v1/sms/sender-id-requests, then platform admins review via POST /v1/sms/sender-id-requests/:requestId/review. Approved values are listed at GET /v1/sms/sender-ids.

For operational listing, GET /v1/sms supports query filters:flow=OTP|STANDARD, status=QUEUED|PROCESSING|SENT|DELIVERED|FAILED, free-text query (recipient/body/external id), plus pagination with page and pageSize (max 100).

• OTP-only first page: GET /v1/sms?flow=OTP&page=1&pageSize=10
• Standard messages with delivery status: GET /v1/sms?flow=STANDARD&status=DELIVERED&page=1&pageSize=50
• Search recipient/body/external id: GET /v1/sms?query=2348067&page=1&pageSize=10

SMS provider webhooks (ingress)

Inbound delivery receipts and status callbacks are configured by your platform operator (exact paths, query tokens, and environment flags). Typical patterns include a signed POST /v1/webhooks/sms/provider for status updates and token-guarded routes for carrier delivery receipts and inbound opt-out handling.

• POST /v1/webhooks/sms/dlr?token=… — Delivery receipt (DLR) JSON callback when enabled by the operator.
• POST /v1/webhooks/sms/provider — Signed provider status updates when enabled.
• POST /v1/webhooks/sms/inbound-opt-out?token=… — Inbound MO (e.g. STOP) mapped to JSON; records a tenant opt-out when enabled and the sender has prior outbound SMS from that organization.

WhatsApp Cloud API (Meta) webhooks

Configure the callback URL on your Meta app to https://<API>/v1/webhooks/whatsapp. Use WHATSAPP_VERIFY_TOKEN for the GET verification handshake and WHATSAPP_APP_SECRET for X-Hub-Signature-256 on POST. Enable with WHATSAPP_CLOUD_API_ENABLED and set access token / phone number id (see .env.example). Default outbound line: platform WHATSAPP_PHONE_NUMBER_ID. Tenants can override in Settings (stored on the organization). Optional WHATSAPP_LINE_MAP maps Meta phone_number_id to organizationId for advanced routing.

WhatsApp Business line (tenant session)

Authenticated workspace members manage the dedicated Meta phone_number_id used for outbound sends when set; otherwise sends use the platform default from env. These routes are not in the public OpenAPI bundle (session JWT or equivalent).

• GET /v1/account/whatsapp-cloud-line — Returns whatsappPhoneNumberId, usesPlatformDefault, and platformLineConfigured. Requires members:read.
• PATCH /v1/account/whatsapp-cloud-line — JSON body with whatsappPhoneNumberId (string | null) and/or whatsappAccessToken (string | null). At least one field required; null clears that value. Token is stored encrypted (same key material as DKIM secret encryption). Requires members:write. Conflict 409 when the phone number id is already bound to another organization (WHATSAPP_PHONE_NUMBER_ID_IN_USE).