Whatsapp

WhatsApp Business numbers: templates Meta reviews, writing first with an approved template (POST /inbox/conversations) and broadcasts to many numbers. Replies inside 24 hours go through the inbox. These accounts take no posts.

List templates

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

Read live from Meta, one entry per name and language.

Parameters

• idstringrequired

Response 200

data []

• idstringrequired
• namestringrequired
• languagestringrequired
• categorystringrequired

  MARKETING, UTILITY or AUTHENTICATION.

• statusstringrequired

  Meta's verdict: PENDING, APPROVED, REJECTED, IN_APPEAL, PAUSED, DISABLED or PENDING_DELETION. Only APPROVED can be sent.

• componentsobject[]required

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"]

Create a template

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

Meta reviews it (up to 24 hours): it starts as PENDING and can only be sent once APPROVED. The category decides what Meta charges for each message.

Parameters

• idstringrequired

Body

• namestringrequired
• categorystringrequired

  Values: MARKETING · UTILITY · AUTHENTICATION

• languagestringrequired

  Meta language code, e.g. es, en_US, pt_BR.

  min 2max 10

• componentsobject[]required

  Meta's components: a BODY with its text ({{1}}, {{2}}…) and an example for each placeholder, plus optional HEADER, FOOTER and BUTTONS.

  max 10 items

Response 201

data

• idstringrequired
• namestringrequired
• languagestringrequired
• categorystringrequired

  MARKETING, UTILITY or AUTHENTICATION.

• statusstringrequired

  Meta's verdict: PENDING, APPROVED, REJECTED, IN_APPEAL, PAUSED, DISABLED or PENDING_DELETION. Only APPROVED can be sent.

• componentsobject[]required

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"]

Delete a template

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

Every language of the name, or only language.

Parameters

• idstringrequired
• namestringrequired
• languagestring

  min 2max 10

Response 204

No content

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']}"},
)

Write first with a template

POST/v1/inbox/conversations

Opens a WhatsApp conversation (or continues one after 24 hours of silence) with an APPROVED template. Their answer arrives in the inbox and as message.received; from then on reply with POST /inbox/conversations/{id}/messages for 24 hours.

Body

• accountIdstringrequired

  The WhatsApp account to write from.

• phonestringrequired

  Who to write to.

• templateobjectrequired

  An APPROVED template: the only way to write first, or after 24 hours of silence.

  template

  • namestringrequired

    max 512

  • languagestringrequired

    min 2max 10

  • paramsstring[]

    Values for the placeholders, in order: header, body, then URL buttons.

    max 30 items

Response 201

data

• conversationIdstring | nullrequired

  The conversation in the inbox (cnv_…): replies arrive there.

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"]

List broadcasts

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

With how many recipients each reached, read and failed.

Parameters

• idstringrequired

Response 200

data []

• idstringrequired

  Opaque broadcast id (bcs_…).

• accountIdstringrequired
• namestringrequired
• statusstringrequired

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

• templatestring
• scheduledAtstring
• recipientCountintegerrequired

  max 9,007,199,254,740,991

• sentCountintegerrequired

  max 9,007,199,254,740,991

• deliveredCountintegerrequired

  max 9,007,199,254,740,991

• readCountintegerrequired

  max 9,007,199,254,740,991

• failedCountintegerrequired

  max 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"]

Send or schedule a broadcast

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

An APPROVED template to a list of numbers, now or at scheduledFor. Each recipient is one outbound message; Meta charges its template fee to your WhatsApp Business account. A new number reaches at most 250 people a day until Meta raises its tier.

Parameters

• idstringrequired

Body

• namestringrequired

  max 200

• templateobjectrequired
  template

  • namestringrequired

    max 512

  • languagestringrequired

    min 2max 10

  • variablesobject | object[]

    What fills {{1}}, {{2}}… for each recipient: one of their fields, or the same value for all.

    max 30 items

    variables

    • fieldstringrequired

      Values: name · phone · email · company

• phonesstring[]required

  Recipients with their country code.

  max 10,000 items

• scheduledForstring (date-time)

  Send at this time; now when omitted.

Response 201

data

• idstringrequired

  Opaque broadcast id (bcs_…).

• accountIdstringrequired
• namestringrequired
• statusstringrequired

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

• templatestring
• scheduledAtstring
• recipientCountintegerrequired

  max 9,007,199,254,740,991

• sentCountintegerrequired

  max 9,007,199,254,740,991

• deliveredCountintegerrequired

  max 9,007,199,254,740,991

• readCountintegerrequired

  max 9,007,199,254,740,991

• failedCountintegerrequired

  max 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"]

Cancel a broadcast

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

A scheduled one, or what is left of one being sent. Messages already sent stay sent.

Parameters

• idstringrequired
• broadcastIdstringrequired

Response 204

No content

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"]