Creator OSDocs

API resource

WhatsApp

A WhatsApp Business number messages customers; it is not a posting target. Conversations and replies are in Messages (start one with POST /v1/inbox/conversations and an approved template). These calls cover the number itself: its live status with Meta, the business profile customers see, blocked users, ice breakers, catalogs and incoming media. Meta bills template deliveries to your own WhatsApp Business account.

Connect WhatsApp with Meta credentials

POST/v1/connect/whatsapp

Works on: WhatsApp

For a number already on Meta's Cloud API: connect it with a permanent System User token, no browser. Everyone else uses GET /v1/connect/whatsapp, which returns a link to Meta's signup (add onboarding=api for a number used only through the API, or leave it out to keep the number in the WhatsApp Business app too). Connecting moves the account's message webhooks to Creator OS.

Body

access_tokenstringrequired

Permanent System User token with whatsapp_business_management and whatsapp_business_messaging.

waba_idstringrequired

WhatsApp Business Account id, from WhatsApp Manager.

phone_number_idstringrequired

Phone number id, from WhatsApp Manager.

pinstring

The 6-digit two-step verification PIN, if the number has one.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/connect/whatsapp" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "EAAG...",
    "waba_id": "317766992490131",
    "phone_number_id": "1875844705851813"
  }'
Response 201
{
  "connected": true,
  "id": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
  "phone_number": "+1 310-555-1234",
  "name": "Acme Corp",
  "quality_rating": "GREEN"
}

Register a connected WhatsApp number on the Cloud API

POST/v1/accounts/{accountId}/whatsapp/register

Works on: WhatsApp

Re-runs Meta's Cloud API registration for a WhatsApp account that is already connected. Use it when the number has its own two-step verification PIN: the connect flows register with a default PIN, Meta rejects that with error 133005, and the number then fails every send with the misleading '(#200) You do not have the necessary permission to send messages' while the account still shows as connected. The PIN is used for this call only and is not stored.

Path parameters

accountIdstringrequired

The WhatsApp account ID

Body

pinstring

The 6-digit two-step verification PIN set on the number. Omitting it applies Creator OS's managed default registration PIN, the same one every Embedded Signup connect sets automatically.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W/whatsapp/register" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "string"
  }'
Response 200
{
  "registered": true,
  "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
  "phoneNumberId": "string"
}

Request a Meta re-verification code for a BYO WhatsApp number

POST/v1/accounts/{accountId}/whatsapp/request-code

Works on: WhatsApp

For a bring-your-own WhatsApp number (its own WABA, migrated off another BSP) that Meta demoted to re-verification, this requests a new OTP from Meta. The code lands on the customer's own handset, so verifying it is necessarily self-service; call POST /v1/accounts/{accountId}/whatsapp/verify-code with the code once it arrives. Rate-limited to one request per 10 minutes per account, and Meta enforces its own cooldown on top of that.

Path parameters

accountIdstringrequired

The WhatsApp account ID

Body

methodstring

languagestring

Meta locale code for the verification message, e.g. en_US.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W/whatsapp/request-code" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "SMS"
  }'
Response 200
{
  "requested": true,
  "alreadyActive": true,
  "method": "string",
  "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
  "phoneNumberId": "string"
}

Verify the Meta re-verification code for a BYO WhatsApp number

POST/v1/accounts/{accountId}/whatsapp/verify-code

Works on: WhatsApp

Submits the OTP Meta sent in response to POST /v1/accounts/{accountId}/whatsapp/request-code. This only verifies the number with Meta; it does not register it on the Cloud API. Call POST /v1/accounts/{accountId}/whatsapp/register afterward to complete activation.

Path parameters

accountIdstringrequired

The WhatsApp account ID

Body

codestringrequired

The 6-digit code Meta sent to the phone. Non-digit separators (e.g. "749-456") are stripped automatically.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W/whatsapp/verify-code" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "string"
  }'
Response 200
{
  "verified": true,
  "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
  "phoneNumberId": "string"
}

List account notifications

GET/v1/whatsapp/account-events

Works on: WhatsApp

