WABAs

A WABA (WhatsApp Business Account) is Meta’s container for a business that wants to use WhatsApp. It groups one or more phone numbers, manages access tokens, and is the unit Meta uses for compliance, rate limits and template approval.

You don’t create WABAs by hand — they’re provisioned when your customer completes Embedded Signup (Meta’s OAuth-like flow). We capture the WABA + tokens automatically and link them to your Customer.

Customer "Clínica San Lucas"
  └── WABA business_id=123 waba_id=456 status=active
        ├── Phone +54 11 5555 1234
        ├── Phone +54 11 5555 5678
        └── Templates (3 approved)

Key Meta concepts

Term	Meaning
`business_id`	Meta Business Manager ID — the legal entity (e.g. “Clínica San Lucas SRL”)
`waba_id`	The WABA itself — one Business can have many WABAs
System User token	Long-lived access token that GoSendAPI uses to send/receive on behalf of the WABA
Display name	What contacts see (“Clínica San Lucas”). Needs Meta approval, can be changed
Verified business	Optional Meta verification (green checkmark). Unlocks higher limits

Properties

Field	Type	Description
`id`	bigint	Internal numeric ID (NOT the Meta waba_id)
`customer_id`	bigint	Which Customer owns this WABA
`waba_id`	string	Meta’s WABA identifier
`business_id`	string	Meta’s Business Manager identifier
`display_name`	string	Business display name shown to contacts
`status`	enum	`pending` / `active` / `suspended`
`external_reference`	string	Optional reference for mapping

Status lifecycle

pending ──> active ──> suspended (if Meta bans the business)
              │
              └──> active again (if appealed successfully)

pending: Customer started Embedded Signup but didn’t finish, or token is missing
active: WABA is fully provisioned, can send/receive
suspended: Meta suspended the WABA (policy violation, high complaint rate, etc.)

⚠️

A suspended WABA cannot send messages. You’ll get 403 Forbidden from Meta. The customer has to appeal directly with Meta — we can’t unsuspend on their behalf.

Tokens

Each WABA has at least one AccessToken in our DB, encrypted with AES-256-GCM. We:

Refresh it before expiration
Rotate when Meta deprecates an OAuth scope
Never expose the raw token via API (only the API uses it to call Meta)

If a WABA shows status pending but you onboarded the customer, check that the AccessToken exists. The dashboard has a “Reconnect” flow for this.

Limits per WABA (Meta enforced)

Limit	Default	Increase by
Conversations/24h (initial)	1,000 unique contacts	Reach the limit consistently → Meta upgrades you to next tier (10k, 100k, unlimited)
Messages/sec throughput	”Standard” (80 msg/s)	Apply for “High Throughput” tier via Meta — requires consistent volume
Templates per WABA	250	Contact Meta support
Phone numbers per WABA	25	Contact Meta support

GoSendAPI tracks these from Meta’s API and surfaces them in the dashboard.

Onboarding a new WABA

You don’t call an endpoint to “create a WABA”. The flow is:

Create a one-time URL for your customer (POST /admin/tenants/:id/setup-links)

1. Generate Setup Link

They click the link, log into their Facebook Business account, grant permissions

2. Customer authorizes

We POST whatsapp.phone_number.created to your endpoint with the new WABA + phone info

3. Webhook arrives

The phone_number_id can immediately receive POST /v1/messages calls

4. Start sending

What’s next

The actual lines registered under each WABA

Phone numbers

Approved message templates owned by the WABA

Templates

Customers Phone numbers