WhatsApp

With the WhatsApp channel your assistant answers messages customers send on WhatsApp, using the same prompt and knowledge as on the phone. This article covers what you need beforehand, how to connect to Meta step by step, and what the assistant can and cannot do on WhatsApp.

Prerequisites

The connection uses Meta's official WhatsApp Business Platform (Cloud API). Have the following ready before you start:

• A plan with WhatsApp. WhatsApp is included in Business, Pro and Enterprise, not in Starter. On Starter it is only possible with the WhatsApp add-on, if a reseller has allowed it; see Subscription & invoices. Without an active subscription you cannot turn WhatsApp on and incoming messages get no reply.
• The Editor or Admin role in the dashboard.
• A Meta Business account. This is the business account you also use to manage Facebook pages and adverts. If you do not have one yet, create it at business.facebook.com.
• An app in Meta for Developers with the WhatsApp product added (WhatsApp Business Platform / Cloud API).
• A phone number registered in that app. Note: a number that is currently in use in the consumer WhatsApp app (or the WhatsApp Business app) on a phone cannot be used; you must remove it there first. You can use your Yarla number, provided it can receive Meta's verification SMS or call.
• A System User with a permanent access token. Create it in Meta Business Suite under Business settings → Users → System users, assign the app and give the token at least the whatsapp_business_messaging permission. A temporary token from the test screen expires after 24 hours and is not suitable.
• The App secret of your Meta app, found under App settings → Basic.

WARNING

Keep the access token and App secret safe. We store them encrypted, but anyone who has them can send WhatsApp messages on behalf of your business.

Step by step

Connecting takes two parts: first you enter the details in the dashboard, then you tell Meta where to deliver messages.

Part A: in the dashboard

1. Open Assistants, choose the assistant that should handle WhatsApp messages, go to the Channels tab and open the WhatsApp row.
2. Switch Enable WhatsApp on. The Verify token is created at that moment. Without a suitable plan the switch stays off and you see a message.
3. Enter the Phone number ID. You find it in Meta for Developers under WhatsApp → API setup; it is a long string of digits, not your phone number itself. One Phone number ID works for one assistant only; if another assistant (also in another account) already uses it, you see "This WhatsApp number or verify token is already used by another assistant".
4. Enter the Display number: pick the country and type the number as customers dial it. A leading 0 is removed. It is stored in international format (for example +442012345678). This number is for display only, for example under Reachable through on Overview; the connection with Meta runs on the Phone number ID.
5. Paste the permanent access token under Access token and click Store as key. Do the same with the App secret under App secret. If you stored the key earlier, choose it from the dropdown. Both are stored encrypted and are not shown again. Without an App secret, incoming messages are rejected.
6. Copy the Webhook URL and the Verify token. You will need them in part B.

There is no save button: switches and dropdowns save straight away, text fields as soon as you leave the field.

Part B: in the Meta app

1. In Meta for Developers, open your app and go to WhatsApp → Configuration.
2. Under Webhook, click Edit and fill in:
   • Callback URL: the Webhook URL you copied in part A. It ends in /webhooks/whatsapp.
   • Verify token: the Verify token you copied in part A.
3. Click Verify and save. Meta now sends a verification request to us; if the token matches, the webhook is saved.
4. Under Webhook fields, click Manage and subscribe to the messages field. Without this subscription no messages will arrive.
5. Send a test message from your own phone to the WhatsApp number. Within a few seconds the conversation appears in the Inbox and the assistant replies.

If nothing comes back, see Troubleshooting: WhatsApp and webchat.

Features

Same prompt and knowledge

On WhatsApp the assistant uses the same prompt, the same knowledge and the same actions as on the phone. There is nothing to maintain twice: a new question and answer works on every channel straight away. Only call transfers, voicemail and Before the call actions work on the phone alone.

Replies written for text

On WhatsApp the assistant writes plain text in short paragraphs, without headings. It keeps replies brief, so they read well on a phone screen. When a task needs several details, it asks for them together in one message. The tone follows the speaking style on the Voice & greeting tab, unless you turn on Separate style for chats on the Instructions tab.

Reading photos

On the Channels tab, Interpret images is on by default. The assistant can then look at photos the customer sends. If a customer sends a picture of a leaking pipe or a boiler display showing an error code, the assistant can describe what it sees and ask targeted follow-up questions. That saves a phone call and gives your engineer a more complete request.

The Inbox does not show the photo. If the option is on, the photo is stored with the conversation and the transcript shows [image], followed by the caption if the customer added one and otherwise by (image). If the option is off, or fetching the photo fails, no photo is stored and the transcript only shows the caption or (image); the assistant then sends a fixed message asking the customer to describe it in text.

If the conversation was handed over or taken over, the assistant does not read the photo and does not send that fixed message either. With the option on, the transcript then only shows [image], without the caption.

