Set up WhatsApp

Connecting WhatsApp puts one of your agents on a WhatsApp Business number you own. Customers message the number the way they message anyone. The agent reads the message, answers from its knowledge base, and every exchange lands in your inbox beside web chat and voice.

Who can do it. WhatsApp needs the Starter plan or above. Owners and admins connect, remove and reconnect numbers, choose the workspace default, change a number's settings (the Automation tab: reply mode, assigned agent, read receipts and typing indicator), edit the business profile and delete templates. The server enforces this: a member who tries gets Administrator access is required. The Channels item in the sidebar is shown to owners and admins.

On the Free plan the page shows Answer customers on WhatsApp with an upgrade prompt instead of the setup card. An owner sees View plans & upgrade; anyone else is asked to get an owner to upgrade. See Plans and limits.

What you get once it is connected #

• Inbound conversations answered automatically. Every message to the number reaches the agent on it, unless you've set the number's reply mode to hold back.
• Your team can step in. Take a conversation over from the inbox, or reply from your phone if the number stays on the WhatsApp Business app.
• Outbound sends from your backend. POST /messages sends free-form text or an approved template from any connected number.
• Opt-out handling across the workspace. A customer who sends STOP to one of your numbers is suppressed on all of them.

Vocabulary: WABA, sender, agent #

A workspace can hold several senders. A number belongs to one workspace at a time. If it is already connected somewhere else, setup stops with "This WhatsApp number is already connected to another workspace." A WhatsApp Business Account can't be split across workspaces either: "This WhatsApp account is already connected to another workspace."

Before you begin #

You need all of these. Missing one usually stops the flow inside Meta's window, where the error is least helpful.

• The Starter plan or above, and the owner or admin role.
• Admin access to your Meta Business portfolio.
• A business phone number you control.
• A way to receive Meta's SMS or voice verification on that number.
• An agent to answer. If there is none, the page says "Create an agent before connecting WhatsApp." with a Create agent link. Build one first: the Quickstart takes a few minutes.

Step 1: Choose the agent #

Open Channels → WhatsApp. With no number connected, the page shows Connect your first WhatsApp number, a three-step card.

Under Choose the agent that will answer, pick the agent from the list. You can change it later, per number, on the Automation tab.

Step 2: Choose how the number connects #

Step 2 of the card, Authorize your business with Meta, asks one question first. The answer picks a different Meta flow, so it can't be changed after the number connects.

A Phone + Amomic number behaves differently in three useful ways:

• Your phone replies appear in the inbox, marked Your phone and Sent from the WhatsApp Business app.
• In Smart mode, your phone replies count as a team reply, so the agent steps back while you're talking. See Reply modes.
• You can pause the agent for one customer from your phone by sending /stop, and hand back with /continue. See Pause the agent with /stop.

Your phone replies also reach your backend as the message.echo webhook event.

Step 3: Authorize with Meta #

Choose Continue with Meta. Meta opens in its own secure window. Sign in, then choose an existing WhatsApp Business Account and number, or create them there.

You authorize inside Meta's window and the credential comes back to Amomic-AI server-side. On this path you are never asked to paste a token into your browser.

When Meta finishes, Amomic-AI:

1. checks that the account and number you picked are the ones you authorized;
2. checks the number isn't connected to another workspace;
3. subscribes the account to incoming messages;
4. stores the credential in a secrets vault. It is never sent back to the browser.

The toast "WhatsApp sender connected and ready to verify." confirms it. The number's agent starts answering as soon as setup completes.

If the Meta window fails #

If the page says "Embedded Signup is unavailable right now. Use advanced recovery below or contact Amomic support.", contact support. Advanced manual recovery asks for a phone number ID, WABA ID, permanent access token and Meta app secret. It exists for support-led recovery of an existing installation, not for a normal connect.

Step 4: Verify a real conversation #

The sender opens on its Overview tab. The Verify a conversation card tests the real inbound session and the real reply path, which is the only proof that matters.

If you skip the first step, the send fails with "The 24-hour session window is closed; only approved template messages can be sent." That is the 24-hour window working. Message the number, then try again.

The button stays disabled, with "Resolve the sender's connection status before sending a test.", while the sender is Not delivering, Reconnect required, Paused, or not yet registered with Meta.

The sender workspace #

Once a number is connected, the page has two columns.

Senders (left) lists every connected number, the default first. Each row shows a health dot, the number, a Default pill on the workspace default, the verified business name, and Phone + Amomic if the number stays on the WhatsApp Business app. + adds a number. The footnote is a rule worth remembering: "A customer opt-out blocks sends from every number in this workspace."