Returns Meta-originated events recorded for a WhatsApp account, newest first: template review outcomes (approved, rejected, paused, category changes) and WABA status changes (restricted, disabled, reinstated, disconnected). Events are captured from Meta webhooks as they happen; the feed starts at the account's first recorded event and is not backfilled. Complements the push events whatsapp.template.status_updated and account.disconnected with a pollable history.

Query parameters

accountIdstringrequired

WhatsApp account ID

limitinteger

Maximum events to return

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/account-events?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "events": [
    {
      "id": "string",
      "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
      "type": "string",
      "severity": "info",
      "title": "string",
      "detail": "string",
      "createdAt": "2026-10-10T00:00:00.000Z"
    }
  ]
}

Check if a user is blocked

GET/v1/whatsapp/block-users/status

Works on: WhatsApp

Definitive blocked-state lookup for a single contact. Meta exposes no membership endpoint, so this reads Creator OS's blocklist mirror (kept in sync by the block/unblock endpoints; the first call per account backfills the mirror from Meta's full list). Constant-time regardless of blocklist size.

Query parameters

accountIdstringrequired

userstringrequired

Consumer wa_id or E.164 phone (leading + optional)

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/block-users/status?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W&user=%3Cuser%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "blocked": true
}

Unblock users

DELETE/v1/whatsapp/block-users

Works on: WhatsApp

Unblock one or more previously blocked WhatsApp users on this number. Up to 1,000 users per request; per-user failures are reported in failed without failing the rest of the batch.

Body

accountIdstringrequired

WhatsApp account ID

usersstring[]required

Phone numbers (E.164) or WhatsApp user IDs to unblock.

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/whatsapp/block-users" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "users": [
      "string"
    ]
  }'
Response 200
{
  "unblocked": [
    {
      "input": "string",
      "waId": "string"
    }
  ],
  "failed": [
    {
      "input": "string",
      "errors": [
        "string"
      ]
    }
  ]
}

List blocked users

GET/v1/whatsapp/block-users

Works on: WhatsApp

List the WhatsApp users blocked on this number. Cursor-paginated; pass nextCursor back as after to fetch the next page. The blocklist holds up to 64,000 users.

Query parameters

accountIdstringrequired

WhatsApp account ID

limitinteger

Page size.

afterstring

Cursor from a previous response's nextCursor.

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/block-users?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "blockedUsers": [
    {
      "waId": "string"
    }
  ],
  "nextCursor": "string"
}

Block users

POST/v1/whatsapp/block-users

Works on: WhatsApp

Block one or more WhatsApp users on this number. Blocked users cannot message your number or see that you are online, and your sends to them return an error. Meta constraints, surfaced per-user in failed (the request itself still succeeds for the rest of the batch): - Only users who messaged your business within the last 24 hours can be blocked (failures outside the window report "Re-engagement required"). - Up to 1,000 users per request; the blocklist caps at 64,000. - Other WhatsApp Business accounts cannot be blocked.

Body

accountIdstringrequired

WhatsApp account ID

usersstring[]required

Phone numbers (E.164, e.g. "+16505551234") or WhatsApp user IDs to block.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/block-users" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "users": [
      "string"
    ]
  }'
Response 200
{
  "blocked": [
    {
      "input": "string",
      "waId": "string"
    }
  ],
  "failed": [
    {
      "input": "string",
      "errors": [
        "string"
      ]
    }
  ]
}

Get display name status

GET/v1/whatsapp/business-profile/display-name

Works on: WhatsApp

Fetch the current display name and its Meta review status for a WhatsApp Business account. Display name changes require Meta approval and can take 1-3 business days.

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/display-name?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "displayName": {
    "name": "string",
    "status": "APPROVED",
    "phoneNumber": "string"
  }
}

Request display name change

POST/v1/whatsapp/business-profile/display-name

Works on: WhatsApp

Submit a display name change request for the WhatsApp Business account. The new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business). Changes require Meta review and approval, which typically takes 1-3 business days.

Body

accountIdstringrequired

WhatsApp account ID

displayNamestringrequired

New display name (must follow WhatsApp naming guidelines)

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/display-name" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "displayName": "string"
  }'
