# 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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mercuri.cx/features/introduction-mercuri-api/mercuri-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.