Setting Up the WhatsApp Channel
WhatsApp is the most complete channel on the platform and supports templates, interactive messages, payments via PIX/Boleto, and order status updates. The connection uses the WhatsApp Business API with Meta. From the Hub, you start Facebook Embedded Signup to authorize your WhatsApp Business Account (WABA) and phone number in your Meta Business Manager.
Prerequisites
- Facebook Business Manager account (Meta Business Suite)
- A phone number you control. A number already in the WhatsApp Business app may be eligible for Coexistence (Coex); a personal WhatsApp number is not.
- Access to the Hub Chatt2.me dashboard with administrator permission on the Application
Connection process
1. Start onboarding
In the Hub Chatt2.me dashboard:
- Go to Channels → Activate/Configure → WhatsApp
- Click Connect with WhatsApp
- The Hub will redirect you to Facebook Embedded Signup
2. Authorize with Meta
Within the Facebook Embedded Signup flow:
- Log in with the Meta Business Manager administrator account
- Select (or create) the WhatsApp Business Account (WABA) to be linked
- Select (or add) the phone number that will be the channel
- Complete the Meta authorization — this grants the Hub the permissions it needs to send and receive messages on your behalf through the WhatsApp Business API
A WhatsApp Business Account is the Meta entity that groups your business's phone numbers. A WABA can have multiple numbers, but each number is a separate channel in the Hub.
Hub Chatt2.me connects your WhatsApp Business number using Meta's Embedded Signup in Business Manager. You attach a WABA and phone number to your organization; authorization is completed in Meta, and the Hub then uses that connection for messaging.
3. Verify the number status
After onboarding, the number goes through verification. Possible statuses are:
| Status | Description |
|---|---|
PENDING | Awaiting Meta verification |
CONNECTED | Ready to use |
FLAGGED | Account with restrictions — check Meta policies |
RESTRICTED | Limited sending — resolve pending issues in Meta |
4. Complete the business profile
Configure your WhatsApp Business public profile:
- Company name
- Description
- Address
- Business category
- Website
This is important for passing Meta's review and increasing user trust.
Provider token migration and renewal
For a connection migrated to Gupshup Universal Tokens, the Hub manages the
partner token (UT), the app-scoped token (UAT), renewal and authenticated
connection checks. Your backend continues to authenticate with the
Application API key in x-api-key; it does not supply provider tokens in
headers or request bodies.
This authentication migration preserves the existing channel and connected
number, WABA, webhook bindings and stored history. Keep the same from, to,
message payloads and webhook subscriptions. Do not disconnect or recreate a
channel solely to renew a provider token.
Token renewal does not change Meta's template approval, messaging restrictions or customer-service window. It also does not restart the one-time Coex contacts/history onboarding window or repeat an earlier synchronization request. A successful connection check confirms provider authentication, not message delivery; use message status events to track delivery.
If the connection remains unavailable, inspect the channel in the Hub dashboard and contact support with its ID, message/log IDs and the failure time. Provider availability and account permissions still apply, so renewal is not a promise of uninterrupted service. Do not share API keys or provider tokens in support messages. See provider troubleshooting.
WhatsApp Business app Coexistence (Coex)
Coex connects an eligible number already used in the WhatsApp Business app to the Hub through Embedded Signup. The business can continue using the app while the Hub receives supported messages and app echoes. This is different from moving a number entirely to the API.
After connecting a Coex number, open Channels → WhatsApp → [your number] → History synchronization. Configure one active channel webhook with message and message_echoes, then click Synchronize contacts and history. The provider allows each initial request only once during the 24 hours after onboarding. Once started, or after that deadline, the action is unavailable. This deadline is separate from the 24-hour customer-service messaging window.
The Hub requests WhatsApp Business app contacts first, then message history as soon as the contact request has a result. It does not wait for every contact to arrive: Gupshup accepts the request before Meta sends the data. If the contact request is rejected or its result is uncertain, the Hub still requests history within the available window and shows the outcomes separately.
Meta sends saved contacts and later address-book changes as asynchronous smb_app_state_sync events. The Hub stores each valid contact as a visitor for this channel. The provider supplies no contact total or final completion event, so the tab shows contacts observed without a contact percentage. Historical history chunks carry their own progress; that percentage covers history intake only.
As chunks arrive, the Hub stores sessions and messages and queues webhook deliveries as pending. It waits for history progress to reach 100%, then for 10 minutes without a newly accepted contact or history event (at most 60 minutes for this contact wait). Every accepted event must be processed, and historical media must be stored or reach a terminal failure before delivery starts. Media preparation can take hours. The tab separately shows intake, preparation and webhook delivery counts.
Meta can send a media placeholder before a separate history event with the media details. The Hub holds that message while waiting for the details; if they do not arrive after a one-hour wait, it marks the media unavailable, skips that message webhook and shows a partial result. Once a media message is skipped, later details cannot revise a webhook for it.
When released, queued historical message events keep their original message time and use the latest saved contact name available at delivery. This name is the business's address-book label, not a verified WhatsApp profile name. If a contact never supplies a name, the phone number remains the identifier. A contact arriving after its historical message was delivered updates the local visitor and future message payloads, but cannot revise the webhook already sent. Live WhatsApp messages and app echoes continue during historical preparation. Use X-Hub-Delivery-Id to deduplicate webhook retries.
Templates
WhatsApp requires Meta-approved templates to initiate conversations outside the 24-hour service window. For the full guide on creating templates, submitting for approval, and sending them — including dynamic headers, buttons, and the ORDER_STATUS type — see WhatsApp Templates.
Important limitations
- Outside the 24h window, only approved templates can be sent
- Non-template messages require a customer inbound on this same channel within the last 24 hours; an active internal conversation alone does not open that window.
- A number connected through the regular API flow cannot also stay in the WhatsApp Business app; eligible Coex numbers are the exception described above
Non-template Service usage
From October 1, 2026 at 00:00 America/Sao_Paulo, each connected number includes
1,000 non-template outbound Service messages per calendar month. The month uses
the number's configured billing timezone, or UTC when no WABA timezone is stored.
Each additional Service message costs BRL 0.09, without a terminal volume cap.
Reconnecting the number, renewing its subscription or resetting organization tiers
does not replenish the monthly allowance. Only usage from this activation onward
consumes it. Insufficient eligible wallet balance returns 402 before provider
delivery. Sandbox and template-category pricing remain unchanged; a monthly
number subscription is separate from these message charges.
Media formats and limits
| Type | Formats accepted for outbound | Outbound limit | Inbound mirror policy |
|---|---|---|---|
| Image | JPEG (image/jpeg), PNG (image/png); static WebP input is converted to PNG; GIF and animated WebP become silent MP4 video | 5 MB image / 16 MB converted animation | Provider maximum not separately published; Hub safety ceiling 2 GiB |
| Video | MP4 (video/mp4), 3GP (video/3gpp); MOV/QuickTime, AVI, MKV and WebM input is converted to H.264/AAC MP4 | 16 MB | Provider maximum not separately published; Hub safety ceiling 2 GiB |
| Audio | MP3/MPEG (audio/mpeg), AAC, M4A/MP4, AMR, OGG/Opus; WebM input is converted to M4A, or OGG/Opus with voice: true | 16 MB | Provider maximum not separately published; Hub safety ceiling 2 GiB |
| Document | Any format is attempted; known documented formats include TXT, PDF, DOC/DOCX, PPT/PPTX and XLS/XLSX | 100 MiB (104,857,600 bytes) | Provider maximum not separately published; Hub safety ceiling 2 GiB |
| Sticker | GIF, JPEG, PNG or WebP input normalized to exact 512×512 WebP | 100 KB static / 500 KB animated | Provider maximum not separately published; Hub safety ceiling 2 GiB |
For ordinary documentUrl messages, the known document formats above are a non-exhaustive list.
Other formats, such as CSV, may also be accepted by WhatsApp. The Hub attempts CSV, EXE, ZIP and
other unlisted file types within the size limit, preserving the original bytes; final acceptance
and delivery depend on the provider. The Hub's exact document ceiling is 100 MiB (104,857,600 bytes).
Template documents follow their separate provider requirements.
enqueued confirms submission, not delivery. Immediate provider rejection returns status: error
in the send response. A later failed update is exposed as status: error through subscribed status
webhooks, with the available provider error code, message and details.
The Hub applies only the conversions listed above. The sticker flow separately converts/resizes the supplied image to the WhatsApp sticker representation.
Inbound media URLs supplied by the provider are temporary or authenticated. The Hub attempts to mirror the binary to configured storage before exposing the normalized message. The 2 GiB value is an operational protection against unbounded downloads, not a claimed WhatsApp acceptance limit.
For ordinary outbound media, the Hub uses the URL form supported by Gupshup. Document messages
validate download and size before submission without a local MIME or extension allowlist; other
media types retain their MIME validation. Gupshup accepts either URL or media ID and gives the ID precedence when both
are present; URL sending is not deprecated. The Hub does not reuse template handleId values as
ordinary-message media IDs because they belong to a different upload flow.
Media captions
Add content.text alongside imageUrl, videoUrl, or documentUrl to send a caption in the
same message. audioUrl does not support a caption, including with voice: true; send its
description in a separate text request. See the caption support matrix.
Identifying the sender (from)
In POST /v1/communication/whatsapp/message, set from to the application channel UUID or the WhatsApp business phone number configured for that channel (with or without a leading +). The UUID always works as a fallback. See Sending messages overview.
Mark as seen
WhatsApp supports marking a target inbound message read with markSeen: true. Set context.messageId to an inbound Hub message ID, or omit it to select the latest inbound with a usable provider ID. The result returns that existing message ID; it does not mark every message in the conversation. Indicator display depends on the recipient settings.
See Mark as seen for the full payload reference.
Next steps
- Sending messages on WhatsApp — all supported types
- Detailed templates — dynamic headers, buttons, and ORDER_STATUS
- Payment Request & Order Status — charges and order status updates