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

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

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

{% endcode %}
{% endtab %}

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

```
{
    "phoneNumberId":"PNa088af00e524f523394578e7b6c6966b",
    "channel":"sms",
    "recipient":"+15078009250",
    "message":{
        "type":"template",
        "template":{
            "templateId":"54b3cf77-82fd-4547-88b4-90f26d8d0310",
            "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 %}

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

{% 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. 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 `[ ]`.

{% 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 %}

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

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

* **Causa**: El `templateId` proporcionado no existe.
* **Solución**: Revisa tu `templateId` en el 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. **Respuesta Exitosa (200)**

* **Descripción**: El mensaje fue enviado con éxito.
* `messageId`: ID único asignado por WhatsApp.
* `status`: Será `"success"` si todo funciona correctamente.

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

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

{% endcode %}

***

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


---

# 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/mercuri-docs-es/caracteristicas/introduccion-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.