WhatsApp

Números de WhatsApp Business: plantillas que revisa Meta, escribir primero con una plantilla aprobada (POST /inbox/conversations) y difusiones a muchos números. Las respuestas dentro de las 24 horas van por la bandeja. Estas cuentas no publican.

Listar plantillas

GET/v1/accounts/{id}/whatsapp/templates

Se leen en directo de Meta, una por nombre e idioma.

Parámetros

• idstringobligatorio

Respuesta 200

data []

• idstringobligatorio
• namestringobligatorio
• languagestringobligatorio
• categorystringobligatorio

  MARKETING, UTILITY o AUTHENTICATION.

• statusstringobligatorio

  El veredicto de Meta: PENDING, APPROVED, REJECTED, IN_APPEAL, PAUSED, DISABLED o PENDING_DELETION. Solo se puede enviar APPROVED.

• componentsobject[]obligatorio

curl

curl "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Crear una plantilla

POST/v1/accounts/{id}/whatsapp/templates

Meta la revisa (hasta 24 horas): empieza como PENDING y solo se puede enviar cuando está APPROVED. La categoría decide lo que cobra Meta por cada mensaje.

Parámetros

• idstringobligatorio

Cuerpo

• namestringobligatorio
• categorystringobligatorio

  Valores: MARKETING · UTILITY · AUTHENTICATION

• languagestringobligatorio

  Código de idioma de Meta, por ejemplo es, en_US, pt_BR.

  mín. 2máx. 10

• componentsobject[]obligatorio

  Los componentes de Meta: un BODY con su texto ({{1}}, {{2}}…) y un ejemplo de cada dato, y si quieres HEADER, FOOTER y BUTTONS.

  máx. 10 elementos

Respuesta 201

data

• idstringobligatorio
• namestringobligatorio
• languagestringobligatorio
• categorystringobligatorio

  MARKETING, UTILITY o AUTHENTICATION.

• statusstringobligatorio

  El veredicto de Meta: PENDING, APPROVED, REJECTED, IN_APPEAL, PAUSED, DISABLED o PENDING_DELETION. Solo se puede enviar APPROVED.

• componentsobject[]obligatorio

curl

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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}`,
  },
});
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']}"},
)
data = res.json()["data"]

Borrar una plantilla

DELETE/v1/accounts/{id}/whatsapp/templates/{name}

Todos los idiomas del nombre, o solo language.

Parámetros

• idstringobligatorio
• namestringobligatorio
• languagestring

  mín. 2máx. 10

Respuesta 204

Sin contenido

curl

curl -X DELETE "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates/pedido_listo" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates/pedido_listo', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});

Python

import os, requests

requests.delete(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/templates/pedido_listo",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)

Escribir primero con una plantilla

POST/v1/inbox/conversations

Abre una conversación de WhatsApp (o la retoma tras 24 horas sin mensajes) con una plantilla APPROVED. La respuesta llega a la bandeja y como message.received; desde ahí responde con POST /inbox/conversations/{id}/messages durante 24 horas.

Cuerpo

• accountIdstringobligatorio

  La cuenta de WhatsApp desde la que escribir.

• phonestringobligatorio

  A quién escribir.

• templateobjectobligatorio

  Una plantilla APPROVED: la única forma de escribir primero, o tras 24 horas sin mensajes.

  template

  • namestringobligatorio

    máx. 512

  • languagestringobligatorio

    mín. 2máx. 10

  • paramsstring[]

    Los valores de los datos, en orden: cabecera, cuerpo y botones de URL.

    máx. 30 elementos

Respuesta 201

data

• conversationIdstring | nullobligatorio

  La conversación en la bandeja (cnv_…): ahí llegan las respuestas.

curl

curl -X POST "https://api.marsial.dev/v1/inbox/conversations" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
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']}"},
)
data = res.json()["data"]

Listar difusiones

GET/v1/accounts/{id}/whatsapp/broadcasts

Con cuántos destinatarios recibieron, leyeron o fallaron.

Parámetros

• idstringobligatorio

Respuesta 200

data []

• idstringobligatorio

  Id opaco de la difusión (bcs_…).

• accountIdstringobligatorio
• namestringobligatorio
• statusstringobligatorio

  draft, scheduled, sending, completed, failed o cancelled.

• templatestring
• scheduledAtstring
• recipientCountintegerobligatorio

  máx. 9.007.199.254.740.991

• sentCountintegerobligatorio

  máx. 9.007.199.254.740.991

• deliveredCountintegerobligatorio

  máx. 9.007.199.254.740.991

• readCountintegerobligatorio

  máx. 9.007.199.254.740.991

• failedCountintegerobligatorio

  máx. 9.007.199.254.740.991

• createdAtstring

curl

curl "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Enviar o programar una difusión

POST/v1/accounts/{id}/whatsapp/broadcasts

Una plantilla APPROVED a una lista de números, ahora o en scheduledFor. Cada destinatario es un mensaje enviado; Meta cobra su tarifa de plantilla a tu cuenta de WhatsApp Business. Un número nuevo llega como mucho a 250 personas al día hasta que Meta amplía su límite.

Parámetros

• idstringobligatorio

Cuerpo

• namestringobligatorio

  máx. 200

• templateobjectobligatorio
  template

  • namestringobligatorio

    máx. 512

  • languagestringobligatorio

    mín. 2máx. 10

  • variablesobject | object[]

    Qué rellena {{1}}, {{2}}… para cada destinatario: uno de sus datos, o el mismo valor para todos.

    máx. 30 elementos

    variables

    • fieldstringobligatorio

      Valores: name · phone · email · company

• phonesstring[]obligatorio

  Los destinatarios con su prefijo de país.

  máx. 10.000 elementos

• scheduledForstring (date-time)

  Se envía a esta hora; si no, ahora.

Respuesta 201

data

• idstringobligatorio

  Id opaco de la difusión (bcs_…).

• accountIdstringobligatorio
• namestringobligatorio
• statusstringobligatorio

  draft, scheduled, sending, completed, failed o cancelled.

• templatestring
• scheduledAtstring
• recipientCountintegerobligatorio

  máx. 9.007.199.254.740.991

• sentCountintegerobligatorio

  máx. 9.007.199.254.740.991

• deliveredCountintegerobligatorio

  máx. 9.007.199.254.740.991

• readCountintegerobligatorio

  máx. 9.007.199.254.740.991

• failedCountintegerobligatorio

  máx. 9.007.199.254.740.991

• createdAtstring

curl

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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}`,
  },
});
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']}"},
)
data = res.json()["data"]

Cancelar una difusión

POST/v1/accounts/{id}/whatsapp/broadcasts/{broadcastId}/cancel

Una programada, o lo que queda de una que se está enviando. Lo ya enviado, enviado está.

Parámetros

• idstringobligatorio
• broadcastIdstringobligatorio

Respuesta 204

Sin contenido

curl

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts/bcs_…/cancel" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts/bcs_…/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/whatsapp/broadcasts/bcs_…/cancel",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]