WhatsApp

Un número de WhatsApp Business se conecta a un perfil como cualquier cuenta (acc_…), con el alta integrada de Meta: GET /v1/connect/whatsapp. Si la cuenta de WhatsApp Business tiene varios números, Marsial vuelve con select=<sessionId> para que elijas uno, como con Facebook. Un número ya usado en la app de WhatsApp Business puede seguir en ella a la vez.

WhatsApp no recibe publicaciones: se usa para conversar.

Las dos reglas de WhatsApp

• La ventana de 24 horas. Durante las 24 horas siguientes al último mensaje de una persona le respondes con lo que quieras, desde la bandeja. Fuera de esa ventana, o para escribir tú primero, solo vale una plantilla aprobada.
• El límite diario. Un número nuevo puede escribir a 250 personas distintas al día; Meta lo amplía a medida que lo usas sin quejas.

Plantillas

Meta revisa cada plantilla antes de que puedas usarla (suele tardar minutos, como mucho 24 horas). Los datos de cada persona van en {{1}}, {{2}}… con un ejemplo de cada uno.

curl

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_listo",
    "category": "UTILITY",
    "language": "es",
    "components": [
      {
        "type": "BODY",
        "text": "Hola {{1}}, tu pedido {{2}} ya está listo.",
        "example": {
          "body_text": [
            [
              "Lucía",
              "#4821"
            ]
          ]
        }
      }
    ]
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "pedido_listo",
    "category": "UTILITY",
    "language": "es",
    "components": [
      {
        "type": "BODY",
        "text": "Hola {{1}}, tu pedido {{2}} ya está listo.",
        "example": {
          "body_text": [
            [
              "Lucía",
              "#4821"
            ]
          ]
        }
      }
    ]
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "name": "pedido_listo",
        "category": "UTILITY",
        "language": "es",
        "components": [
            {
                "type": "BODY",
                "text": "Hola {{1}}, tu pedido {{2}} ya está listo.",
                "example": {
                    "body_text": [
                        [
                            "Lucía",
                            "#4821"
                        ]
                    ]
                }
            }
        ]
    },
)
data = res.json()["data"]

Empieza como PENDING; con GET /v1/accounts/{id}/whatsapp/templates ves cuándo pasa a APPROVED (o REJECTED). La categoría decide lo que cobra Meta: UTILITY (pedidos, citas), MARKETING o AUTHENTICATION (códigos).

Escribir primero

Con una plantilla aprobada abres la conversación. La respuesta llega a la bandeja y como message.received, y desde ahí sigues con POST /v1/inbox/conversations/{id}/messages.

curl

curl -X POST "https://api.marsial.dev/v1/inbox/conversations" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "phone": "+34 611 222 333",
    "template": {
      "name": "pedido_listo",
      "language": "es",
      "params": [
        "Lucía",
        "#4821"
      ]
    }
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "phone": "+34 611 222 333",
    "template": {
      "name": "pedido_listo",
      "language": "es",
      "params": [
        "Lucía",
        "#4821"
      ]
    }
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/conversations",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "phone": "+34 611 222 333",
        "template": {
            "name": "pedido_listo",
            "language": "es",
            "params": [
                "Lucía",
                "#4821"
            ]
        }
    },
)
data = res.json()["data"]

Difusiones

Una plantilla aprobada a muchos números, ahora o programada. Cada {{n}} se rellena por persona con su nombre o su teléfono, o con un texto igual para todos.

curl

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "template": {
      "name": "oferta_black_friday",
      "language": "es",
      "variables": [
        {
          "field": "name"
        },
        {
          "value": "BF30"
        }
      ]
    },
    "phones": [
      "+34611222333",
      "+34622333444"
    ],
    "scheduledFor": "2026-11-27T09:00:00+01:00"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Black Friday",
    "template": {
      "name": "oferta_black_friday",
      "language": "es",
      "variables": [
        {
          "field": "name"
        },
        {
          "value": "BF30"
        }
      ]
    },
    "phones": [
      "+34611222333",
      "+34622333444"
    ],
    "scheduledFor": "2026-11-27T09:00:00+01:00"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "name": "Black Friday",
        "template": {
            "name": "oferta_black_friday",
            "language": "es",
            "variables": [
                {
                    "field": "name"
                },
                {
                    "value": "BF30"
                }
            ]
        },
        "phones": [
            "+34611222333",
            "+34622333444"
        ],
        "scheduledFor": "2026-11-27T09:00:00+01:00"
    },
)
data = res.json()["data"]

GET /v1/accounts/{id}/whatsapp/broadcasts devuelve cada difusión con cuántos la recibieron, la leyeron o fallaron; POST …/broadcasts/{broadcastId}/cancel para la que está programada o lo que queda por enviar.

Solo a quien quiere recibirlos

Escribe solo a personas que han aceptado recibir tus mensajes. Las quejas bajan la calidad del número y Meta puede limitarlo.

Lo que cuesta

Cada mensaje que envías (cada destinatario de una difusión) cuenta como un mensaje enviado. Además, Meta cobra su tarifa por cada plantilla directamente a tu cuenta de WhatsApp Business. Responder dentro de la ventana de 24 horas no tiene tarifa de Meta.

En el panel, todo esto está en Bandeja → WhatsApp.