WhatsApp

Connect an expert to WhatsApp so people can message your business number and get answers from your documents. Aimy uses Meta's official WhatsApp Cloud API, so you need a Meta Business account and a short trip through Meta's developer console. It needs the Professional plan.

The older WhatsApp methods, Twilio and the QR code, are retired. Only the Cloud API is offered for new connections.

Before you start

• A Meta Business account, which is free to create at business.facebook.com.
• A phone number that can receive a text or call for verification, and that is not registered in WhatsApp or WhatsApp Business.
• Permission to create apps and System Users in that Business account. Some organisations limit this to administrators.
• An expert in Aimy with at least one document in its Knowledge Base.

Meta renames and moves its screens from time to time. If a label below is not quite where it should be, look for the nearest match.

What you need from Meta

Aimy asks for four things. Gather them first, then connect.

Step 1: create a Meta app

1. Go to developers.facebook.com/apps and choose Create App.
2. Choose the Business type and choose Next. Give the app a name, attach it to your Business account and create it.
3. On the app's dashboard, find WhatsApp in the product list and choose Set up.

Step 2: copy the two IDs

In the app's left menu, open WhatsApp and then API Setup. Copy the Phone Number ID and the WhatsApp Business Account ID. Meta gives every app a free test number here, so you can finish this whole guide before you attach your real number.

Step 3: create a System User and a token

1. Open Business Settings, then Users, then System Users, and choose Add. Name it and give it the Admin role.
2. With the System User selected, choose Assign assets and give it access to the app you created, and to the WhatsApp Business Account.
3. Choose Generate New Token, pick your app, and tick the whatsapp_business_messaging and whatsapp_business_management permissions.
4. Copy the token straight away. Meta shows it once.

Step 4: copy the App Secret

In the app, open App Settings, then Basic. Choose Show beside App Secret and copy it.

Step 5: connect in Aimy

Open Integrations under CONNECT and choose WhatsApp. Pick the expert from the Experts list on the left. Each expert connects to one WhatsApp number.

All four of the first rows are required. Choose Connect.

Aimy checks the details with Meta before it stores anything. A wrong token, a Phone Number ID from another account or a revoked System User is refused on the spot with a message you can act on. When it works, a green banner shows the business name and the number that Meta returned, for example Connected to Acme Sdn Bhd. That tells you that you linked the right account, not only that the form saved.

Step 6: paste two values back into Meta

After you connect, two more rows appear on the page. Each has a Copy button.

• Callback URL
• Verify token

Point at the (i) beside either label for a reminder of where it goes. In your Meta app, open WhatsApp, then Configuration, then Webhook, and choose Edit. Paste the Callback URL and the Verify token, then choose Verify and save. Copy and paste both values instead of typing them. A stray space is enough to fail the check.

The status message

A note under the two values tells you where things stand.

If the page still says it is waiting after you chose Verify and save in Meta, reload the page. The status updates when Meta's check succeeds.

Step 7: test it

Send a question your documents can answer to the number you connected, and check that the reply arrives. With Meta's free test number, only phone numbers you have added as recipients in API Setup can message it.

What the expert can read

• Text messages, which it answers.
• Photos and documents. If the customer adds a caption, the caption is the question. Supported files are JPEG, PNG, WebP and GIF pictures, and PDF, Word, Excel, PowerPoint, plain text and CSV documents.
• Voice notes get a short reply asking the customer to type instead.
• Video, stickers, locations and shared contacts get a short reply saying the expert reads text, photos and documents.
• Reactions, such as a thumbs up, get no reply.

Each customer has their own conversation, so one person's questions never mix with another's. Their messages appear in History with the source WhatsApp. See History.

The 24 hour reply window

WhatsApp only lets a business send a free form message within 24 hours of the customer's last message. This is Meta's rule, not an Aimy limit.

The expert answers as soon as a customer writes, so its own replies are always inside the window. The rule matters when a person takes over. If you use Handoff and the customer's last message is more than 24 hours old, WhatsApp refuses the person's reply, and the customer has to message again first. The Handoff page shows a line such as WhatsApp reply window closes with the time and the hours left, and warns you when the window has closed, so you do not write a reply that cannot be sent. See Handing a chat to a person.

Replace credentials or disconnect

For security, Aimy never shows the access token or the App Secret again, not even partly. When you come back to a connected expert, the Phone Number ID and WhatsApp Business Account ID are filled in, and the two secret rows are empty.

• To change anything, fill in all four rows again, including both secrets, and choose Replace credentials. Your callback URL and verify token stay the same, so nothing needs changing in Meta.
• To stop the expert answering on WhatsApp, choose Disconnect and confirm. If you connect again later, Aimy gives you a new verify token and you repeat Step 6.

If an expert was connected with Twilio or the QR code before those were retired, the page shows a note that the method is no longer offered for new connections. Choose Disconnect, then connect again with a System User token as above.

Troubleshooting

• Connect is refused straight away. The token, the Phone Number ID or the App Secret is wrong, or the System User lacks the two WhatsApp permissions from Step 3. Check them and try again.
• Stuck on Waiting for Meta to verify. The callback URL or verify token was not pasted correctly, or Verify and save did not succeed in Meta. Copy both values again from Aimy.
• Verified, but no replies arrive. The messages field was not subscribed in Step 6.
• It worked yesterday and is silent today. The token was created with a short expiry. Generate a new one with expiry set to Never and use Replace credentials.
• The page says WhatsApp rejected the access token. The token expired or was revoked in Business Manager. Issue a new one and use Replace credentials.
• Meta will not accept the phone number at all. The number is probably still registered in the WhatsApp or WhatsApp Business app. See the note at the top.