Response 200
{
  "success": true,
  "message": "string",
  "displayName": {
    "name": "string",
    "status": "PENDING_REVIEW"
  }
}

Get username suggestions

GET/v1/whatsapp/business-profile/username/suggestions

Works on: WhatsApp

Retrieve a list of available WhatsApp Business username suggestions based on the account's business profile name. Use these to help users discover valid, unclaimed usernames.

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/username/suggestions?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "suggestions": [
    "string"
  ]
}

Delete business username

DELETE/v1/whatsapp/business-profile/username

Works on: WhatsApp

Release the currently claimed WhatsApp Business username from the account. After deletion the username becomes available for other accounts to claim.

Body

accountIdstringrequired

WhatsApp account ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/username" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W"
  }'
Response 200
{
  "success": true
}

Get business username

GET/v1/whatsapp/business-profile/username

Works on: WhatsApp

Fetch the current WhatsApp Business username and its approval status. Username status can be approved (active), reserved (pending activation), or none (no username set).

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/username?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "username": "string",
  "status": "approved"
}

Set business username

POST/v1/whatsapp/business-profile/username

Works on: WhatsApp

Claim or transfer a WhatsApp Business username for the account. Username rules: 3-35 characters, letters/digits/period/underscore only, must contain at least one letter, no leading or trailing periods, no consecutive periods, no www prefix, no domain TLD suffix (e.g. .com). If the desired username is currently held by another account, pass transferAction: "force_transfer" to request a transfer.

Body

accountIdstringrequired

WhatsApp account ID

usernamestringrequired

Desired username. Letters, digits, period, and underscore only. Must contain at least one letter. No leading, trailing, or consecutive periods. No www prefix. No domain TLD suffix.

transferActionstring

Pass force_transfer to request a transfer if the username is held by another account

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/username" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "username": "string"
  }'
Response 200
{
  "success": true,
  "username": "string",
  "status": "approved"
}

Get business profile

GET/v1/whatsapp/business-profile

Works on: WhatsApp

Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "businessProfile": {
    "about": "string",
    "address": "string",
    "description": "string",
    "email": "string",
    "profilePictureUrl": "string",
    "websites": [
      "string"
    ],
    "vertical": "string"
  }
}

Update business profile

POST/v1/whatsapp/business-profile

Works on: WhatsApp

Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated. Constraints: about max 139 chars, description max 512 chars, max 2 websites.

Body

accountIdstringrequired

WhatsApp account ID

aboutstring

Short business description (max 139 characters)

addressstring

Business address

descriptionstring

Full business description (max 512 characters)

emailstring

Business email

websitesstring[]

Business websites (max 2)

verticalstring

Business category (e.g., RETAIL, ENTERTAINMENT, etc.)

profilePictureHandlestring

Handle from resumable upload for profile picture

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W"
  }'
Response 200
{
  "success": true,
  "message": "string"
}

Unlink a catalog from a WhatsApp number

DELETE/v1/whatsapp/catalogs

Works on: WhatsApp

Query parameters

accountIdstringrequired

WhatsApp account ID

catalogAccountIdstring

A facebook, instagram or metaads account whose Meta login carries catalog_management; its token performs the call instead of the account's own

catalogIdstringrequired

Meta catalog ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/whatsapp/catalogs?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W&catalogId=%3CcatalogId%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "wabaId": "string",
  "catalogId": "string"
}

List the catalogs linked to a WhatsApp number

GET/v1/whatsapp/catalogs

Works on: WhatsApp

The Meta Commerce catalogs connected to the number's WhatsApp Business Account. Pass catalogAccountId: the WhatsApp connection's own (embedded signup) token answers an empty list even when a catalog is linked, only a Meta login with catalog_management sees the link. A linked catalog is what product, product_list and catalog_message interactive messages sell from (see POST /v1/inbox/conversations/{conversationId}/messages) and what customers browse in the WhatsApp app. Create and fill catalogs with the /v1/ads/catalogs endpoints.

Query parameters

accountIdstringrequired

WhatsApp account ID

catalogAccountIdstring

A facebook, instagram or metaads account whose Meta login carries catalog_management; its token performs the call instead of the account's own

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/catalogs?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "wabaId": "string",
  "catalogs": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Link a catalog to a WhatsApp number

