> For the complete documentation index, see [llms.txt](https://docs.mercuri.cx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mercuri.cx/features/introduction-mercuri-api/mercuri-api.md).

# Mercuri API

## **Send WhatsApp/SMS Message – Mercuri API**

{% hint style="info" %}
**View the Mercuri API Postman Collection :** 

<https://www.postman.com/mercuri-team/workspace/mercuri-api>
{% endhint %}

### **Endpoint**

```
POST https://api.mercuri.cx/v1/send_message
```

* The API endpoint to send WhatsApp messages.

***

### **Headers**

```json
{
 'Content-Type': 'application/json',
 'Authorization': `Bearer ${bearerToken}`
}
```

* `Content-Type` → JSON format for the request body.
* `Authorization` → Use your Mercuri API token .

***

### **Request (Payload)**

{% tabs %}
{% tab title="WhatsApp" %}
{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
   "phoneNumberId":"xxxxxxxxxxx",
    "channel":"whatsapp",
    "recipient":"+918971476855",
    "message":{
        "type":"template",
        "template":{
            // "templateId":"1777667316490397",
            "templateId":"xxxxxxxxxxxxx",
            "parameters":[
                {
                    "otpCode":"xxxxxxxxxxx",
                    "businessPhoneNumber":"xxxxxxxxxxx"
                    "firstName" : "xxxxxxxxxxx",
                    "lastName" : "xxxxxxxxxxx",
                    "businessName" : "xxxxxxxxxxx",
                    "orderNumber" : "xxxxxxxxxxx",
                    "orderTotal" : "xxxxxxxxxxx",
                    "expirationTime":"xxxxxxxxxxx",
                    "couponCode":"xxxxxxxxxxx"
                }
            ]
        }
    },
    "country":"US",
    "saveToInbox":true
}
}
```

{% endcode %}
{% endtab %}

{% tab title="SMS" %}
{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
    "phoneNumberId":"xxxxxxxxxxx",
    "channel":"sms",
    "recipient":"+15078009250",
    "message":{
        "type":"template",
        "template":{
            "templateId":"xxxxxxxxxxx",
            "parameters":[
                {
                    "otpCode":"112233",
                    "businessPhoneNumber":"+919986347648",
                    "firstName" : "JJ",
                    "lastName" : "Thomson",
                    "businessName" : "Mercuri",
                    "orderNumber" : "100ABCD45",
                    "orderTotal" : "1000",
                    
                    "expirationTime":"2025-07-24T09:55:28.613Z",
                    "couponCode":"ABCD35"
                }
            ]
        }
    },
    "saveToInbox":true
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Field Descriptions:**

| Field                       | Description                                                                                                                                                                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phoneNumberId               | WhatsApp Business/ SMS  number ID (sender). [<sub>*Follow these steps to get your phone number ID.*</sub>](/features/introduction-mercuri-api/faqs.md#where-can-i-find-the-phone-number-id-of-my-whatsapp-sms-number) |
| channel                     | `"whatsapp"or"sms"`                                                                                                                                                                                                   |
| recipient                   | Customer’s phone number (receiver)                                                                                                                                                                                    |
| message.type                | `"template"` – type of message                                                                                                                                                                                        |
| message.template.templateId | Approved WhatsApp/SMS template ID. [<sub>*Follow these steps to get your template ID.*</sub>](/features/introduction-mercuri-api/faqs.md#how-to-find-the-template-id-of-any-whatsapp-sms-template)                    |
| message.template.parameters | array of object  fields (OTP, names, order info, etc.)                                                                                                                                                                |
| country                     | Customer’s country code. If the `recipient` phone number **does not include a country code**, Mercuri will **default to this country code** (e.g., `"US"`).                                                           |
| saveToInbox                 | `true` to save message in Mercuri inbox                                                                                                                                                                               |

***

### **Response**

#### 1. Validation Failed – Invalid Recipient Number (422)

**Cause**: The recipient number format is invalid or missing country code

{% code title="Status: 422" overflow="wrap" lineNumbers="true" %}

```javascript
 { 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_RECIPIENT_PHONE_NUMBER", 
            "message": "Invalid recipient phone number: 8971476855 (country: US)." 
        } 
    ] 
}

```

{% endcode %}

#### 2. Validation Failed – Wrong Payload Format (422)

* **Cause**: `parameters` must be an **array**, but an object was sent.
* **Fix**: Wrap parameters inside `[ ]`.

{% code title="Status: 422 " overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.parameters: Invalid input: expected array, received 
object" 
        } 
    ] 
} 
 
```

{% endcode %}

#### Validation Failed – Missing Template ID

* **Cause**: `templateId` is missing or was not passed as a string.
* **Fix**: Ensure that `templateId` is provided and enclosed in quotes.

{% code title="Status: 422 " overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.templateId: Invalid input: expected string, received 
undefined" 
        } 
    ] 
} 
```

{% endcode %}

#### 3. Template Not Found (400)

* **Cause**: The provided `templateId` does not exist.
* **Fix**: Check your `templateId` in the dashboard.

{% code title="Status: 400" overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "API_TRIGGER_FAILED", 
    "errors": [ 
        { 
            "code": "WHATSAPP_TEMPLATE_NOT_FOUND", 
            "message": "WhatsApp template not found." 
        } 
    ] 
} 
```

{% endcode %}

4. **Success Response (200)**

* **Description**: Message was sent successfully.
* `messageId`: Unique ID assigned by WhatsApp.
* `status`: Will be `"success"` if everything works.

{% code title="Status Code : 200" overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": 
"wamid.HBgMOTE5OTAxNzU4NzM4FQIAERgSRkRCNjYzMTY1QkMxNzcyMjM4AA==", 
    "status": "success", 
    "errorCode": null, 
    "errors": null 
} 
```

{% endcode %}

***

### **Flow Overview**

1. Your system prepares the payload with dynamic customer/order info.
2. Sends a POST request to the Mercuri API.
3. Mercuri processes the payload and delivers the message.
4. API returns a response to your system for tracking success/error.

***