Meta Cloud API Layer — API Reference

The Pilot Status Meta Cloud API Layer is a transparent passthrough to the WhatsApp Cloud API (Graph API). Point your base URL at the layer and keep your existing Graph API requests exactly as they are — Pilot Status swaps your ps_ key for the number’s real Meta system token upstream, so you never handle Meta tokens yourself.

Base URL

https://pilotstatus.com.br/api/layer/meta/

Append any Graph API node exactly as you would on graph.facebook.com/<version>/. The vNN.N version segment is optional — omit it and Pilot uses the configured default (v22.0), or include it (e.g. v22.0/<phone-number-id>/messages) to pin a version.

Authentication

Send your Pilot Status ps_ key using any of the three forms below. Pilot Status swaps it for the number’s real Meta token before forwarding — the ps_ key never reaches Meta:

x-api-key: ps_your_key_here

Authorization: Bearer ps_your_key_here

?access_token=ps_your_key_here

How it works

The Meta layer is passthrough-with-denylist: it forwards messaging, media, template, profile, group, and calling traffic and denies account / business / auth management and number (de)registration. The Graph node id — phone-number id, WABA id, media id, group id, template id — is the first path segment. Pilot Status checks that the phone-number id / WABA id in the path belongs to your API key’s number (403 otherwise).

Single-segment nodes (GET/POST/DELETE /{id}) are resolved by id type — the same shape covers media, group, phone-number, and template ids, exactly as the Graph API does. See each operation’s description in the Playground.

Supported operations

Messages

Method	Path	Description
`POST`	`/{phone-number-id}/messages`	Send any message — `type` selects text / image / audio / video / document / sticker / location / contacts / interactive / template / reaction.
`POST`	`/{phone-number-id}/messages/status`	Read receipt (`status: read`) or typing indicator.

Media

Method	Path	Description
`POST`	`/{phone-number-id}/media`	Upload media (multipart/form-data: `messaging_product`, `type`, `file`).
`POST`	`/{app-id}/uploads`	Create a resumable upload session (`file_length`, `file_type`).
`POST`	`/{upload-id}`	Append the file bytes (raw binary, header `file_offset`).
`GET`	`/{media-id}`	Media URL + metadata — the `url` is rewritten to a signed Pilot download URL.
`DELETE`	`/{media-id}`	Delete an uploaded media asset.

Templates

Method	Path	Description
`GET`	`/{waba-id}/message_templates`	List templates (paging/filter via query).
`POST`	`/{waba-id}/message_templates`	Create a template for approval.
`DELETE`	`/{waba-id}/message_templates`	Delete a template by name (`?name=`).
`GET`	`/{template-id}`	Read a template.
`POST`	`/{template-id}`	Edit an approved template’s `components`.

Phone numbers

Method	Path	Description
`GET`	`/{phone-number-id}`	Number info — display number, quality rating, status.
`GET`	`/{waba-id}/phone_numbers`	List the WABA’s phone numbers.

Business profile

Method	Path	Description
`GET`	`/{phone-number-id}/whatsapp_business_profile`	Read the business profile (`?fields=...`).
`POST`	`/{phone-number-id}/whatsapp_business_profile`	Update business-profile fields.

Groups (OBA)

Method	Path	Description
`POST`	`/{phone-number-id}/groups`	Create a group.
`GET`	`/{phone-number-id}/groups`	List groups.
`GET`	`/{group-id}`	Group info.
`POST`	`/{group-id}/participants`	Add participants.
`DELETE`	`/{group-id}/participants`	Remove participants.
`POST`	`/{group-id}/admins`	Promote to admin.
`DELETE`	`/{group-id}/admins`	Demote admin.
`GET`	`/{group-id}/invites`	Get invite link.
`POST`	`/{group-id}/invites`	Reset invite link.
`DELETE`	`/{group-id}`	Leave / close a group.
`POST`	`/{group-id}/pins`	Pin a group message.

Calls (WhatsApp Business Calling)

Method	Path	Description
`POST`	`/{phone-number-id}/calls`	Call control — `action`: `connect` / `pre_accept` / `accept` / `reject` / `terminate`.
`GET`	`/{phone-number-id}/settings`	Read calling settings.
`POST`	`/{phone-number-id}/settings`	Enable/disable calling, call hours, SIP, voicemail.
`GET`	`/{phone-number-id}/call_permissions`	Check a user’s calling permission (`?user_wa_id=`).

Blocked (denied)

These are not exposed through the layer and return 403 — manage them in the Pilot Status dashboard instead:

Number lifecycle: POST /{phone-number-id}/register, POST /{phone-number-id}/deregister
Auth / management segments anywhere in the path: oauth, debug_token, subscribed_apps, subscriptions, system_users, assigned_users, client_whatsapp_business_accounts, owned_whatsapp_business_accounts
Deleting your own WABA or phone-number id

Sends are recorded in Logs

A message you send with POST /{phone-number-id}/messages through the layer is recorded on the number once Meta accepts it (a 2xx response with a message id). It appears as an outbound row in the dashboard Logs, in GET /v1/messages and in GET /v1/messages/history, with:

origin: "CHATWOOT" when the number is connected to Chatwoot through a native WhatsApp Cloud inbox — every layer send on that number is then attributed to Chatwoot — and origin: "LAYER" on every other number, including one connected to Chatwoot through an API mirror inbox;
a status that follows the statuses Meta reports: SENT, DELIVERED, READ or FAILED;
no correlationId and no send detail: GET /v1/messages/{messageId} answers 404 for these rows.

These sends do not count toward your plan’s message usage. Recording happens after the response and never changes it: what you receive is Meta’s response, unchanged. The row follows the number’s PII retention mode like any other. What is not recorded: read receipts and typing indicators (/messages requests with a status field), reactions, group messages, and requests Meta refuses. What the row shows:

Media sent by Meta media id is re-hosted, so the row shows the media.
Media sent by link is recorded with its type and caption only — Pilot Status does not fetch the URL.
A template reads Template: <name> in content (text on the history endpoint), without its rendered body; template stays null.
A location or contacts message gets a short generated text the same way (Location: …, Contacts: …).

The full field-by-field shape is in Outbound rows with no send request. Only sends made after recording started for your number are listed. Earlier sends are not backfilled.

Example: send a text message

curl -X POST 'https://pilotstatus.com.br/api/layer/meta/<phone-number-id>/messages' \
  -H 'x-api-key: ps_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "5511999999999",
    "type": "text",
    "text": { "preview_url": false, "body": "Hello from Pilot Status 👋" }
  }'

Try it

Every endpoint above is interactive in the Playground → Meta Cloud API — send a request with your ps_ key and see the live Graph API response.

For new integrations, consider the native Pilot Status API — one endpoint sends across Meta and non-official numbers with a simpler body.

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

Meta Cloud API Layer — API Reference

Base URL

Authentication

How it works

Supported operations

Messages

Media

Templates

Phone numbers

Business profile

Groups (OBA)

Calls (WhatsApp Business Calling)

Blocked (denied)

Sends are recorded in Logs

Example: send a text message

Try it

​Base URL

​Authentication

​How it works

​Supported operations

​Messages

​Media

​Templates

​Phone numbers

​Business profile

​Groups (OBA)

​Calls (WhatsApp Business Calling)

​Blocked (denied)

​Sends are recorded in Logs

​Example: send a text message

​Try it

Base URL

Authentication

How it works

Supported operations

Messages

Media

Templates

Phone numbers

Business profile

Groups (OBA)

Calls (WhatsApp Business Calling)

Blocked (denied)

Sends are recorded in Logs

Example: send a text message

Try it