Email, chat and messaging
This page covers the digital channels: email, webchat and the social and messaging channels (Facebook Messenger, Instagram, WhatsApp, Viber). Problems are grouped by what you see. For agents who receive nothing on any channel, start with the quick checks. For queues, skills and opening hours in general, see Workflows and routing.
Email
An email received at the weekend or after hours was never assigned
This is the most common email question. The email arrived, waited in the queue outside working hours, and was closed by the system before any agent logged in.
Cause: the workflow idle timeout expired. Every email workflow has an Idle timeout. If nothing happens in a conversation for that long, the system closes it. The default is 1440 minutes (24 hours), so an email that arrives on Saturday morning is closed before agents start on Monday.
Fix (customer administrator):
- In the portal, go to Email › Workflows and click the workflow.
- Click the pen icon at the top left, raise the Idle timeout (maximum 30240 minutes, 21 days) and click OK.
- Click Save. OK only closes the window; it doesn't save the workflow.
Set it long enough to cover your longest closed period, such as a long weekend or holiday. The new value applies to new conversations.
Closed emails like this don't appear as tasks, because no agent ever received them. Look for them in Historical Reports › Conversations instead.
An email waits in the queue for one agent and nobody else gets it
Cause: the queue waits for the customer's preferred agent. When Route to customer's preferred agent is on in the email Queue node, the email waits for that agent. If the agent is away, or lost their connection while handling the email, it can wait indefinitely.
Fix (customer administrator): in the email workflow, open the Queue node and set a Preferred agent timeout. After that time the email is offered to any skilled agent. The change applies to new emails; ask support about emails already stuck.
If emails wait although agents look available, also check:
- Skills. The email goes only to agents who have the queue's Attribute Requirements.
- Work item thresholds. With the tenant default of one task at a time, an agent busy on a call receives no emails. See Default work item thresholds, or Override work item thresholds on the agent.
- Emails the agent is still holding. Email tasks stay open after the agent replies, and the agent stays Busy until they close the task. See Waiting for responses.
Only Graia support can remove an email item that is stuck and can't be picked or closed by agents.
An inbound email never appeared in the agent application
The email is in the mailbox but not in Graia CCaaS. Graia CCaaS retrieves every email that Microsoft 365 or Google delivers to the mailbox, with its attachments, and shows it to the agent.
The sender is blacklisted. Blacklisting a sender stops all emails from them. Check the blacklist under Customers › Blacklist.
If the sender isn't blacklisted, send support the sender address, the exact time the email was received, details of any attachments, and the original email (as a file), and say which kind of mailbox the channel uses (Exchange, Gmail or IMAP).
Access policy error when you set up an email channel
When you create the channel, you get an error related to the Microsoft 365 application access policy.
Cause: your Microsoft 365 application access policy doesn't allow the Graia CCaaS email application to reach the mailbox. This happens when you limit mailbox access with a mail-enabled security group and the mailbox isn't in the group, or the policy points to the wrong group or application.
Fix (your Microsoft 365 administrator):
- Check that the mailbox is a member of the mail-enabled security group.
- Check that the
New-ApplicationAccessPolicyuses the Buzzeasy Email Integration application ID, that group as PolicyScopeGroupId, and RestrictAccess. - Wait for Microsoft to apply the change. New groups and policies can take a while to propagate. Then create the channel again.
The channel mailbox must also be a real user mailbox. Guest users, mail contacts and mail users can't be used.
The queue is flooded with spam or automatic replies
Two patterns cause hundreds or thousands of email tasks overnight:
- Spam from one address.
- An auto-reply loop. Your workflow's Send reply node answers an external auto-responder, which answers back, and so on.
Fix (customer administrator):
- Stop new items: in the portal go to Customers › Customers, open the sender's record, click Blacklist and block them for email. See Blacklist a customer record. Blacklisting stops all new emails from the sender. Blacklisted senders are listed under Customers › Blacklist.
- Contact Graia support to remove the items already queued. Blacklisting doesn't remove them, and only support can bulk-remove queued items.
To prevent loops, avoid sending automatic replies to automated senders. For example, set a custom field on known automated senders and use a Switch node in the email workflow to skip the Send reply node for them.
Unrelated emails appear in one conversation
Cause: the new email was composed from an old one. If someone creates a new email by replying to, or copying, an earlier sent email, it keeps that email's reply headers. Mail clients and Graia CCaaS then thread both conversations together, and an agent can reply to the wrong person with the wrong history.
Fix (agents and staff): start new emails as new messages. Before replying, check the recipient and the quoted history.
Several emails from a customer are grouped in one task
This is by design. Replies to the same original email, with the same subject, are grouped in one thread. The waiting task shows a red counter with the number of replies received. Follow-ups that arrive while an agent handles the conversation also don't start a new conversation, so no new auto-reply is sent.
A reply or forward doesn't include the whole email history
Reply and forward include the history up to the message you click them on. To include the whole thread, click Reply or Forward on the latest message. To include only part of it, click the button on an earlier message. Use Reply All to keep people in copy. Click the three dots in a message to expand the quoted history.
Other email questions
| Symptom | Cause and fix |
|---|---|
| The Save button of an email template stays greyed out | The template needs content and a fallback language. Add the language, click Set language as fallback (the star), make sure the content isn't empty, then save. See email templates. |
| You want a different signature per queue | The signature is set per email channel, not per queue. Use a separate channel (mailbox) for each signature. See Create an email signature. |
| An email sent to a customer never arrives and leaves no trace | The customer record holds an invalid address, for example wrapped in angle brackets (<name@example.com>). Correct the address in the customer record and send again. |
| The downloaded email transcript doesn't open | The transcript downloads as a .zip file. Extract it first: it holds one .eml file per message in the thread. Open those with an email client such as Outlook. |
| An agent wants to reply to an old, closed email | Start a new outbound email to the customer. See Outgoing email. |
Webchat
Chats end or messages go missing on mobile phones
This is the most common webchat problem. Customers say the chat stopped or they never got the agent's answer; agents see the customer disconnect, sometimes after several minutes.
Cause: the customer's browser stopped talking to the widget. Mobile browsers suspend a page when the customer switches app, the screen locks or the network drops. If the customer doesn't come back within the channel's Connection Timeout, the conversation is closed. A new message from the customer then starts a new chat, which can go to a different agent.
Fix (customer administrator): raise the Connection Timeout:
- In the portal, go to Chat › Webchat and click the channel.
- On the Widget Configuration tab, raise Connection Timeout. The default is 60 seconds; try 180 seconds, for example.
- Click Save.
Tell customers to keep the chat page in the foreground. Browser push notifications don't work while a mobile browser suspends the page.
Webchat embedded in your own mobile app behaves the same way when the app goes to the background. Check how your app handles the chat when it's minimised.
Chats close because of inactivity
Several settings end or mark a chat when nothing happens:
| Setting | Where | What it does |
|---|---|---|
| Connection Timeout | Webchat channel › Widget Configuration | Closes the chat when the customer's browser has lost the connection for this many seconds. |
| Customer inactivity timeout | Webchat channel › Widget Configuration | Marks the customer Inactive (orange dot) for the agent. It doesn't close the chat. |
| Idle timeout | Chat workflow › Details | Closes the conversation when nobody writes for this long. Default 1440 minutes, minimum 10 minutes, maximum 7 days. |
Agents can also close a chat themselves when the customer has been inactive for a while; that's not a fault. The agent sees the customer's activity status on the task.
For WhatsApp and other messaging channels, where customers often answer hours later, set the workflow Idle timeout long enough to cover nights and weekends, for example three days. A short idle timeout makes unanswered messages disappear.
The widget is blank, text is invisible or icons are missing
Cause: your website's styles leak into the widget. The widget inherits styles from the page it's embedded in, such as a white font colour or font size from a footer element. Text can become invisible, or icons can disappear on some pages but not others.
Fix (your website team): isolate the widget on the page and override the inherited styles in your website's CSS. Compare a page where the widget looks right with one where it doesn't. Elements of your page that sit on top of the widget, such as a privacy or cookie icon, can also cover the send button.
The widget doesn't load, or nothing happens after the customer clicks to start
Check these causes in order.
1. Your Content-Security-Policy blocks the chat service. The browser console shows a Content Security Policy error that names the connect-src directive.
Your website team must add the address the console names to the connect-src directive of your site's Content-Security-Policy, so the widget can open its connection. It's the chat service address in the widget code you copied from the portal. See Webchat widget doesn't work on your website.
2. The widget works on one site but not on another. Compare the embedded widget snippet on the working and the failing site. A different channel ID or address in the snippet is the usual cause. See embedding the webchat widget.
3. Trusted Domains doesn't list the site. If Trusted Domains is on in Widget Configuration, the widget works only on the listed addresses.
4. The browser translates the page. Automatic page translation can break the widget. Turn it off for the page and test again. The same applies to agents: if an agent sees an error each time they send a chat reply although the message arrives, turn off translation for the agent tab and reload it.
The widget shows the closed message during opening hours
Cause: business hours were changed just now. Changes to a channel's business hours take up to 10 minutes to apply. Wait 10 minutes and test again.
When you change hours for a holiday, change them on every channel, including Facebook, Instagram and WhatsApp channels. Each channel has its own Business Hours tab.
The pre-conversation message keeps appearing
This is by design. A pre-conversation message of type Visible message is shown on every page load. If that's too intrusive, choose Badge-only message or Hidden message in Widget Configuration, or shorten the text.
Changing the privacy policy or GDPR link
The link is stored in two places. Change both, on every webchat channel that uses it:
- Chat › Webchat › your channel › Widget Configuration › Custom Privacy Policy URL. Click Save.
- The consent question in each chat workflow that shows the link. Any node that asks the customer a question, such as Main menu or Custom question, can serve as the consent step; its text and outputs are free to configure. Edit the link in that node's text and save the workflow.
What the chat results mean
Task history and reports show a result for each chat task:
| Result | Meaning |
|---|---|
| Handled | The chat was closed normally. |
| Missed | The agent didn't accept the chat before the RONA timer ran out. |
| Rejected | The agent rejected the chat, which also moves them to RONA. |
| Abandoned | The customer left before the agent accepted the chat. |
| Failed | A system error ended the task. If you see this often, report examples to Graia support. |
Facebook, Instagram, WhatsApp and Viber
Facebook or Instagram messages stop arriving
Customers can see their messages in Messenger or Meta Business Suite, but nothing reaches Graia CCaaS, and customers don't get the bot's menu.
Cause: the page connection was lost or the Meta access token expired. This happens when the page administrator changes their password, Meta revokes the token, the administrator loses access, or consent for the Graia CCaaS Meta application is withdrawn.
Fix (customer administrator who administers the page): open the channel in the portal (Chat › Facebook or Chat › Instagram) and click Reconnect, logging in with an account that administers the page. See also Instagram channel connection status.
If the Facebook login fails at the first step, turn off browser extensions that block Facebook (ad and privacy blockers) and try again.
WhatsApp messages stop arriving: access token error
The WhatsApp channel shows an error related to the access token or the session.
Cause: the system user access token is no longer valid. Meta invalidates tokens, for example after a password change, and a token with an expiry date stops working when it expires.
Fix (customer administrator): generate a new token in Meta Business Settings, as described in Generate an access token. Set Token expiry to Never so it doesn't expire again. Then send the new token to Graia support through a secure channel. Support updates it in Graia CCaaS.
If you've lost administrator access to the Meta app or business account, regain it first. Without it, the callback URL and verify token can't be saved and the integration can't be repaired.
Setting up WhatsApp
- You need a Meta business account. Private Facebook accounts aren't enough. Create the Meta prerequisites first.
- You own the WhatsApp app and its numbers. You keep full control of the WhatsApp app and the phone numbers in your Meta business account, and you add or change numbers there.
Customers see an error about the maximum number of chat sessions
Cause: the concurrent chat limit was reached. The number of chat conversations open at the same time is limited to agent seat count × 10 for each channel type. For example, with 10 agent seats you can have up to 100 webchat conversations and, separately, up to 100 Facebook conversations at the same time.
Fix: the message clears as conversations end. If it happens regularly, increase your licensed agent seats with your Graia account manager.
Other messaging questions
| Symptom | Cause and fix |
|---|---|
| Agents receive nothing when a customer sends a voice message on Messenger | Voice messages aren't supported in chat. Tell customers at the start of the conversation, for example in the welcome message, that voice messages can't be received. |
| Viber customers don't see agent messages | Viber rejects messages when the agent's display name is longer than 28 characters. Keep the agent's Display Name short. See edit an agent. |
| Messages arrive outside your holiday hours on one channel | That channel still has its normal business hours. Update the hours on every channel. |
Related
Was this page helpful?