Customer API · v1

WhatsApp infrastructure,
without the platform work.

Send messages, manage templates and media, receive signed events, and build customer workflows on one tenant-isolated API.

Send your first message Download the OpenAPI contract

Base URL: https://castapi.dev/api/v1
Format: JSON over HTTPS
Authentication: Bearer API key

Quickstart

Use an organization key from the portal. Keep it on your server and never place it in browser code or logs.

RequestPOST /api/v1/messages

export CASTAPI_BASE_URL="https://castapi.dev"

curl --request POST \
  --url "$CASTAPI_BASE_URL/api/v1/messages" \
  --header "Authorization: Bearer $CASTAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-842-reminder-1" \
  --data '{
    "from": "default",
    "to": "+972501234567",
    "type": "template",
    "template": {
      "name": "appointment_reminder",
      "language": "he"
    },
    "metadata": { "order_id": "842" }
  }'

202 Accepted

The API stores the message before queueing delivery. Track final delivery through signed webhooks or GET /api/v1/messages/{id}.

Conventions

These rules apply across the customer API.

Authentication

Send Authorization: Bearer <key>. Organization keys are tenant-scoped; application keys are accepted only by provisioning operations.

Idempotency

Message, campaign, conversation-reply, and top-up writes require an Idempotency-Key of at most 255 characters. Replays return the original result.

Pagination

Cursor endpoints return data and next_cursor. Pass that opaque value as cursor; do not parse or construct it.

Rate limits

Limits apply per credential. A 429 response includes Retry-After; wait that many seconds before retrying with backoff.

Error envelope

All expected API failures use the same shape. Validation errors may add a safe details field.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": [
      { "path": "to", "message": "E.164 number required" }
    ]
  }
}

Messages, media, and templates

The send endpoint supports text, templates, images, documents, audio, video, interactive content, reactions, and locations.

Phone numbers

Recipient numbers must use E.164 with a leading +. Set from to default when the organization has one active sender, or pass its Meta phone-number id.

Media lifecycle

Upload a file or import an HTTPS URL with POST /api/v1/media, then reference the returned UUID as media_id. Downloads redirect to short-lived signed URLs.

Templates

List, create, inspect, and delete WhatsApp templates through the gateway. Meta remains the authority for approval status and template validation.

Webhooks you can verify

Subscribe to message, template, and billing events. The endpoint secret is shown once when the endpoint is created or rotated.

Each delivery includes X-CastAPI-Signature, X-CastAPI-Timestamp, X-CastAPI-Event-Id, and X-CastAPI-Event-Type.

1Read raw body

Do not parse JSON first.

2Check timestamp

Reject stale requests.

3Verify HMAC

Compare in constant time.

4Dedupe event id

Store before processing.

Signature inputHMAC-SHA256

signed_payload = X-CastAPI-Timestamp + "." + raw_request_body
expected = hex(hmac_sha256(webhook_secret, signed_payload))
received = X-CastAPI-Signature.remove_prefix("v1=")

constant_time_compare(expected, received)

Delivery

A 2xx response confirms receipt. Other responses and network errors are retried with exponential backoff, up to eight attempts over roughly four hours.

Deduplication

Use X-CastAPI-Event-Id as a unique key. Duplicate delivery is normal, so acknowledge events you have already processed.

Event types

message.received, message.status, template.status, and billing.low_balance.

API reference

All 75 customer operations are listed below. Request and response schemas are available in the machine-readable OpenAPI contract.

About `/keys` and `/api-keys`

/api/v1/keys is the canonical paginated list and revoke surface. Create keys with POST /api/v1/api-keys. The older list and revoke operations under /api-keys remain available for compatibility and are marked deprecated in OpenAPI; no existing client is being broken.

Check billing availability before checkout

GET /api/v1/billing/balance returns checkout_enabled. When it is false, top-ups, payment-customer creation, and enabling automatic top-up return 503 billing_checkout_unavailable; messaging and billing reads remain available.

Messages

4 operations

post/api/v1/messagesQueue a message

get/api/v1/messagesList messages

get/api/v1/messages/{id}Get a message

post/api/v1/events/{id}/redeliverRedeliver a stored event

Media

3 operations

post/api/v1/mediaUpload or import media

get/api/v1/mediaList media

get/api/v1/media/{id}Download media

Templates

4 operations

get/api/v1/templatesList message templates

post/api/v1/templatesCreate a message template

get/api/v1/templates/{name}Get a message template

delete/api/v1/templates/{name}Delete a message template

Webhooks

8 operations

post/api/v1/webhooksCreate a webhook endpoint

get/api/v1/webhooksList webhook endpoints

get/api/v1/webhooks/{id}Get a webhook endpoint

patch/api/v1/webhooks/{id}Update a webhook endpoint

delete/api/v1/webhooks/{id}Delete a webhook endpoint

post/api/v1/webhooks/{id}/testSend a test event

