Mercuri API

Send WhatsApp/SMS Message – Mercuri API

View the Mercuri API Postman Collection :

https://www.postman.com/mercuri-team/workspace/mercuri-api

Endpoint

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

• The API endpoint to send WhatsApp messages.

---

Headers

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

• Content-Type → JSON format for the request body.

• Authorization → Use your Mercuri API token .

---

Request (Payload)

WhatsApp

{
   "phoneNumberId":"xxxxxxxxxxx",
    "channel":"whatsapp",
    "recipient":"[phone]",
    "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
}
}

SMS

Field Descriptions:

Field	Description
phoneNumberId	WhatsApp Business/ SMS number ID (sender). Follow these steps to get your phone number ID.
channel	"whatsapp"or"sms"
recipient	Customer’s phone number (receiver)
message.type	"template" – type of message
message.template.templateId	Approved WhatsApp/SMS template ID. Follow these steps to get your template ID.
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

Status: 422

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

2. Validation Failed – Wrong Payload Format (422)

• Cause: parameters must be an array, but an object was sent.

• Fix: Wrap parameters inside [ ].

Status: 422

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

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.

Status: 422

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

3. Template Not Found (400)

• Cause: The provided templateId does not exist.

• Fix: Check your templateId in the dashboard.

Status: 400

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

1. Success Response (200)

• Description: Message was sent successfully.

• messageId: Unique ID assigned by WhatsApp.

• status: Will be "success" if everything works.

Status Code : 200

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

---

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.

---