# Send a WhatsApp message

Sends a WhatsApp message to the specified recipient using a pre-approved utility template. Supports body parameters, URL buttons, and an optional reference for tracking. See [Send a message](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/api-references/send-message-apis/send) for details.

Endpoint: POST /api/services/send
Version: 2.1.0.0
Security: basicAuth, ApiKeyAuth

## Security:

  - `basicAuth` (unknown)
    http basic

  - `ApiKeyAuth` (unknown)
    apiKey in header X-Api-Key

## Request body:

  - `application/json` (unknown)
    WhatsApp message request

## Request fields (application/json):

  - `to` (string, required)
    Recipient phone number in E.164 format (e.g. `+390000000000`).
    Example: +390000000000

  - `language` (string, required)
    Language code of the template to use (e.g. `it`, `en`). 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.
    Example: it

  - `templateId` (integer, required)
    Identifier of the WhatsApp template to use.
    Example: 3

  - `businessRelationId` (string | null)
    Optional business relation identifier for internal tracking.

  - `lra` (string | null)
    Local Registration Authority (LRA) identifier.

  - `reference` (object)
    Optional reference object for tracking. See [Reference Attribute](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference) for details.

  - `reference.service` (string | null)
    Identifies the product or service sending the message. Required if `action` or `key` are specified.

  - `reference.action` (string | null)
    Describes the specific action for the selected service (e.g. `2FA`, `AUTH`).

  - `reference.key` (string | null)
    Custom tracking key for internal processes.

  - `body` (object)
    Template body component with dynamic parameters. See [Body component](https://docs.namirial.app/products/whatsapp/enterprise-documentation/developer-documentation/api-references/send-message-apis#body-component) for details on how to use placeholders.

  - `body.text` (string | null)
    Static body text.

  - `body.parameters` (array | null)
    List of dynamic text parameters to substitute in the template body.

  - `body.parameters.text` (string | null)
    Parameter value to substitute in the template.

  - `urlButtons` (array | null)
    List of URL button components with dynamic URL paths.

  - `urlButtons.index` (integer | null)
    Zero-based index of the URL button in the template.

  - `urlButtons.urlPath` (string | null)
    Dynamic path suffix appended to the button's base URL.

  - `urlButtons.url` (string | null)
    Full URL override for the button.

  - `urlButtons.text` (string | null)
    Button label text.

## Response 200:

  - `200` (unknown)
    Message sent successfully.

## Response 200 fields (application/json):

  - `messageId` (string)
    Unique identifier of the sent message.
    Example: 3425151601

## Response 400:

  - `400` (unknown)
    Invalid request — missing or malformed parameters.

## Response 400 fields (application/json):

  - `type` (string)
    Exception type identifier.

  - `code` (integer)
    Numeric error code. See [Error codes](https://docs.namirial.app/products/whatsapp/) for the full list.

  - `message` (string)
    Human-readable error description.

  - `errorDetails` (array | null)
    Additional validation error details, present on constraint violations.

  - `errorDetails.field` (string)
    The field that failed validation.

  - `errorDetails.message` (string)
    Validation error message.

## Response 401:

  - `401` (unknown)
    Authentication failed — invalid or missing credentials.

## Response 401 fields (application/json):

  - `type` (string)
    Exception type identifier.

  - `code` (integer)
    Numeric error code. See [Error codes](https://docs.namirial.app/products/whatsapp/) for the full list.

  - `message` (string)
    Human-readable error description.

  - `errorDetails` (array | null)
    Additional validation error details, present on constraint violations.

  - `errorDetails.field` (string)
    The field that failed validation.

  - `errorDetails.message` (string)
    Validation error message.

## Response 403:

  - `403` (unknown)
    Forbidden — the account does not have the required role.

## Response 403 fields (application/json):

  - `type` (string)
    Exception type identifier.

  - `code` (integer)
    Numeric error code. See [Error codes](https://docs.namirial.app/products/whatsapp/) for the full list.

  - `message` (string)
    Human-readable error description.

  - `errorDetails` (array | null)
    Additional validation error details, present on constraint violations.

  - `errorDetails.field` (string)
    The field that failed validation.

  - `errorDetails.message` (string)
    Validation error message.

## Response 400 examples:

  - `Invalid input` (unknown)

  - `Invalid template` (unknown)

  - `Wrong destination number` (unknown)

## Response 401 examples:

  - `Invalid credentials` (unknown)

  - `Missing API key` (unknown)

  - `Invalid API key` (unknown)

## Response 403 examples:

  - `Insufficient role` (unknown)

