> For the complete documentation index, see [llms.txt](https://docs.cartat.net/cartat-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cartat.net/cartat-api/whatsapp-official-api/send-messages.md).

# Send Messages

The primary endpoint for sending WhatsApp messages is:

```http
POST /message/text
Authorization: Bearer <cartat_api_token>
Content-Type: application/json
```

The provider is selected automatically from the instance data. In most cases, you do not need to send `provider` in the request.

### Request examples

{% tabs %}
{% tab title="Meta text" %}
Sends a plain text message through Meta Cloud API when the instance is Meta.

```json
{
  "number": "+966501234567",
  "message": "Hello, your order was received successfully."
}
```

{% endtab %}

{% tab title="Meta template" %}
Sends a pre-approved Meta template.

```json
{
  "number": "+966501234567",
  "template_name": "order_update",
  "parameters": {
    "customer_name": "John",
    "order_id": "ORD-1001"
  }
}
```

{% endtab %}

{% tab title="Template with header" %}
Use this shape when the template has a header parameter:

```json
{
  "number": "+966501234567",
  "template_name": "invoice_ready",
  "header": {
    "type": "document",
    "document": {
      "link": "https://example.com/invoice.pdf",
      "filename": "invoice.pdf"
    }
  },
  "parameters": {
    "customer_name": "John"
  }
}
```

{% endtab %}

{% tab title="Template with button" %}
Use this shape when the template has a URL button or quick reply:

```json
{
  "number": "+966501234567",
  "template_name": "payment_link",
  "parameters": {
    "customer_name": "John"
  },
  "buttons": [
    {
      "url": "https://store.example.com/pay/ORD-1001"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Response

When Meta succeeds, the response follows this general shape:

```json
{
  "status": "success",
  "id": "wamid.xxxxx",
  "from": "1234567890",
  "to": "966501234567",
  "type": "template",
  "provider": "meta",
  "response": {
    "messages": [
      {
        "id": "wamid.xxxxx"
      }
    ]
  }
}
```

{% hint style="success" %}
Meta daily-limit usage is deducted only after a successful Meta response, and after creating `message_log` when possible. No deduction happens while preparing the request or before the provider responds successfully.
{% endhint %}

### Behavior by connection type

| Connection type | Behavior                                                                     |
| --------------- | ---------------------------------------------------------------------------- |
| Meta            | Supports text and template messages through the official connection.         |
| QR              | Supports text messages only in this endpoint and does not support templates. |