Troubleshooting: WhatsApp and webchat

WhatsApp and webchat are text channels that run on the same assistant as the phone. For WhatsApp, problems almost always sit in the connection with Meta (tokens, App secret, webhook subscriptions); for webchat, in the code on your website and the allowed websites. Below are the most common problems.

Symptoms, causes and fixes

Symptom	Likely cause	Fix
WhatsApp webhook verification fails	Verify token mismatch, WhatsApp has never been enabled, or wrong callback URL	Copy Verify token and Webhook URL again from the Channels tab and re-enter them in Meta
WhatsApp messages get no reply	App secret wrong, Access token expired, messages field not subscribed, number not registered, Phone number ID wrong, WhatsApp off, no active subscription, blocked contact, or the conversation is with the team	Check whether the message is in the Inbox and go through the points below
Your WhatsApp reply fails after 24 hours	The WhatsApp messaging window has closed	Wait for a new message from the customer or call the customer
The assistant doesn't look at images	Interpret images is off	Turn the option on in the Channels tab
Voice notes are not understood	Voice notes are not supported	The assistant asks for text with a fixed sentence; you can't change that sentence
Webchat widget doesn't appear	Incomplete code, wrong name in data-slug, webchat off, website not allowed, no active subscription, or ad blocker	Check the browser console, Enable webchat and Allowed websites
Ready-made chat page doesn't work	Webchat is off in the Channels tab, or there is no active subscription	Turn on Enable webchat or choose a plan
setContext throws an error or does nothing	Called before widget.js has loaded, over 8 KiB, or the conversation is with the team	Call setContext after widget.js has loaded and keep the context small
Team messages are not sent	Viewer role, conversation ended, or Meta refuses the message	Have an Editor or Admin reply, or wait for a new message from the customer

WhatsApp webhook verification fails

When you save the webhook, Meta checks that we know the verify token and that the callback URL responds.

1. Open Assistants, choose the assistant, go to the Channels tab and open the WhatsApp card. Copy Verify token again (watch for leading or trailing spaces). If there is no token yet, first turn on Enable WhatsApp; that needs a plan with WhatsApp.
2. Check that the callback URL in Meta is exactly the Webhook URL on that card: https://<api-domain>/webhooks/whatsapp.
3. Save the webhook in Meta again.

See WhatsApp.

WhatsApp messages get no reply

First check whether the message is in the Inbox.

If it isn't, it didn't reach us or wasn't processed. Check on the Channels tab (WhatsApp card) and in Meta:

• App secret must match your Meta app's exactly. If it is wrong or empty, our signature check fails and the message is rejected.
• The messages field must be ticked in the webhook subscriptions in Meta.
• The phone number must be registered with Meta for the Cloud API.
• Phone number ID must be the ID of the number the customer writes to; otherwise we can't link the message to the assistant.
• Enable WhatsApp must be on and Access token must be filled in.
• You need an active subscription. Without one, incoming messages are ignored.
• Messages from a contact set to Blocked are ignored. You can see this under Customers → Contacts.

If the message is there, there are two causes:

• Access token has expired. Use a permanent System User token rather than a temporary token from the developer console and paste it into Access token.
• The conversation is With a colleague. The assistant is paused and only answers again after you choose Hand back to the assistant in the conversation.

Your WhatsApp reply fails after 24 hours

WhatsApp only allows free-form replies within 24 hours of the customer's last message. The assistant always answers straight after a customer's message, so this doesn't affect it; it applies to a reply from your team in the Inbox. Meta refuses that message after 24 hours. You then see an error and the customer receives nothing, even though the message is in the transcript after a reload. We don't send message templates to customers, so wait until the customer sends something new or call the customer. This is a WhatsApp rule, not a Yarla setting.

The assistant doesn't look at images

If a customer sends a photo of a leak and the assistant answers with a fixed sentence saying it can't look at images, Interpret images is off. A caption on the photo gets no answer either. Turn the option on in the Channels tab (WhatsApp card) so the assistant can look at the photo and respond to it. If the same sentence comes while the option is on, the photo could not be fetched from Meta; ask the customer to try again.