Display name

Refresh display name next to the WhatsApp display name reads the name from Meta again. This works once WhatsApp is on and the Phone number ID and the access token are stored. A failed read keeps the previous name and shows the error.

WhatsApp template after the conversation

An After the conversation action of type WhatsApp sends a Meta template to a verified team number, never to the customer. You create the action on the Tasks tab, under Actions, with Add new. Fill in the Name, the Template name and the Team number. The Team number field starts with an example number: replace it with the number that should receive the template, in international format (for example +447700900123). The action is only saved once all three are right. Without a name nothing is kept; if only the template name is missing you see A required field is empty, and if the number is wrong, Some fields are not valid. The assistant is not saved until you fix it.

Verify the number in the action itself or under Settings → Team, at Verified WhatsApp recipients. Send code sends an SMS with a code that is valid for 10 minutes; this needs a number with SMS. Finish with Confirm code. As long as the number is not verified, the action fails.

The action always sends the template in the language nl, with one body parameter: the conversation summary ({{summary}}). So the template must be approved in Meta in that language, with one variable in the body.

The action runs after every conversation of this assistant, phone calls included, unless you fill in a condition at Under what condition should this run after the conversation?. It then runs only if the conversation meets that condition. WhatsApp must be on for this assistant, and the switch on the action's row turns the action itself on or off. A WhatsApp conversation is over when the assistant closes it, when someone clicks End conversation in the Inbox, or after 6 hours without new messages (with your team: not while the customer waits for an answer, after that 18 quiet hours).

Human handover

Under Handover to the team when, in the WhatsApp row of the Channels tab, you add rules with Add rule. In them you describe in plain language when the assistant should hand the conversation over, with up to 100 rules of up to 500 characters each. For example:

If the customer asks for a member of staff or becomes angry.
If it concerns an ongoing complaint about a previous repair.

As soon as a condition applies, or the customer insists on speaking to a person, the assistant hands the conversation over and stops replying. The assistant lets the customer know a colleague will take over. The conversation then appears in the Inbox under Waiting for you, and a notification goes to the Notification phone and the Notification email. An Admin sets those under Settings → Team, at Notifications and availability. The SMS only goes out if your business has a phone number.

Taking over from the Inbox

In the Inbox an Editor or Admin can take over a running WhatsApp conversation at any time. A Viewer cannot.

1. Open the conversation and click Take over. The assistant stays silent from that moment. Sending a reply straight away has the same effect.
2. Type your reply and click Send. It is sent from the same WhatsApp number, so nothing changes for the customer.
3. When you are done, click Hand back to the assistant. The assistant reads the messages exchanged in between and replies again as soon as the customer writes.

Voice notes and other messages

Voice notes are not supported yet. If a customer sends one, the assistant sends a fixed message asking them to send it as text. If the conversation was handed over or taken over, the assistant does not send this message; the transcript only shows (voice message). A shared location reaches the assistant as an address or coordinates. Documents and other message types cannot be read; the assistant only sees that such a message was sent.

WhatsApp's 24-hour messaging window

WhatsApp applies a 24-hour messaging window: within 24 hours of the customer's last message you may reply freely. Outside that window WhatsApp only allows pre-approved message templates. The assistant only replies to incoming messages, so it stays within the window. Yarla does not send templates to customers, not from the Inbox either. If you reply from the Inbox more than 24 hours later, Meta refuses the message and you see an error. Your reply does appear in the transcript, but the customer does not receive it; wait until the customer writes again or get in touch by phone.

Contacts and history

A WhatsApp number is matched automatically to the contact with the same phone number in Contacts. The assistant receives the name and notes from that contact by itself, on WhatsApp and on the phone. In actions the name is available as {{contact.name}}; in the prompt that variable stays empty.

If there is no contact yet, the assistant and the Inbox see the name on the WhatsApp profile. If the customer gives a name or company in the conversation, the contact is created. A blocked contact gets no reply. All WhatsApp conversations are listed in the Inbox; set the Channel filter to WhatsApp to see them on their own.

Costs

Meta charges its own rates for the Cloud API, which depend among other things on the customer's country. Meta bills these costs to you directly through your Meta Business account; they are separate from your Yarla subscription. Your plan has no limit on WhatsApp messages. The assistant's replies do count as usage. You see this on Overview → Figures at Usage this period. Admins also see it under Settings → Subscription & invoices, at Usage in the Texts row, together with SMS.

After a downgrade

When you switch to Starter without the WhatsApp add-on (you confirm what stops first), or your subscription ends, the assistant stops answering on WhatsApp from that date, including WhatsApp tasks. The WhatsApp settings stay saved and work again on a plan with WhatsApp. See Subscription & invoices.

Related articles

• Webchat
• Inbox & analytics
• Assistants
• Troubleshooting: WhatsApp and webchat