POST/v1/whatsapp/catalogs

Works on: WhatsApp

Connects a Meta Commerce catalog (owned by the same business portfolio as the WhatsApp Business Account) to the number's WABA. The WhatsApp connection's own token cannot do this, so pass catalogAccountId naming a facebook, instagram or metaads account whose Meta login carries catalog_management.

Body

accountIdstringrequired

WhatsApp account ID

catalogAccountIdstring

Account whose Meta login token performs the call

catalogIdstringrequired

Meta catalog ID

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/catalogs" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "catalogId": "string"
  }'
Response 200
{
  "wabaId": "string",
  "catalogs": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Get a number's commerce settings

GET/v1/whatsapp/commerce-settings

Works on: WhatsApp

Whether the linked catalog is shown on the business profile (isCatalogVisible) and whether customers can build a cart (isCartEnabled).

Query parameters

accountIdstringrequired

WhatsApp account ID

catalogAccountIdstring

A facebook, instagram or metaads account whose Meta login carries catalog_management; its token performs the call instead of the account's own

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/commerce-settings?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "settings": {
    "isCartEnabled": true,
    "isCatalogVisible": true
  }
}

Update a number's commerce settings

PUT/v1/whatsapp/commerce-settings

Works on: WhatsApp

Body

accountIdstringrequired

WhatsApp account ID

catalogAccountIdstring

isCartEnabledboolean

isCatalogVisibleboolean

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/whatsapp/commerce-settings" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W"
  }'
Response 200
{
  "settings": {
    "isCartEnabled": true,
    "isCatalogVisible": true
  }
}

Clear ice breakers and commands

DELETE/v1/whatsapp/conversational-automation

Works on: WhatsApp

Remove every prompt and command and turn the welcome message off.

Query parameters

accountIdstringrequired

WhatsApp account ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/whatsapp/conversational-automation?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true
}

Get ice breakers and commands

GET/v1/whatsapp/conversational-automation

Works on: WhatsApp

Read the number's conversational automation (Meta's conversational_automation): ice breaker prompts, slash commands and the welcome-message flag. A number with none set returns the empty configuration.

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/conversational-automation?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": {
    "enable_welcome_message": true,
    "prompts": [
      "string"
    ],
    "commands": [
      {
        "command_name": "string",
        "command_description": "string"
      }
    ]
  }
}

Set ice breakers and commands

POST/v1/whatsapp/conversational-automation

Works on: WhatsApp

Set ice breaker prompts (up to 3, 80 characters each), slash commands (up to 30) and the welcome-message flag on the number. Only the fields you send are changed. A tapped prompt arrives as a normal message.received carrying its text.

Body

accountIdstringrequired

WhatsApp account ID

enable_welcome_messageboolean

When true, Meta sends a request_welcome event the first time a person opens a chat with the number.

promptsstring[]

Ice breakers shown to a person opening a chat. Tapping one sends its text as a normal message.

commandsobject[]

Slash commands shown when a person types /. Names are unique, letters, digits and underscores, without the slash.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/conversational-automation" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W"
  }'
Response 200
{
  "success": true
}

Get number status

GET/v1/whatsapp/number-info

Works on: WhatsApp

Live snapshot of a connected number straight from Meta: the phone-number node (display number, display name + approval, quality rating, messaging-limit tier, throughput, official-business badge, connection status, health_status) and its owning WhatsApp Business Account (name, business verification, timezone, health_status). Fetched live because Meta updates quality/tier/name/health over time; the call also refreshes the cached values shown on the connection card.

Query parameters

accountIdstringrequired

WhatsApp account ID

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/number-info?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "phone": {
    "display_phone_number": "string",
    "verified_name": "string",
    "name_status": "string",
    "quality_rating": "string",
    "messaging_limit_tier": "string",
    "throughput": {
      "level": "string"
    },
    "status": "string",
    "is_official_business_account": true,
    "platform_type": "string",
    "health_status": {}
  },
  "waba": {
    "name": "string",
    "business_verification_status": "string",
    "timezone_id": "string",
    "health_status": {}
  }
}