Voice notes are not understood

Voice notes via WhatsApp are not supported. The assistant answers with a fixed sentence asking the customer to send their question as text. You can't change that sentence, not even with a rule in the instructions. The Inbox only shows (voice message), so your team can't listen to it either.

The webchat widget doesn't appear

If something goes wrong while loading, the widget shows no message: it simply stays away. So go through these points.

1. Open the browser console (F12) and look for errors mentioning widget.js and /public/chat/<slug>/config. A 404 means the name in data-slug doesn't exist; a 403 means your website isn't allowed or there is no active subscription.
2. Copy the code again from Code for your website in the Channels tab (Webchat card) and put it on every page where the chat should appear. data-slug must be exactly the Public link name and data-api must be in it. If you change that name later, the old code stops working.
3. Check that Enable webchat is on. If it is off, the widget stays away without an error in the console.
4. Check Allowed websites. Empty means any website. If it has entries, your website's address must be listed exactly, including https:// and without a path; with and without www are two different addresses. If you turn the chat on with an empty list, we fill in your business website, with and without www. If the chat is on another domain or subdomain, add that too.
5. Check that you have an active subscription. Without one, the widget stays away.
6. Test in a private window without an ad blocker.

See Webchat.

The ready-made chat page doesn't work

The Ready-made chat page does show a message; the widget on your own site stays away in these cases. If the page says "This chat is currently disabled.", webchat is off for this assistant. Turn on Enable webchat in the Channels tab; the message disappears once the page reloads. If the page says "This chat is unavailable", there is no active subscription.

Allowed websites only applies to the widget on other websites: the ready-made chat page opens with a filled-in list too. See Webchat.

setContext throws an error or does nothing

With window.YarlaChat.setContext you pass the assistant information about the visitor, such as the page or the product. The context goes along with the visitor's next message. Go through these causes:

• window.YarlaChat doesn't exist yet, because widget.js is still loading. The browser then throws an error. Call setContext after the script has loaded, for example in the page's load event. The widget has no ready event of its own.
• The context is larger than 8 KiB. The call then throws the error context exceeds 8 KiB and the previous context stays in place. Only pass the fields the assistant needs.
• The conversation is with the team, for example because Who answers is set to The team. The assistant doesn't answer then and doesn't read the context either.

Team messages are not sent

The reply field on a conversation is there for team members with the Editor or Admin role, as long as the conversation isn't Ended. You don't need to choose Take over first: Send takes over the conversation straight away, and the assistant stays silent until you choose Hand back to the assistant.

A conversation is Ended when someone has chosen End conversation, when the assistant has closed it, or automatically after a time without activity: on webchat the assistant's Inactivity timeout (minutes) (60 by default), on WhatsApp and SMS 6 hours, and with your team only 18 hours after the last message, never while the customer waits for an answer. After that you can no longer reply. On WhatsApp, the customer's next message starts a new conversation in the Inbox. On webchat, the visitor can't type any further in the same conversation: on the ready-made chat page they choose Start a new conversation, and in the widget on your own site you start a new conversation with window.YarlaChat.startNewConversation().

If sending fails on WhatsApp, you see an error and the customer receives nothing, even though the message is in the transcript after a reload. Usually the 24-hour window has closed or Access token has expired.

On webchat, the visitor sees your message almost immediately if the conversation was already with the team and the page is open and visible. If the browser can't open a WebSocket connection to Yarla, it takes at most about 30 seconds. If you take over a conversation that was still Active, your message only appears once the visitor reopens the chat, reloads the page or sends something. See Inbox & analytics.

Still stuck?

Can't find your problem here, or did the fix not help? Let us know via Report a problem and include the channel, the time and, for webchat, the domain the widget is on.

Related articles

• WhatsApp
• Webchat
• Inbox & analytics