Creating a batch

A WhatsApp batch sends one approved template to every row of a list, from a number connected under WhatsApp → Numbers. Replies are answered by the text agent on that number, or by one the batch names, which sees the row’s columns. Creating a batch (POST /v1/whatsapp/batches) sends nothing: it lands as a draft you review and then send.

Before your first batch

A connected number — Twilio or Gupshup, set up in WhatsApp. Put a published text agent on its Messages cell if you want replies answered; without one, replies are stored and counted but nobody answers.
An approved template — write one under WhatsApp → Templates and submit it to WhatsApp (Twilio), or create it in your Gupshup app. Only approved templates can be picked for a batch.
Opted-in recipients — you may only message people who gave you their number and agreed to hear from you on WhatsApp (WhatsApp Business Messaging Policy). Messaging anyone else puts your number at risk.

Rules Meta enforces

Rule	Consequence
Every template is `marketing`, `utility` or `authentication`, and Meta re-checks approved ones	A promotional template submitted as utility is recategorized as marketing. A first message to a prospect is marketing.
US (`+1`) numbers never receive marketing templates	The row fails (`63049`) and is never resent. The form warns when a marketing template meets `+1` numbers.
Per-person marketing limit	Meta holds back a marketing template from someone who has had too many (`63049` on Twilio, `131049` on Gupshup). The batch resends it later — see `delivery_attempts` below.
Business messaging limit: 250 unique people a day, rising to 2,000, 10,000, 100,000 and unlimited as quality holds	Shared by every number in your business portfolio, which is why `send_daily_cap` defaults to 250.

Which templates can be sent

BSP	Sendable
Twilio	Text, image, video or document header; footer; URL, phone, quick-reply, copy-code and call buttons
Gupshup	Text-only templates

Carousel, catalog, flows and authentication templates are listed but refused. GET /v1/whatsapp/templates?integration_id=… returns each template’s header, body, footer, buttons and variables; one with unsupported_reason set cannot be sent from a batch.

Create the batch

In the dashboard: WhatsApp → Outbound → New batch. Pick the sender and template, type rows or upload a CSV (Download a sample file gives exactly the columns the template needs), map the phone column and each template variable — including one in a header or button URL — and set the pace. The preview shows row 1 as it will arrive.

curl -X POST https://api.talqing.com/v1/whatsapp/batches \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "224c93a2-f6c9-408d-bd21-bc1459f3a76f",
    "template_id": "HX91d46793053aedda5877d6c92a5f1b2f",
    "to_column": "phone",
    "variable_map": { "first_name": "first_name" },
    "send_daily_cap": { "kind": "fixed", "limit": 250 },
    "recipients": [
      { "input": { "phone": "+919876543210", "first_name": "Asha", "company": "Acme" } }
    ]
  }'

const batch = await talqing.whatsapp.batches.create({
  createWhatsAppBatchRequest: {
    integration_id: "224c93a2-f6c9-408d-bd21-bc1459f3a76f",
    template_id: "HX91d46793053aedda5877d6c92a5f1b2f",
    to_column: "phone",
    variable_map: { first_name: "first_name" },
    send_daily_cap: { kind: "fixed", limit: 250 },
    recipients: [{ input: { phone: "+919876543210", first_name: "Asha", company: "Acme" } }],
  },
});

batch = talqing.whatsapp.batches.create(
    integration_id="224c93a2-f6c9-408d-bd21-bc1459f3a76f",
    template_id="HX91d46793053aedda5877d6c92a5f1b2f",
    to_column="phone",
    variable_map={"first_name": "first_name"},
    send_daily_cap={"kind": "fixed", "limit": 250},
    recipients=[{"input": {"phone": "+919876543210", "first_name": "Asha", "company": "Acme"}}],
)

Template variables are 1, 2… on Gupshup and named or numbered on Twilio; variable_map maps each one to a column.

Fields

Field	Default	Meaning
`name`	The template’s name	1–200 characters
`integration_id`	—	The connected WhatsApp number
`template_id`	—	An approved template on that number
`to_column`	—	The column holding phone numbers
`variable_map`	—	Template variable → column, for every variable the template has
`recipients`	—	1–10,000 rows per request, each `{"input": {column: value}}`; a batch has no total ceiling
`timezone`	`UTC`	IANA zone for `window` and the daily cap
`window`	None	Sending hours and days
`send_gap_seconds`	`1`	Seconds between messages, 1–3600
`send_daily_cap`	`{"kind": "fixed", "limit": 250}`	Messages per local day; `null` is uncapped
`delivery_attempts`	`3`	Sends per row, the first included, while Meta’s per-person limit holds it back. 1–5; `1` never resends
`delivery_retry_after_hours`	`48`	Hours before a held-back row is resent, 24–168

send_daily_cap is {"kind": "fixed", "limit": 250} or a ramp, {"kind": "ramp", "start": 50, "end": 250, "step": 25, "interval_days": 1}, which warms up a new sender. A ramp rises by step every interval_days sending days — a weekend or a pause earns nothing — and belongs to the batch: two batches on one sender ramp independently.

What is refused at create

The whole batch is refused, every problem listed in one 400, when:

a template variable is unmapped, mapped to a column that does not exist, or variable_map names a variable the template does not have;
to_column is not in the list, or no row holds a valid number in it;
the template is no longer approved or cannot be sent from a batch, the integration is not active, or a Twilio sender is not ONLINE.

A problem with one row never refuses the batch. The row is kept as skipped with the reason, and becomes ready once its cell is fixed:

Row problem	Reason shown
Phone blank or not a valid number	`phone is empty`, `'98x' is not a valid phone number`
Same number as an earlier row	`same number as row 12`
A mapped cell is blank, has a line break or tab, or more than four spaces in a row	`first_name is empty`

A number without a country code is read in the sender’s country. The earliest row with a number keeps it, even after it is sent; delete that row and the next row with the number takes it.

Which agent answers

Leave the agent out and replies go to the agent on the number’s Messages trigger, whichever it is when they reply. Or name one: the batch takes agent_id, agent_version, agent, agent_override, agent_team and vars as an outbound call does (no secrets: one bag for a whole list is the wrong shape). Each send saves that agent for the person’s reply, as a posted template does. The number still needs its Messages trigger on, or replies never reach Talqing (422 messages_off).

What the replying agent knows

Every non-blank cell of a row becomes {{userdata.<column>}} for the agent that answers a reply — the same rule as a call batch. The template sits in the conversation as the agent’s own first message, header, footer and buttons included as text ([Button: Book a demo → https://…]).

Sending and monitoring

Send the draft, pace it, and follow rows to delivered, read and replied.

Connect the number and put a text agent on its replies.

Get started

Build

Guides

Creating a batch

Before your first batch

Rules Meta enforces

Which templates can be sent

Create the batch

Fields

What is refused at create

Which agent answers

What the replying agent knows

Next

Sending and monitoring

WhatsApp

​Before your first batch

​Rules Meta enforces

​Which templates can be sent

​Create the batch

​Fields

​What is refused at create

​Which agent answers

​What the replying agent knows

​Next

Sending and monitoring

WhatsApp

Before your first batch

Rules Meta enforces

Which templates can be sent

Create the batch

Fields

What is refused at create

Which agent answers

What the replying agent knows

Next