> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business Platform (Meta Cloud API)

> Client-mode REST API connector for a curated WhatsApp Cloud API (Graph v21.0) slice: send text and template messages, phone-number smoke, and WABA message template list

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/overview) on Meta Graph **v21.0**:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST messages (template) | `POST /{phone_number_id}/messages` | `type=template` + body params (alarms) |
| POST messages (text) | `POST /{phone_number_id}/messages` | `type=text` within 24h window |
| GET phone number (smoke) | `GET /{phone_number_id}` | Bearer credential check |
| GET message\_templates | `GET /{whatsapp_business_account_id}/message_templates` | List WABA templates |
| Inbound webhook (secondary) | Meta Cloud API webhooks | Client-mode package; webhook → MQTT out of scope |

Default `BASE_ADDRESS` is `https://graph.facebook.com/v21.0`. Topics use `messaging/whatsapp-business-platform/<object>/<verb>`.

> [!NOTE]
>
> All events send `Authorization: Bearer {access_token}` (system user / permanent token). Prefer Hub secrets (`WHATSAPP_ACCESS_TOKEN` / `WHATSAPP_TOKEN`). Use the WhatsApp **Business phone number ID** in the path — not the customer MSISDN. Graph returns **OAuthException 190** on bad tokens. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — WhatsApp Cloud API Graph v21.0
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://graph.facebook.com/v21.0

DEFINE ROUTE WhatsAppBusinessPlatformRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://graph.facebook.com/v21.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getphonenumber
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/phone/get"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/phone/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.phone_number_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Sendtextmessage
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/message/send-text"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/message/send-text/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.phone_number_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Sendtemplatemessage
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/message/send-template"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/message/send-template/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.phone_number_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listmessagetemplates
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/template/list"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/template/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.whatsapp_business_account_id}/message_templates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Auth and secrets

1. Create a Meta app with WhatsApp product / Cloud API access and a **system user** (or permanent) token with `whatsapp_business_messaging` (and related) permissions.
2. Store the token as Hub secret `WHATSAPP_ACCESS_TOKEN` (alias `WHATSAPP_TOKEN`).
3. Note your WhatsApp Business **phone\_number\_id** and **WABA** id from Meta Business Suite / WhatsApp Manager.
4. Publish MQTT JSON that includes `access_token` (or inject via Hub) plus path ids.

Never commit real tokens. Factory live-test stays **blocked** until a credentialed Graph smoke returns 200.

## Example payloads

**Phone smoke**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID"
}
```

**Text message**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID",
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "text",
  "text": { "body": "Coreflux alarm: Zone A vibration" }
}
```

**Template (alarm params)**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID",
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "coreflux_alarm",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Zone A" },
          { "type": "text", "text": "vibration high" }
        ]
      }
    ]
  }
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy `WhatsAppBusinessPlatformRestApi.lot` only (not `hub-metadata.lot`).
3. Smoke with `GET /{phone_number_id}` → 200 before sending production templates.

## References

* [Cloud API overview](https://developers.facebook.com/docs/whatsapp/cloud-api/overview)
* [Messages reference](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages)
* [Text messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages)
* Meta Postman: WhatsApp Business Platform collection
* Coreflux: [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.