Mercuri API

Enviar Mensaje de WhatsApp/SMS – Mercuri API

Endpoint

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

• El endpoint de la API para enviar mensajes de WhatsApp.

---

Headers

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

Request (Payload)

WhatsApp

{
   "phoneNumberId":"635894262943892",
    "channel":"whatsapp",
    "recipient":"[phone]",
    "message":{
        "type":"template",
        "template":{
            // "templateId":"1777667316490397",
            "templateId":"2020796801660936",
            "parameters":[
                {
                    "otpCode":"112233",
                    "businessPhoneNumber":"[phone]"
                    "firstName" : "JJ",
                    "lastName" : "Thomson",
                    "businessName" : "Mercuri",
                    "orderNumber" : "100ABCD45",
                    "orderTotal" : "1000",
                    "expirationTime":"2025-07-24T09:55:28.613Z",
                    "couponCode":"ABCD35"
                }
            ]
        }
    },
    "country":"US",
    "saveToInbox":true
}
}

SMS

{
    "phoneNumberId":"PNa088af00e524f523394578e7b6c6966b",
    "channel":"sms",
    "recipient":"[phone]",
    "message":{
        "type":"template",
        "template":{
            "templateId":"54b3cf77-82fd-4547-88b4-90f26d8d0310",
            "parameters":[
                {
                    "otpCode":"112233",
                    "businessPhoneNumber":"[phone]",
                    "firstName" : "JJ",
                    "lastName" : "Thomson",
                    "businessName" : "Mercuri",
                    "orderNumber" : "100ABCD45",
                    "orderTotal" : "1000",
                    
                    "expirationTime":"2025-07-24T09:55:28.613Z",
                    "couponCode":"ABCD35"
                }
            ]
        }
    },
    "saveToInbox":true

Descripciones de Campos:

Campo	Descripción
phoneNumberId	ID del número de WhatsApp Business / SMS (remitente). <sub>Sigue estos pasos para obtener tu phone number ID.</sub>
channel	"whatsapp" o "sms"
recipient	Número de teléfono del cliente (receptor)
message.type	"template" – tipo de mensaje
message.template.templateId	ID de plantilla de WhatsApp/SMS aprobado. <sub>Sigue estos pasos para obtener tu template ID.</sub>
message.template.parameters	Arreglo de objetos con campos (OTP, nombres, información del pedido, etc.)
country	Código de país del cliente. Si el número en recipient no incluye código de país, Mercuri usará por defecto este código de país (ejemplo: "US").
saveToInbox	true para guardar el mensaje en la bandeja de entrada de Mercuri

Response

1. Error de Validación – Número de Destinatario Inválido (422)

Causa: El formato del número del destinatario es inválido o falta el código de país.

Status: 422

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

2. Error de Validación – Formato Incorrecto del Payload (422)

• Causa: parameters debe ser un array, pero se envió un objeto.

• Solución: Encierra parameters dentro de [ ].

Status: 422

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

Error de Validación – Falta Template ID

• Causa: Falta templateId o no se envió como cadena de texto.

• Solución: Asegúrate de que templateId esté presente y entre comillas.

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 No Encontrado (400)

• Causa: El templateId proporcionado no existe.

• Solución: Revisa tu templateId en el dashboard.

Status : 400

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

1. Respuesta Exitosa (200)

• Descripción: El mensaje fue enviado con éxito.

• messageId: ID único asignado por WhatsApp.

• status: Será "success" si todo funciona correctamente.

Status : 200

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

---

Descripción del Flujo

1. Tu sistema prepara el payload con la información dinámica del cliente/pedido.

2. Envía una solicitud POST a la Mercuri API.

3. Mercuri procesa el payload y entrega el mensaje.

4. La API devuelve una respuesta a tu sistema para el seguimiento de éxito/error.