# Start a WhatsApp Chat (new number)

Open a WhatsApp thread with a number a flow just learned — a Messenger lead who typed it, a form, a webhook — using an approved template, since no messaging window is open yet on that number.

## Getting here

**Automate → Workflows**, open a workflow, click **+** on the canvas, then pick **Start a WhatsApp Chat (new number)** under **Add Steps**.

## Before you start

- An **owner**, **admin** or **agent** can add this step and save the workflow. Publishing that workflow — the thing that makes it run on live conversations — is an **owner** or **admin** action.
- Building and running workflows depends on your plan; see [pricing](/pricing).
- A WhatsApp channel connected to this workspace, and a template already **approved by Meta** on that number.

## Set up

1. Open the workflow and click **+** where the new chat belongs — typically right after the step that captured the number.
2. Pick **Start a WhatsApp Chat (new number)**.
3. Choose the opening template from the list of approved templates.
4. Pick the number to reach: the contact's own number, or a field like their typed reply.
5. If the number may arrive without a country code, set the **country code** (e.g. 60).
6. Save the step, then publish the workflow.

## Fields

| Field | What it means | Default | Limits |
| --- | --- | --- | --- |
| Template | The approved template that opens the thread. | — | Lists every template this workspace has synced as approved, the same workspace-wide list **Send WhatsApp Template** shows — not filtered to a particular WhatsApp number, and this drawer has no channel picker to narrow it. |
| Number to reach | The contact's own stored phone number, or a field value such as their typed reply. | The contact's own number | — |
| Country code | Used only when the number has no country code of its own — a local number like 012-345 6789. | — | A number already written in full international form (e.g. with a leading +) does not need it. |

## How it works

