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

# WhatsApp API

> Meta Cloud API endpoints used by Galantis — message sending, template management, media upload, and catalog operations.

Galantis communicates with Meta through the WhatsApp Cloud API (Meta Graph API v23.0). This page documents every endpoint Galantis calls, the operation each performs, and relevant implementation notes.

## What this covers

* All Meta Cloud API endpoints Galantis uses
* Request patterns per endpoint category
* Rate limiting and throughput considerations
* Media upload protocol

## Base URL

All Meta Graph API calls use:

```
https://graph.facebook.com/v23.0/
```

The version segment (`v23.0`) is the Graph API version Galantis targets. Meta increments API versions periodically — Galantis pins to a specific version to ensure consistent behavior across all API calls.

## Message API

**Send a WhatsApp message**

```
POST https://graph.facebook.com/v23.0/{phone_number_id}/messages
```

Used for all outbound message sends — campaigns, automation Action Nodes, and Inbox agent template replies.

The `{phone_number_id}` path parameter identifies which of the workspace's connected phone numbers the message is sent from. For workspaces with multiple phone numbers, each send operation specifies the correct `phone_number_id` for the intended sender.

**Request body structure (template message):**

```json theme={null}
{
  "messaging_product": "whatsapp",
  "to": "{customer_whatsapp_number}",
  "type": "template",
  "template": {
    "name": "{template_name}",
    "language": {
      "code": "{language_code}"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "{variable_value_1}" },
          { "type": "text", "text": "{variable_value_2}" }
        ]
      }
    ]
  }
}
```

Variable values are populated at send time — each `{{N}}` placeholder is resolved to its mapped customer, order, or static value before the request is constructed.

**Request body structure (session message — free-form text):**

```json theme={null}
{
  "messaging_product": "whatsapp",
  "to": "{customer_whatsapp_number}",
  "type": "text",
  "text": {
    "body": "{message_text}"
  }
}
```

Session messages are only sent within an active 24-hour conversation window. See [Compliance — Conversation Window](/whatsapp/compliance/conversation-window).

**Response:** Meta returns a message ID on success. This ID is stored in Galantis and used to match incoming status update webhooks back to the original send.

## Template API

**Create a message template**

```
POST https://graph.facebook.com/v23.0/message_templates
```

Called when a merchant submits a template from **Templates → New Template** in the Galantis dashboard. The full template structure — category, language, header, body, footer, and buttons — is serialized and sent to Meta for review.

**Fetch template list and status**

```
GET https://graph.facebook.com/v23.0/message_templates
```

Called to sync current template approval statuses from Meta into Galantis. Used to reconcile local template records with Meta's current state — particularly useful after a reconnection or during initial setup when template status may have changed while the connection was inactive.

Template status changes in normal operation arrive via the `message_template_status_update` webhook rather than through polling, so this endpoint is used primarily for reconciliation rather than routine status tracking.

**Delete a template**

```
DELETE https://graph.facebook.com/v23.0/message_templates
```

Called when a merchant deletes a template from the Galantis dashboard. Removes the template from Meta's system in addition to the local record.

## Media Upload API

**Upload media (resumable protocol)**

```
POST https://graph.facebook.com/v23.0/{app_id}/uploads
```

Used when a merchant uploads an image, video, or document for use as a template header. Meta's media upload uses a resumable protocol — large files are uploaded in chunks, and the upload can be resumed if interrupted.

The upload process:

1. Galantis initiates the upload session with the file size and MIME type
2. Meta returns an upload session ID
3. Galantis uploads the file data (in chunks for large files)
4. Meta returns a media handle on completion
5. The media handle is stored on the template header component and submitted with the template

Media handles are referenced in template submissions and remain valid as long as the template exists and the WABA connection is active.

**Supported media types for template headers:**

| Header type | Accepted formats | Notes                                |
| ----------- | ---------------- | ------------------------------------ |
| Image       | JPEG, PNG        | Minimum 500×500px for catalog images |
| Video       | MP4              |                                      |
| Document    | PDF              | Standard PDF format                  |

## Catalog API

**Push products to Meta Catalog**

```
POST https://graph.facebook.com/v23.0/{catalog_id}/products
```

Called to push product data from Galantis into the connected Meta Catalog. The `{catalog_id}` path parameter identifies the specific Meta Catalog associated with the workspace.

Product data is sent as a batch — multiple products are pushed in a single request where possible, reducing API call overhead for large catalogs.

The request payload maps Galantis product variant fields to Meta's product schema:

* `title` → product name
* `description` → product description
* `price` → product price (formatted per Meta's currency requirements)
* `availability` → derived from `inventory_quantity`
* `image_link` → product image URL
* Variant options → mapped to Meta's item group and variant structure

After a successful push, the product's sync status in Galantis is updated from `PENDING` to `SYNCED`. On failure, the status moves to `FAILED` with the error response stored for diagnostic review.

## Rate limiting and throughput

**Message API throughput** — WhatsApp enforces per-phone-number message sending limits that scale with the phone number's quality tier and business verification level. Galantis processes recipients in batches that respect these limits. Rate limit errors from the Message API cause the affected batch to be retried.

**Template API rate limits** — Template creation and status fetching are subject to standard Graph API rate limits. These are unlikely to be encountered in normal usage — template operations are infrequent relative to message sends.

**Catalog API rate limits** — Bulk product pushes are subject to Catalog API rate limits. Galantis processes products in batches sized to avoid exceeding these limits.

## Related guides

* [Webhooks Reference](./webhooks-reference) — Meta webhooks that deliver status callbacks for Message API sends
* [Templates](/whatsapp/templates/index) — How template submissions map to Template API calls
* [Catalog — Meta Catalog](/whatsapp/catalog/meta-catalog) — How catalog data is pushed to Meta