Get pricing analytics

GET/v1/whatsapp/pricing-analytics

Works on: WhatsApp

Message volume and approximate cost for one connected WhatsApp number, read live from Meta's pricing_analytics on the WhatsApp Business Account and scoped to that account's phone number. Meta's figures are approximate and can lag; Meta bills from its own invoice. Meta limits how far back and how fine the data goes (for example HALF_HOUR only over short ranges) and answers out-of-range requests with an error.

Query parameters

accountIdstringrequired

WhatsApp account ID

startstringrequired

Range start, ISO 8601 date or date-time.

endstringrequired

Range end, ISO 8601 date or date-time. Must be after start.

granularitystringrequired

Size of each data point. Meta refuses MONTHLY when the range is too short for a monthly bucket (for example a range that starts at the beginning of the current month and ends today); that is a 400 with param: granularity and Meta's reason in error. Use DAILY for short or month-to-date ranges. One of: HALF_HOUR, DAILY, MONTHLY.

dimensionsstring

Comma-separated breakdowns: COUNTRY, PHONE, PRICING_CATEGORY, PRICING_TYPE, TIER. Without it each data point is a total for the interval.

metricTypesstring

Comma-separated: COST, VOLUME. Defaults to both.

pricingTypesstring

Comma-separated filter: REGULAR, FREE_CUSTOMER_SERVICE, FREE_ENTRY_POINT.

pricingCategoriesstring

Comma-separated filter of Meta pricing categories, for example MARKETING, MARKETING_LITE, UTILITY, AUTHENTICATION, AUTHENTICATION_INTERNATIONAL, SERVICE, REFERRAL_CONVERSION.

countryCodesstring

Comma-separated ISO 3166-1 alpha-2 country codes to filter on.

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/pricing-analytics?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W&start=%3Cstart%3E&end=%3Cend%3E&granularity=%3Cgranularity%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
  "phoneNumber": "string",
  "granularity": "HALF_HOUR",
  "start": "2026-10-10T00:00:00.000Z",
  "end": "2026-10-10T00:00:00.000Z",
  "dataPoints": [
    {
      "start": "2026-10-10T00:00:00.000Z",
      "end": "2026-10-10T00:00:00.000Z",
      "phoneNumber": "string",
      "country": "string",
      "tier": "string",
      "pricingType": "string",
      "pricingCategory": "string",
      "volume": 0,
      "cost": 0
    }
  ]
}

Download WhatsApp media

GET/v1/whatsapp/media/{mediaId}

Works on: WhatsApp

Streams the binary for a WhatsApp attachment. This is the endpoint the url on a WhatsApp attachments[] entry points at, in both the message.received webhook and the List messages response. This is an authenticated endpoint, not a public link. Send Authorization: Bearer <your API key> exactly as you would for any other call. Passing the URL straight to a browser, an LLM vision API, or a no-code "download file" step without the header returns 401.

Path parameters

mediaIdstringrequired

The media id from attachments[].payload.id.

Query parameters

accountIdstringrequired

The WhatsApp account that received the media.

curl "https://creatoros-production-5658.up.railway.app/v1/whatsapp/media/1029384756102938?accountId=acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "ok": true
}

Upload profile picture

POST/v1/whatsapp/business-profile/photo

Works on: WhatsApp

Upload a new profile picture for the WhatsApp Business Profile. Uses Meta's resumable upload API under the hood: creates an upload session, uploads the image bytes, then updates the business profile with the resulting handle. Provide the image either as a binary upload (multipart/form-data with file) or as a download URL (application/json with url). With a URL we fetch the image server-side and upload the bytes for you. Meta's profile-photo API is bytes-only, so there is no direct URL passthrough. JPEG/PNG, max 5MB either way.

Body

accountIdstringrequired

WhatsApp account ID

urlstringrequired

Publicly reachable https URL of the image (JPEG or PNG, max 5MB, recommended 640x640). Fetched server-side; must resolve directly without redirects.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/whatsapp/business-profile/photo" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Wa2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9W",
    "url": "string"
  }'
Response 200
{
  "success": true,
  "message": "string"
}
PreviousDiscordNextWhatsApp templates and flows