- A number already written with a leading `+`, or one long enough and not starting with `0`, is read as already international and used as-is; anything else needs the **country code** field, or the step fails rather than guessing which country a bare local number belongs to.
- When the step names a specific number (a field, not left on the contact's own), and that number is not the same person's own stored phone, it checks marketing consent for THAT number first — has it opted in, and not opted out since — and refuses to open the thread at all if not. Left blank, the step opens the contact's own number with no consent check, because that is the customer this conversation is already about, not a third party.
- Consent lookups fail CLOSED: a number this workspace has never recorded, or a lookup that errors, is treated as "not consented", never as "consent unknown, send anyway".
- Independent of consent, this step also caps how many new WhatsApp threads one conversation may open this way: at most 3 in a rolling day, even when every one of them is the contact's own number — so a workflow loop cannot open unlimited threads.
- The **3-per-day cap is spent on the attempt, not on a thread actually opening**: it is checked and consumed right after the consent check, before the template-approval check or the send itself run — so a run that fails afterwards (an unapproved template, a bad number, a send error) still counts against the cap, even though no thread ended up open.
- Once consent (where it applies) and the cap both pass, the step checks the chosen template is currently approved by Meta on the channel — the same approval check **Send WhatsApp Template** runs — so a paused, disabled, rejected or still-pending template is refused before any thread is created.
- The contact and conversation are find-or-create, not always brand-new: a WhatsApp contact is looked up by this number's `wa_id` on the chosen channel first, and reused if one already exists (its phone is filled in if it was missing); a NEW contact is only created when none matches. The conversation works the same way — an already-open conversation for that contact on this channel is reused rather than opening a second one alongside it. Nothing here treats the send as an inbound message, so it does not reopen or move any existing messaging window either way.
- This new WhatsApp contact is not automatically merged with whatever contact record the number came from (a Messenger lead, a form submission) — they remain two separate contact records on the workspace unless merged some other way.
- The step's underlying data supports body variables and naming a specific WhatsApp channel, but the drawer offers neither — no variables list, no channel picker. A workspace with only one WhatsApp number never needs the picker; one with two or more fails every run of this step (see When it fails) because nothing in the drawer lets the author name which one to use. A chosen template with `{{1}}`, `{{2}}` … slots sends with no values in them when built through the drawer, and Meta rejects it.
- Once the contact and conversation exist, the send (or the failed attempt) is recorded on that conversation as a reply from the workflow, so a thread this step opened is never left silently empty.

## When it fails

- No number to reach: neither the step's own field nor the contact has one on file. The step fails with **no phone number on the step or on the contact.**
- The number cannot be resolved: an unusable string fails with a quoted explanation of what is wrong with it; a number lacking a country code with none set fails with **“…” has no country code — set a country code on the step, or ask for the number in full international form.**
- A named number that is not the contact's own has not consented to WhatsApp marketing: the step fails with **recipient has not opted in to WhatsApp marketing messages**, before any contact or conversation is created — the thread is never opened.
- This conversation has already made 3 attempts at this step in a rolling day (whether or not each one opened a thread): the step fails with **start_whatsapp send limit reached for this conversation today** — checked after consent, before the template check.
- This workspace has more than one connected WhatsApp channel and the step does not name one (the usual case — the drawer has no channel picker): the step fails with **more than one WhatsApp number is connected — name one on the step**, which nothing in the drawer lets an author do. A workspace with exactly one WhatsApp channel never hits this.
- The template is not currently approved: the step fails before any thread is created, carrying Meta's status reason — no half-open conversation is left behind with nothing said.
- The template send itself fails or cannot be confirmed after the contact and conversation were found or created: that conversation (new, or an existing one this step reused) still exists, and the attempt is recorded on it with the failure reason, so an operator opening the thread later can see why nothing has been said.
- This step has no failure branch of its own; the run continues to the next step regardless of which of the above happened.
- The reason is in the workflow's **Activity** tab, under **Execution log**, on this step's line.

## Limits

- The consent check only applies to a number you name that is not the contact's own — leaving the field blank to reach the contact's own number skips it entirely, the same as if consent were never in question.
- It cannot make more than 3 attempts per conversation in a rolling day, even to the contact's own number — a workflow that loops back to this step will start failing once that many attempts have run, whether or not each one actually opened a thread.
- It does not merge a newly created WhatsApp contact with the contact record the number came from. A Messenger lead who is opened as a new WhatsApp chat exists as two contacts afterward, not one, until merged separately — though if this exact number already has a WhatsApp contact and an open conversation on the chosen channel, this step reuses them rather than creating a duplicate.
- It cannot open a chat with no template — every open needs an approved one, because no messaging window exists yet to send free text into.
- The drawer offers no channel picker and no template-variables list, though the step itself supports both. A workspace with two or more connected WhatsApp numbers cannot use this step at all through the drawer — every run fails on the ambiguity — and a template built to take `{{1}}`, `{{2}}` … slots sends with them empty.
- It cannot guess a country for a bare local number; a number with no country code and no **country code** field set fails rather than being sent to a guessed destination.

## Best practices

- Capture the number right before this step (an **Ask a Question**, a form field) so the field you point this step at is fresh, rather than reaching back several steps for a value that may have changed.
- Set the **country code** whenever the source of the number is a form or a typed reply that might omit it — a Messenger-typed local number almost always will.
- Leave **Number to reach** on the contact's own number whenever that is what you mean — naming a different field turns on the consent check, which fails the step for anyone who has not opted in.

## Use cases

- A Messenger lead types their WhatsApp number to continue on WhatsApp; this step opens that thread with a welcome template.
- A web form captures a phone number for a callback request; a workflow opens a WhatsApp thread confirming the request was received.

## FAQ and troubleshooting

### Does this step check marketing consent before sending?

Only when you name a number that is not the contact's own — a value like their typed reply. Reaching the contact's own number, which is the default, skips the check. Either way, the template still has to be approved by Meta.

### Is the new WhatsApp contact linked to the Messenger (or form) contact the number came from?

Not automatically. They are two separate contact records unless merged some other way — unless this exact number already has its own WhatsApp contact on the chosen channel, in which case this step reuses that one rather than creating a new one.

### Why did the step fail with a country-code message?

The number you pointed it at was not written in full international form and no country code was set on the step. Add one, or ask for the number in a format that already includes it.

### This workspace has two WhatsApp numbers. Which one does this step use?

None reliably — the drawer has no channel picker, so with more than one WhatsApp channel connected the step fails every run with "more than one WhatsApp number is connected — name one on the step," and nothing in the drawer lets an author name one. This step only works as built through the drawer when the workspace has exactly one WhatsApp channel.

### Can I use this to message someone who already has an open WhatsApp conversation with us?

You can, but it is built for a number with no thread yet — it always sends the approved template rather than checking whether a window is already open. Use Send a Message or Send WhatsApp Template on the existing conversation instead.

### Can this step open unlimited WhatsApp threads if I loop a workflow back to it?

No. One conversation can make at most 3 attempts at this step in a rolling day, regardless of consent, which numbers are targeted, or whether each attempt actually opened a thread. The next attempt inside that window fails once the cap is reached.

## Related

- [Send WhatsApp Template](https://inchat.inseller.my/help/workflows/send-whatsapp-template)
- [Send a Message](https://inchat.inseller.my/help/workflows/send-a-message)
- [Ask for Marketing Consent](https://inchat.inseller.my/help/workflows/ask-for-marketing-consent)
- [Workflows: how a flow runs](https://inchat.inseller.my/help/workflows/workflows-overview)

---

Source files: `src/lib/workflows/ai-builder/spec.ts`, `src/lib/workflows/canvas-model.ts`, `src/components/workflows/WorkflowStepConfigDrawer.tsx`, `src/lib/workflows/open-whatsapp.ts`, `src/lib/workflows/dispatch-send.ts`, `src/lib/workflows/engine-message-actions.ts`, `src/lib/rate-limit/check.ts`, `src/lib/workflows/types.ts`, `src/lib/workflows/form-payload.ts`, `src/lib/access/permissions.ts`