Onyx VoiceDocumentation
All chapters

Docs / Call handling

Chat and WhatsApp

Onyx Voice answers written conversations as a team: visitors of the company's website (a chat window the website adds with one line of code) and customers on WhatsApp (through Meta's WhatsApp Business Platform, or through Twilio). This chapter covers setting up each kind of channel, who answers, answering in the portal, and the chat report.

Channels and teams

A channel is one place conversations come from: a website, or one WhatsApp number. To add one:

  1. Open Chat & WhatsApp (under Connections) and click Add a channel.
  2. Choose the Kind, give it a Name, fill in its settings (below) and tick the people who answer it under Answered by. With nobody ticked, everyone of the company answers it.
  3. Click Add channel. The list then shows what to put on the website or into Meta or Twilio.

When someone writes for the first time (or again after the conversation was closed), the team gets an e-mail, if their extensions have e-mail addresses.

Chat on your website

Settings: Title (at the top of the chat window), Greeting (the first message visitors see), Only on these websites (for example https://www.acme.com, https://acme.com; empty means any site that has the snippet) and Colour.

Copy the snippet from the channel's row and put it on every page of the website, just before </body>:

<script src="https://pbx.example.com/chat/widget.js" data-onyx-chat="..." async></script>

A chat button then appears at the bottom right. Visitors may give their name and e-mail address; the conversation stays with them while they move between pages. The server must be reachable from the internet under its name, with its certificate (see Names and certificates).

WhatsApp through Meta

You need a WhatsApp Business account and an app in Meta for Developers with the WhatsApp product.

  1. In Meta: WhatsApp > API Setup shows the Phone number ID. Make a permanent access token for a system user with the whatsapp_business_messaging permission (Business settings > System users). App settings > Basic shows the App secret.
  2. In Onyx Voice, add a WhatsApp (Meta Cloud API) channel with the phone number ID, the access token and the app secret.
  3. Back in Meta: WhatsApp > Configuration > Webhook: paste the channel's webhook address and its Verify token (both in the channel's row), click Verify and save, and subscribe to messages.

Onyx Voice checks that every message really comes from Meta (the app secret signs it). WhatsApp allows a free-form reply only within 24 hours of the customer's last message; after that it needs an approved template message, which Onyx Voice does not send yet: the reply then shows "not sent" with that reason.

WhatsApp through Twilio

Add a WhatsApp (through Twilio) channel with the Account SID, the WhatsApp sender (your WhatsApp-enabled Twilio number, +1...) and the Auth Token. In the Twilio console, set the sender's "When a message comes in" webhook to the channel's webhook address (HTTP POST). Onyx Voice checks Twilio's signature on every message.

Answering in the portal

People who answer a channel see Chat in the portal, with the newest conversations first and the number of new ones in its heading. Click a conversation to read it, type the reply and press Enter (Shift+Enter for a new line). Take it marks the conversation as yours; Close puts it away until the customer writes again.

From the command line: onyx chat inbox acme 101 and onyx chat reply acme <conversation id> 101 "text".

The chat report

At the bottom of Chat & WhatsApp, the Chat report shows, per channel and per person, the conversations of the last seven days, how many were answered, the average time to the first reply, and the number of messages.

When it does not work

  • No chat button on the website. The channel is off, the page's address is not in Only on these websites, or the snippet is missing. The browser's developer console shows a refused request to /chat/w/... in those cases.
  • WhatsApp messages do not arrive. Check the webhook address and that messages is subscribed (Meta), and that the app secret or auth token in the channel is current: messages with a wrong signature are refused.
  • A reply shows "not sent". The reason is shown with it: an expired access token, or the 24-hour window.