The sender header (right) shows:

• the number, its health badge, Phone + Amomic or Amomic only, and Workspace default if it is;
• the verified business name and Meta's phone number ID;
• Agent, Quality (Meta's rating: Green, Yellow or Red) and Connected with (Meta, or Manual for a recovered connection);
• a live status strip. It checks the number with Meta every time you open the sender, then shows Live: Active or the problem. Re-check runs it again.

Below the header are five tabs:

Sender health #

Each sender shows one health state. The page names the fix for each.

Not delivering comes from real delivery receipts, so it catches what a token check can't. It clears on its own once a message from the number is delivered again. Nothing in the console fixes it, because the payment method, any policy appeal and any account restriction all live in Meta Business Manager.

The Readiness card breaks health into four checks: Phone number (registered with Meta), Authorization (credential available), Incoming messages (webhook subscription active) and Agent. Use it to see which part is failing.

The Connection tab #

The Internal sender ID (for example wa_snd_veloria_bookings) is the sender_id the API takes. You can also list senders and their ids from code with GET /channels.

Reconnect a sender #

Use Reconnect Meta on the Connection tab when a sender shows Reconnect required: the credential was revoked, the person who authorized lost access to the business portfolio, or the number moved. The dialog, Reconnect WhatsApp sender, asks for the agent and opens Meta again. Choose the same business, account and number.

A sender that was connected manually shows Upgrade with Meta instead. It runs the same Meta flow and replaces the manual credential with an authorized one.

Reconnecting keeps the number's setting for the WhatsApp Business app. That was fixed by Meta at first connect, so the dialog doesn't ask again.

Multiple senders and the default #

Add another number with Add sender, or + in the rail. Each one authorizes separately through Meta and gets its own credential, so a problem with one never touches another.

Per sender, independently:

• the agent that answers, and the reply mode;
• whether incoming messages are marked as read, and whether a typing indicator shows;
• the business profile customers see;
• its message templates (shared by every number on the same WhatsApp Business Account).

One sender is the workspace default, marked Default in the rail and Workspace default in its header. Change it with Make workspace default on another sender's Connection tab. The default decides which number POST /messages uses when you don't pass sender_id.

{
  "to": "+919840331276",
  "sender_id": "wa_snd_veloria_bookings",
  "text": "Your technician is on the way."
}

The default does not decide which number a support reply leaves from. That is set in Tickets → Reply settings. A ticket that arrived on WhatsApp always replies from the number the customer wrote to. See Working tickets.

Putting an agent on a sender #

Two routes set the agent on a number:

• From the channel. Open the sender's Automation tab, pick the agent under Assigned agent, and choose Save automation. It applies straight away.
• From the agent. Deploy the agent to the WhatsApp connection from the agent's deployments. Activating the deployment points the number at that agent. See Deployments.

Whichever acts last wins. Disabling the deployment that is serving the number takes its agent off. The sender then shows Agent required, and messages to it go unanswered.

Business profile and display name #

The Profile tab edits what customers see when they open your number in WhatsApp. Changes go straight to Meta and are live immediately. Choose Save profile to send them.

The display name can carry a note from Meta's review:

• "A change to this name is awaiting Meta's review."
• "Meta declined this name. Submit a different one in WhatsApp Manager."
• "No display name yet. Set one in WhatsApp Manager — customers see it above your number."

If Meta doesn't return the profile, the tab shows "We couldn't read the profile" with Try again. Nothing has changed at Meta.

Remove (disconnect) a sender #

Open the sender's Connection tab and expand Remove this sender at the bottom. It's tucked away because it's the one control on the page that silences a live number. Choose Remove sender, then confirm Remove and disconnect in the dialog Remove {number}?. You need the owner or admin role.

Removing a sender disconnects it from your workspace. It doesn't remove the number from WhatsApp.

Conversations already in your inbox are kept. The number can be connected again later, to this workspace or another, without verifying it again.

To take the number off the WhatsApp Cloud API entirely (back to the WhatsApp Business app only, or to another provider), deregister it in WhatsApp Manager. That can't be undone, and the display name goes back through review.

How an inbound message reaches your agent #

Customer sends a message
  → Meta delivers a signed webhook to Amomic-AI
  → the number it was sent to identifies the sender
  → the sender identifies the workspace, the agent and the reply mode
  → the agent answers, grounded in its knowledge base
  → the reply goes back out on the same number

Details in that chain that surprise people:

• Routing is by the receiving number. The same customer messaging two of your numbers gets two separate conversations, each with that number's agent.
• A sender with no agent is silent. No error to the customer, no fallback message. Check for Agent required if messages seem to vanish.
• Reply mode, contact settings and pauses come first. The agent stays quiet when the number is Off, when Smart mode has stepped back, when someone sent /stop, or when the contact's Let the agent reply switch is off. The message is still saved to the inbox in every one of those cases, unless the number is Off with Don't keep these conversations on. See Reply modes and Pause the agent.
• Out of conversations, the agent goes quiet. If the workspace has used its plan's conversation allowance, a message that would start a new conversation is saved but not answered. Conversations already open keep going.
• A suspended workspace answers nobody. While the workspace is suspended for an unpaid plan invoice, every message is saved to the inbox but not answered, with no typing…, even in conversations already open, and nothing is sent from the number at all: no agent replies, no team replies, no templates or API sends. Opt-outs are still recorded. It lifts by itself once the invoice is paid. See When a payment fails.

Every inbound message also restarts the 24-hour window for that customer on that number.

What the agent can read #

Voice notes over 8 MB, and recordings with no clear speech, get a reply asking the customer to send it again or type it.

What the agent can send #

Text, interactive replies, and voice notes.

Voice notes. When a customer sends a voice note, the agent replies with a voice note first and the written reply underneath. They're the same answer in two forms. The spoken one is reworded to be heard: no formatting, numbers and amounts said the way people say them, no links read out. The written one keeps the links, references and tappable buttons.

The voice note is a real WhatsApp voice message with a waveform, not a file to download. There's no setting for it: it happens whenever a customer sends a voice note and the language is one the agent can speak. If the voice can't be produced, the written reply still goes out on its own, so a voice note is never the only copy of an answer.

The agent writes in WhatsApp's own formatting (*bold*, _italic_, ~strike~), never markdown. Long replies split at sentence and paragraph boundaries rather than being cut off.

It can also produce native WhatsApp UI:

• Up to 3 options render as tap buttons, labels trimmed to 20 characters.
• 4 to 10 options render as a tap-to-open list, row titles trimmed to 24 characters.
• A single link renders as a call-to-action button.

The agent doesn't send images, documents or video on this channel. If a customer needs a file, it sends a link.

Opt-outs #

Opt-out is handled for you, before the message reaches the agent, and in every reply mode. A customer whose message matches an opt-out keyword exactly, ignoring case and surrounding spaces, is suppressed immediately.

Opt-out keywords: stop, unsubscribe, opt out, optout, cancel, stop promotions, band karo, बंद करो, रोको, बंद

A button tap counts too: tapping a quick reply labelled with one of these words (such as Meta's Stop promotions button on marketing templates) opts the customer out, and so does a button whose hidden payload is one of them, except cancel and बंद, so a "Cancel booking" button never unsubscribes anyone.

They get one reply and nothing else:

You won't receive any more messages from us. Send START to resubscribe.

Opt-in keywords: start, subscribe, unstop, shuru karo, शुरू करो

Welcome back! How can I help you today?

The match is exact. "please stop messaging me" doesn't suppress anyone; it reaches the agent as an ordinary message. /stop with a slash is different again: it's typed by you to pause the agent, and never suppresses the customer.

Sending from your backend #

Once a sender is connected and healthy, POST /messages is the whole surface:

curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: visit-SR-20817-confirmed" \
  -d '{
    "to": "+919840331276",
    "template": {
      "name": "service_visit_confirmed",
      "language": "en",
      "variables": ["Meera", "washing machine drum noise", "Thu 15 Oct, 10 am – 12 pm"]
    }
  }'

Two rules shape every integration on this channel:

• Free-form text only works inside the 24-hour window. Outside it you get 409 with session_window_closed. See The 24-hour window.
• Templates must already be approved by Meta. See Templates.

Troubleshooting #

Go-live checklist #

• [ ] The sender shows Ready or Connected, and Readiness has four green checks.
• [ ] Verify a conversation delivered a reply to your phone.
• [ ] The right agent is assigned, and you tested its answers in the playground.
• [ ] The reply mode matches how your team works.
• [ ] The business profile has a photo, an About line, a description and a website.
• [ ] The templates your systems will send are approved. See Templates.
• [ ] If you'll reply to tickets on WhatsApp, the Amomic-AI ticket template is approved or nominated.
• [ ] Your backend handles 409 session_window_closed and 403 suppressed.

Next #