Knowledge & tools

WhatsApp tool

The WhatsApp tool lets an agent message your customers on WhatsApp from your business number. It can send approved templates at any time, send ordinary messages while a conversation is open, and look after the number's message templates for you. One tool configuration is one WhatsApp Business number, and a workspace can have as many as it has numbers.

Connect the same number as a WhatsApp channel too. The tool sends; a WhatsApp channel is what receives. With both in place, every message the tool sends shows up in that customer's conversation, and when they reply, the channel's agent picks it up right where the message left off. Without a channel, replies to the number don't reach any agent. See Replies and conversations.

What it does

Sends templates. A template is a message Meta has approved in advance. It's the only way to start a conversation with someone, or to write to them again once 24 hours have passed since their last message.
Sends messages. Ordinary text, images, documents, locations and other message types, while the customer's 24-hour window is open.
Manages templates. Lists them with their review status and quality, creates new ones (including from Meta's template library), edits, deletes and archives them, compares how two performed, and copies them over from another of your WhatsApp Business Accounts.

Because the tool runs outside the agent's conversation turn, it can also be used as a post-call hook. Sending a WhatsApp follow-up after every phone call is a common one.

Connect your number

Open Tools → Add tool → WhatsApp. There are three ways in, and they all end up the same. When the assistant sets up a WhatsApp agent for you, it asks for your number in the chat instead, and the card there has the same options.

Connect with Facebook

The quickest. Click Continue with Facebook, sign in, and pick your WhatsApp Business number in the window that opens. Hania connects it and names the configuration after the number, for example "WhatsApp (Acme Support (+1 555-010-0199))". Connecting the same number again updates the existing configuration instead of making a second one.

If the number couldn't be registered for sending automatically, you'll see a note saying so. The connection is still saved. This usually means the number is already registered with its own PIN, and if sending fails later, you can register it in WhatsApp Manager.

Use a connected WhatsApp channel

If the number is already connected under Channels, choose Use a connected WhatsApp channel and pick it. No new sign-in is needed. The tool and the channel stay independent afterwards: removing one leaves the other working.

It works the other way round too. When you connect a WhatsApp channel, Use an existing WhatsApp tool connection sets the channel up from a number you connected here, with nothing to paste.

Enter the details manually

Choose Enter the details manually instead and fill in three things: an access token, the Phone Number ID and the WhatsApp Business Account ID. Hania doesn't check them when you save, so the form offers Test the connection straight afterwards. It asks WhatsApp for the number's templates without sending anything, and shows Meta's answer if something is wrong.

The access token should be a system user token with the whatsapp_business_messaging and whatsapp_business_management permissions, set never to expire. The temporary token on your app's WhatsApp page lasts about a day, so a connection made with it stops working soon after.

Reconnecting

A number connected with Facebook or from a channel shows as Connected when you edit it, and its credentials aren't editable there. To replace them, use Reconnect and run either option again. The name and description stay as they are. The description and safety settings can be changed at any time.

A number you entered manually can be switched over too. Edit it, choose Connect with Facebook or a channel instead, and connect. Hania replaces the stored details with the new connection.

Finding your Phone Number ID and WhatsApp Business Account ID

You only need these for the manual option. Both are long numbers, and neither is your phone number.

In WhatsApp Manager, open Phone numbers to find the Phone Number ID for each of your numbers.
In Meta for Developers, open your app's WhatsApp API Setup page, which shows both the Phone Number ID and the WhatsApp Business Account ID.

Templates

Each WhatsApp configuration on the Tools page has a Templates button. It opens the number's templates as Meta has them right now, so the status you see is always current. Use Refresh after a change. Filter by status, category, language or name.

Review and status

Meta reviews every new template, usually within minutes and at most 24 hours. Only Approved templates can be sent. You'll also see In review, Rejected, Paused, Disabled, Archived, In appeal and Being deleted.

Quality is Meta's quality rating for the template: High, Medium, Low, or Not rated yet.

Rejections and how to fix them

A rejected template shows the reason in the list and next to the editor. The common ones:

The format isn't valid - check the variables, their example values and how the text is laid out.
The category doesn't match the content - for example a promotion sent as Utility. Choose the category that fits what the message says.
The content doesn't match the chosen category - the same fix.
The content breaks WhatsApp's policies - the wording has to change.

Fix the template in the editor and save it again.

Creating and editing

Click New template and fill in the name, language, category, and the parts of the message: an optional header, the body, an optional footer and optional buttons (quick replies, links and call buttons). The preview beside the form shows how it will look. Anything the form doesn't cover, such as carousels, can be written in Meta's own format with Edit as JSON.

Names use lowercase letters, numbers and underscores only, like order_update.
Variables are written {{1}}, {{2}}, or by name, like {{first_name}}. Every variable needs an example value, which is what Meta's reviewers see.
Header images, videos and documents are added as a public https link. Hania fetches the file and uploads it to WhatsApp. JPEG and PNG images, MP4 videos and PDF documents are accepted.
Edits work on approved, rejected and paused templates, not on one that's still in review. An approved template can be edited up to 10 times in 30 days, and once in 24 hours.
Order status templates are a kind of Utility template. Tick Order status template when creating one. WhatsApp only accepts them once payments are set up for your account.
Delivery time limit is optional. It sets how long WhatsApp keeps trying to deliver a message sent with the template before it gives up. Leave it blank to use WhatsApp's default.
You can create up to 100 templates an hour on one account, and a name can only be used once per language.

The template library

The Template library tab lists Meta's ready-made templates for common needs, like delivery updates and appointment reminders. Use this creates your own copy under a name you choose, which then goes through review like any other. If the template has a link button, you'll be asked for your web address for it.

Deleting and archiving

Deleting asks whether to remove just the one language version or every language of that name. The name of an approved template can't be used again for 30 days after it's deleted. Archiving hides an approved or rejected template from sending until you unarchive it. Meta also archives templates that haven't been used for 12 months, and deletes them 28 days after that unless you unarchive them.

The Compare and copy tab compares how two approved templates performed over the same dates (each needs at least 1,000 sends in that time), and copies templates from another WhatsApp Business Account that belongs to the same Meta business. Copying runs in batches of up to 500: start with batch 0, then 1 for the next, and so on. To copy only some templates, list their IDs.

Sending

Templates versus free text. Free text works only within 24 hours of the customer's last WhatsApp message. Outside that window, send an approved template. When the customer replies, the window opens again.
Agreement first. Only message people who agreed to hear from you on WhatsApp. This is Meta's policy.
US numbers. WhatsApp doesn't deliver marketing templates to US phone numbers.
Display name. A number can't send until Meta has approved its display name. Creating and managing templates works in the meantime.
Payment method. A number connected with Facebook also needs a payment method on its WhatsApp Business Account before it can send.

Testing your setup

Most new templates wait for Meta's review, so there's a quicker way to try a send end to end. In New template, choose Use the quick test template. It fills in a login code template, which Meta approves as soon as it's created, and gives it a name with a short random ending. You only check the name and create it.

Then open Send a test, pick the template, enter a code of up to 15 characters and the number to send to. The code appears in the message and in its copy button. Delete the template when you're done. Because an approved name can't be reused for 30 days, the random ending keeps the next test's name fresh.

Some accounts also have Meta's own hello_world sample, already approved and with nothing to fill in. It's there only on accounts where Meta created it.

Sending a test

The Send a test tab sends a template or a free-text message to a number you enter, in international format like +14155550123. Fill in the template's variables, or edit the parameters as JSON for header media and buttons. A test is a real message to a real person and Meta charges for it, so you're asked to confirm before it goes.

"Accepted" means WhatsApp took the message, not that it arrived. The result also says where a reply would go, with a link to the conversation when the number is connected as a channel.

Replies and conversations

Each WhatsApp configuration on the Tools page says where replies to its number go, for example "Replies go to Acme Support (+1 555-010-0199), answered by Support Agent". If the number isn't connected as a channel, it warns that replies won't reach any agent and offers Connect as a channel, which opens the channel form with this number already chosen.

When the number is a channel, every message the tool sends is added to that customer's conversation with the channel's agent, marked Sent on WhatsApp by the agent's tool. A template appears with its variables filled in and its buttons listed, and a picture or document shows as a short label. So when the customer replies, the agent has the whole exchange in front of it.

Delivery status

Messages the tool sent show WhatsApp's delivery status in the conversation:

One tick - sent.
Two ticks - delivered to the customer's phone.
Two blue ticks - read.
Not delivered, in red, with WhatsApp's reason.

The ticks update by themselves while the conversation is open, usually within seconds. Read is shown only when the customer has read receipts turned on, so a message that stays at delivered may well have been read. Messages the channel's agent writes in reply don't carry ticks.

Giving the tool to an agent

Assign the WhatsApp configuration to an agent like any other tool, from the agent's Tools tab. The agent can then send templates and messages and manage templates when you ask it to, in chat or in a scheduled run. To send a WhatsApp message after every call, add the tool as a post-call hook on a voice agent.

Some blueprints, such as the Customer Support Agent, Appointment Reminder Caller and Virtual Receptionist, offer WhatsApp as an optional app you can add when you create the agent.

Two of the ready-made WhatsApp agents are built around this tool: the Template Manager, which looks after your templates when you ask, and Daily Appointment Reminders, which sends your approved reminder template the day before each booking.

Safety settings

Every tool carries safety settings that decide what it may do in scheduled or triggered runs, where no one is watching. A new WhatsApp configuration starts with all of them off:

Read-only is off, because the tool sends messages and changes templates.
Destructive is off. Turning it on would stop the tool sending anything in unattended runs unless the agent is allowed destructive actions.
Sends data externally is off. Turning it on means an unattended run can only message a number written into its goal, which would stop automatic reminders to your customers. Turn it on if you want that limit.

The tool is also marked as not safe to retry, because sending twice means two messages. All of these are under Show advanced in the form, and you can change them at any time. Chatting with an agent directly is never limited by them.

Troubleshooting

"The authorization code is invalid or expired" - the Facebook sign-in took too long or was interrupted. Run Continue with Facebook again.
"Subscription failed - check the WhatsApp Business Account" - Hania couldn't link to the account you picked. Check that you chose the right business and number, then try again.
"This WhatsApp channel has no WhatsApp Business Account id" - the channel was connected before Hania stored that ID. Reconnect the channel, or connect the tool with Facebook instead.
"That WhatsApp tool connection is incomplete" - when connecting a channel from a tool connection. Reconnect the tool first.
The template isn't approved or doesn't exist in that language - only approved templates can be sent, in a language they exist in. Check the status on the Templates screen.
The number's display name isn't approved yet - Meta reviews the display name of new numbers. Wait for the approval before sending.
"This WhatsApp connection can send messages but can't manage templates" - the connection was made without permission to manage templates. Choose Reconnect and connect with Facebook again; listing templates keeps working until you do.
Sending is refused because of billing - add a payment method to the number's WhatsApp Business Account, then try again.
A free-text message is refused - the 24-hour window is closed. Send an approved template instead.
Not delivered, "to maintain healthy ecosystem engagement" - Meta limits how many marketing messages one person receives, and held this one back. It shows as a red status on the message rather than an error when sending.
Not delivered, the user stopped marketing messages - the customer has opted out of your marketing messages.
A name already used - a template with that name already exists in that language, or in another category. Pick a different name.
A template can only be edited when approved, rejected or paused - wait for the review to finish.
Too many variables for the amount of text, or a variable at the start or end - add more words around the variables.
A library template needs button inputs - fill in the link button's web address before creating it.
Order status templates or some button types are refused - these need payments set up in WhatsApp first.
Comparing needs at least 1,000 sends of each template - choose a longer date range, or wait until both have been sent more.
No templates found to copy - the other account belongs to a different Meta business, or has nothing that can be copied.
The phone button's number isn't valid - use the full international format, like +15551234567.
An unknown error when using a flow button - check the flow's ID.

Security

The access token is stored encrypted and is never shown again, in the console or anywhere else. Editing a manually entered configuration without retyping the token keeps the stored one. To cut off access, remove the configuration in Hania, or revoke the token or remove Hania from your business integrations in Meta's Business Settings.