# Send a message

Use this endpoint to send a message using a **utility template**.
See [Utility templates](/products/whatsapp/enterprise-documentation/developer-documentation/integration-guide/utility-templates) for details on components, button types, and examples.
Before making requests, ensure you have configured [authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication).

For the full technical reference, see the [OpenAPI specification](/products/whatsapp/openapi/services/sendwhatsappmessage).

#### Endpoint


```
POST /api/services/send
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `Authorization` | Yes | Basic Auth credentials. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `Content-Type` | Yes | Must be `application/json`. |


#### Body parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `to` | string | Yes | Destination phone number in international format (e.g. `+390000000000`) |
| `language` | string | Yes | Template language. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages). Falls back to the template's default language if not found. |
| `templateId` | integer | Yes | The template ID to use |
| `body` | object | Depends on template | Body component with placeholder values. See [Body component](#body-component) below. |
| `urlButtons` | array | Depends on template | URL button overrides. Each entry has `index` (button position, zero-based) and `urlPath` (path appended to the base URL defined in the template). Max 2 buttons. |
| `reference` | object | No | Tracking information: `service` (optional), `action` (optional), `key` (optional) |
| `lra` | string | No | Local Registration Authority (LRA) identifier |
| `businessRelationId` | string | No | One Platform Business Relation ID. If specified, consumption is attributed to this BRI. |


#### Body component

The `body` object is used to fill in the dynamic placeholders defined in the template. Templates are limited to one body component.

Use the `parameters` array to replace placeholders in order. Each entry must have a `text` field with the value to substitute.

**Example**: given a template with the following body text:


```
New login access from {{1}} using the account {{2}}
```

The corresponding `body` object is:


```json
"body": {
  "parameters": [
    { "text": "Rome" },
    { "text": "m.rossi" }
  ]
}
```

The placeholders `{{1}}` and `{{2}}` are replaced in order: `{{1}}` → `Rome`, `{{2}}` → `m.rossi`.

If the template has no placeholders, omit the `body` field entirely.

#### Request example


```json
{
  "to": "+390000000000",
  "language": "en",
  "templateId": 2,
  "body": {
    "parameters": [
      { "text": "Rome" },
      { "text": "m.rossi" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "/activity/m.rossi"
    }
  ],
  "reference": {
    "service": "DIGITALSIGN",
    "action": "AUTH",
    "key": "ext-key-001"
  }
}
```

#### Response examples

**200 — Message sent**


```json
{
  "messageId": "3425151601"
}
```

**400 — Invalid input**


```json
{
  "type": "ConstraintViolationException",
  "code": 3,
  "message": "Parameter 'template' must not be empty and > 0"
}
```

**400 — Wrong number**


```json
{
  "type": "WrongNumberException",
  "code": 8,
  "message": "NO_VALID_RECIPIENT"
}
```

#### Error codes

| HTTP Status | Error code | Error type | Solution |
|  --- | --- | --- | --- |
| `400` | 3 | `ConstraintViolationException` | Check the request parameters against the API documentation |
| `400` | 7 | `InvalidTemplateException` | Verify that the `templateId` exists and is approved |
| `400` | 8 | `WrongNumberException` | Verify the `to` number is in valid international format |


For authentication errors (code 1, 6, 9), see [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication).

#### FAQ

##### What happens if the `language` does not exist for a `templateId`?

Each template has a default language defined in its configuration. If the language specified in the request does not exist for the given `templateId`, the API automatically falls back to the template's default language.