WhatsApp numbers, replies and opt-outs

One Mailhuset account can run several WhatsApp numbers, for example one per product or brand. Each number keeps its own conversations, its own opt-outs and, if you give it to a project, its own webhooks and API keys.

Give a number to a project

Open WhatsApp → Overview. Each number has a Project setting:

• Shared by all projects (the default): every project's API keys can send from the number, and its replies reach every webhook endpoint on the account.
• A project: replies to the number reach only that project's webhook endpoints, and only that project's API keys can send from it. A key from another project that names the number gets 403 with the code WHATSAPP_SENDER_OTHER_PROJECT.

You can change it from the API too:

PATCH /v1/whatsapp/senders/{id}
{ "projectId": "proj_123" }

Send "projectId": null to share the number again.

Which number a message is sent from

Pass senderId on POST /v1/whatsapp to choose the number. Without it, Mailhuset uses the oldest connected number in the key's project, and if the project has none, the oldest shared number.

Replies you send from the dashboard inbox always go out from the number the conversation is on.

Webhook events

WhatsApp events arrive on your webhook endpoints like email events:

Every WhatsApp event carries senderId, the number it was sent from or received on. whatsapp.inbound also carries:

• phone: who wrote to you.
• to: the number they wrote to.
• inboundId: Mailhuset's id for the message. It is the same on every retry, so use it to ignore duplicates. It is also the id for downloading media with GET /v1/whatsapp/inbound/{inboundId}/media.
• text, or media with its type, file name and caption.

Opt-outs are per number

When someone replies STOP to one of your numbers, they are opted out of that number only. Your other numbers can still message them.

You can also record consent yourself, under WhatsApp → Consent or with POST /v1/whatsapp/opt-ins:

• With a senderId, the opt-in or opt-out applies to that number only.
• Without one, it applies to every number on the account.

When both exist for the same phone, the number's own record wins. So a phone opted out of every number can still be opted back in for one, and a STOP to one number is never undone by an account-wide opt-in.

The 24-hour window

Free-form text can only be sent within 24 hours of the person's last message to that same number. Outside the window, send an approved template. The window is tracked per number, so a message to one number does not open a window on another.

Need help? Email support@mailhuset.com.