get/api/v1/webhooks/{id}/deliveriesList endpoint deliveries

get/api/v1/webhooks/{id}/statsGet endpoint delivery statistics

Channels

5 operations

get/api/v1/channelsList WhatsApp channels

get/api/v1/channels/{waba_id}/phonesList channel phone numbers

post/api/v1/channels/{waba_id}/syncSync a channel from Meta

get/api/v1/embedded-signup/configGet Embedded Signup public configuration

post/api/v1/embedded-signup/exchangeComplete Embedded Signup for the current organization

Contacts

9 operations

get/api/v1/contactsList contacts

post/api/v1/contactsCreate a contact

get/api/v1/contacts/{id}Get a contact

patch/api/v1/contacts/{id}Update a contact

delete/api/v1/contacts/{id}Delete a contact

post/api/v1/contacts/importImport contacts from CSV or XLSX

get/api/v1/suppressionList suppressed recipients

post/api/v1/suppressionSuppress a recipient

delete/api/v1/suppression/{id}Remove a suppression

Audiences

4 operations

get/api/v1/audiencesList audiences

post/api/v1/audiencesCreate an audience

get/api/v1/audiences/{id}Get an audience

delete/api/v1/audiences/{id}Delete an audience

Campaigns

6 operations

get/api/v1/campaignsList campaigns

post/api/v1/campaignsCreate a campaign draft

get/api/v1/campaigns/{id}Get a campaign

post/api/v1/campaigns/{id}/scheduleSchedule a campaign

post/api/v1/campaigns/{id}/cancelCancel a campaign

get/api/v1/campaigns/{id}/exportExport campaign recipients

Conversations

3 operations

get/api/v1/conversationsList conversations

get/api/v1/conversations/{id}Get a conversation and its messages

post/api/v1/conversations/{id}/messagesReply in a conversation

Analytics

2 operations

get/api/v1/overviewGet the workspace overview

get/api/v1/analyticsGet messaging analytics

Billing

10 operations

get/api/v1/billing/balanceGet the prepaid balance

get/api/v1/billing/usageList usage ledger entries

get/api/v1/billing/profileGet the billing profile

put/api/v1/billing/profileReplace the billing profile

put/api/v1/billing/auto-topupConfigure automatic top-ups

post/api/v1/billing/payment-methodStart payment-method configuration

post/api/v1/billing/topupsCreate a balance top-up

get/api/v1/billing/topups/{id}Get a top-up

get/api/v1/billing/documentsList billing documents

get/api/v1/billing/documents/{id}/pdfDownload a billing document PDF

Identity

7 operations

get/api/v1/membersList organization members

post/api/v1/membersInvite an organization member

patch/api/v1/members/{id}Update a member

delete/api/v1/members/{id}Remove a member

get/api/v1/invitationsList pending invitations

post/api/v1/invitationsCreate an invitation

delete/api/v1/invitations/{id}Revoke an invitation

API keys

5 operations

get/api/v1/api-keysList API keys (compatibility shape)compatibility

post/api/v1/api-keysCreate an organization API key

delete/api/v1/api-keys/{id}Revoke an API key (compatibility shape)compatibility

get/api/v1/keysList organization API keys

delete/api/v1/keys/{id}Revoke an organization API key

Provisioning

5 operations

post/api/v1/orgsCreate an organization

post/api/v1/orgs/{id}/keysCreate a key for an organization

get/api/v1/orgs/{id}/webhooksList an organization’s webhooks

post/api/v1/orgs/{id}/webhooksCreate an organization webhook

post/api/v1/orgs/{id}/embedded-signup/exchangeComplete Embedded Signup for an organization

Application provisioning

Partner applications can create isolated customer organizations, mint their first organization key, register webhooks, and complete Embedded Signup.

Application key

Create the tenant boundary

Application-scoped credentials work only on /api/v1/orgs provisioning routes. They do not grant access to an organization’s messages or contacts.

Embedded Signup

Exchange codes server-side

Send the short-lived code, WABA id, and phone-number id to the exchange operation. Never expose Meta access tokens to customer browsers.

Organization key

Hand off least privilege

The full key is returned once. Store it in a server-side secret manager and use it for the tenant’s normal messaging operations.

WhatsApp infrastructure, without the platform work.

Quickstart

Conventions

Authentication

Idempotency

Pagination

Rate limits

Error envelope

Messages, media, and templates

Phone numbers

Media lifecycle

Templates

Webhooks you can verify

Delivery

Deduplication

Event types

API reference

About /keys and /api-keys

Check billing availability before checkout

Messages

Media

Templates

Webhooks

Channels

Contacts

Audiences

Campaigns

Conversations

Analytics

Billing

Identity

API keys

Provisioning

Application provisioning

Create the tenant boundary

Exchange codes server-side

Hand off least privilege

WhatsApp infrastructure,
without the platform work.

About `/keys` and `/api-keys`