Skip to main content
A conversation menu («قوائم المحادثة» in the Arabic console) is a page of yours that Tawked Chat shows beside the conversations of one application’s WhatsApp number: a tab beside the conversation on the web, and an item in the conversation’s menu in the phone app, which opens the page full screen. Use it in one of two ways:
  • No code. Put tokens such as {customer_phone} in the link. Tawked fills them with the open conversation’s values before your page opens.
  • Code. Add one script to your page. It hands your page the open conversation: its id, the customer and the agent.
Either way, protect the page with a key so that only your menu opens it.
Menus are added in the Tawked console at tawked.com, inside the application, not in Tawked Chat (chat.tawked.com). Tawked Chat only shows them. A connected app adds its own menus to its customer’s application over the API.

Ask your coding assistant to build a conversation menu page.

Open in Cursor

Add a menu

A menu belongs to the application it is added in, and shows only in the conversations of that application’s WhatsApp number. A business with two applications adds a menu in each one that needs it.
1

Open the Tawked console

Sign in at tawked.com with the phone number of the account’s owner or an admin. This is the Tawked console, not Tawked Chat (chat.tawked.com), where menus cannot be added.
2

Open the application's menus

Choose the application whose conversations should show the menu, then in its sidebar Chat → Conversation menus («المحادثات ← قوائم المحادثة» in Arabic). The address looks like https://tawked.com/en/dashboard/applications/<application id>/chat/menus. The application’s WhatsApp number must be connected to Tawked Chat; until it is, the page says so and Add menu waits.
3

Add the menu

Press Add menu, type the Name your team sees and the Link of your page, with its key. Press a token chip under the link (Customer phone, Customer name, Customer email, Conversation number) to add it to the link. The preview shows the page as your team will see it, with a sample customer.
4

Save and reload Tawked Chat

Press Add menu. Tawked checks whether your site opens inside Tawked Chat and shows the answer in the list’s Status column. Your team sees the new menu after reloading Tawked Chat on the web, or reopening the phone app.
Every change is recorded with who made it. To change a menu, open it from the list, then Save, or Delete menu.

Added by a connected app

A platform you connected to the application, as a connected app, can add its own menus with its credential, under the same rules: you do nothing, and the tab appears once your team reloads Tawked Chat. The list shows such a menu with the app’s name, and you can still edit or delete it like your own. Every change the app makes is recorded in your account under the app’s name. When you disconnect the app, or revoke its key, the menus it added are removed. The app sees only the menus it added, never yours. The same app can also set up the application’s auto-attendant, the menu of tappable choices that answers a new conversation: see Set up the auto-attendant for your client. A token is a name in braces inside the link. Tawked replaces each one with the open conversation’s value.
  • Encoded. Each value is URL-encoded before it goes into the link: +966551234567 becomes %2B966551234567, and an Arabic name becomes percent-encoded UTF-8. Your server decodes it like any query value.
  • Empty when missing. A value the conversation does not have becomes an empty string. Your page must handle ?email= with nothing after it.
  • Path or query. A token can sit in the path or the query: https://crm.example.com/customers/{customer_phone} and https://crm.example.com/search?phone={customer_phone} both work.
  • The agent’s name is not a token. Only the script gives it.
opens, for the sample customer, as
How the values reach the link. A link with a token opens through a short page of Tawked’s first. That page asks Tawked Chat for the open conversation, fills the tokens, and replaces itself with your page in the same tab. If no answer comes after five asks, 1.5 seconds apart, it opens your page with every token empty. The values are those of the conversation open when the menu opened.

Read the open conversation in your page

Load the script, then register a callback. This is a complete page:
TawkedChat.onConversation(callback) calls callback(c) with one object: There are no other fields. Read nothing else from c. When the callback runs
  • The script asks Tawked Chat for the open conversation as soon as you register a callback, then again every 1.5 seconds, five asks in all, and stops at the first answer.
  • The callback runs when the answer arrives. A callback registered after that runs at once with the last conversation.
  • If Tawked Chat sends a different conversation to the same page later, the callback runs again with it. It never runs twice in a row for the same conversation. Write it so that running again replaces what the page shows.
  • Opened outside Tawked Chat, no answer comes and the callback never runs. Show a message instead, as the example does.
  • In the console’s preview, when your site lets https://tawked.com frame it, the callback runs once with the sample customer: Sara (سارة العتيبي), +966551234567, sara@example.com, conversation 1042.
  • An error thrown inside your callback is caught and logged to the browser console; other callbacks still run. You can register more than one.
  • Loading the script twice is harmless: the second copy does nothing.
Which messages the script trusts. It reads a message only when it comes from https://chat.tawked.com, from https://tawked.com (the console’s preview, with the sample customer), from your page’s own origin, or with an empty origin (how the phone app delivers it), and only when it has the shape of a conversation. Everything else is ignored. Its ask carries no data, so it goes to whichever page frames yours.
The script works the same on the web and in the phone app. It works with or without link tokens: a menu whose link has tokens opens your page in the same tab, and the script on that page then talks to Tawked Chat directly.

Find the customer in your system

The phone number is the usual way to find the customer: it is the WhatsApp number the customer writes from. Your page receives it in international format, +966551234567, as the {customer_phone} link token (URL-encoded, %2B966551234567) or as c.customer.phone from the script. Your own system may keep it as 0551234567, 966551234567 or +966 55 123 4567, so bring both sides to the same digits before you compare them:
Keep the same digits on your customers’ records (a column such as phone_digits, indexed), and look the customer up by them:
  • Several matches are normal. A parent who pays for two children, or a family sharing one number, matches more than one record: show them all, with a name on each.
  • No match is normal too. The customer may write from another number than the one you hold, such as a parent’s second phone. Show a short “not found” and a search by name or another number.
  • An empty value. A conversation without a phone gives an empty token or null: show the search instead of an error.
  • For a platform serving many businesses, the key in the link also tells you which business is asking: look the phone up within that business’s customers alone.
  • The phone is a hint, not proof. It chooses which customer to show to your team; for anything that changes data or spends money, check who is acting in your own system.

Opening inside Tawked Chat

On the web, Tawked Chat shows your page in a frame inside https://chat.tawked.com. Your site must allow that:
  • Send Content-Security-Policy: frame-ancestors with https://chat.tawked.com in the list, or
  • send no frame-ancestors at all and no X-Frame-Options: DENY or X-Frame-Options: SAMEORIGIN.
When both headers are present, frame-ancestors decides, as in browsers. X-Frame-Options: ALLOW-FROM is ignored. The header to add:
Add https://tawked.com to the list as well if you want the console’s preview to show your live page, with the sample customer handed to the script; without it the preview shows a drawing of where the page goes.
If your site already sends a Content-Security-Policy, add https://chat.tawked.com to its existing frame-ancestors list rather than sending a second header: every policy a page sends must allow the frame. What the console’s check answers. When you add or save a menu, Tawked reads your link’s headers (with the tokens filled with the sample) and records one of three answers: The check is advice: a menu is saved whatever it answers. The check runs again only when you save the menu, so after changing your site’s headers, open the menu and press Save. In the phone app your page always opens full screen, so the frame rule does not apply there.

Protect your page with a key (basic auth)

A menu page is a page on the internet: without protection, anyone who learns its address can open it and look up your customers. The simplest protection, and the one to use by default, is a long random key made only for this page. It goes in the menu’s link, and your server refuses every request that does not carry it.
1

Make a key

Make a random key of at least 32 bytes, for example with openssl rand -hex 32, and keep it on your server in an environment variable such as TAWKED_MENU_KEY. Use it for this page only: never your Tawked API key, never a key to another service.
2

Put it in the menu's link

In the console, the menu’s Link carries the key, beside any tokens:
3

Check it on every request

Your server compares the key in constant time on the page itself (from the link’s key) and on every call the page makes to your server (from an X-Menu-Key header), and answers 403 otherwise.
In the page, read the key from the link once and send it with every call:
What the key proves, and what it does not So:
  • Show what any of your support team may see. A page that looks up a customer’s orders by phone is a good fit.
  • For anything that changes data or spends money (a refund, a credit, a gift), also check in your own system who is doing it: their own sign-in for that action, or an approval in your back office. Do not trust an agent name or email the page reports about itself.
  • Change the key when someone who had access leaves. Add the new key on your server beside the old one, change the menu’s Link in the console and Save, let your team reload Tawked Chat, then remove the old key.
  • Keep the key from leaking. Send Referrer-Policy: no-referrer on the page (so links from it never carry the key to other sites), load no third-party analytics or chat widgets on it, and keep full request addresses out of your logs. Prefer a site that opens inside the conversation: a page that opens in a new window shows the key in the browser’s address bar and history.
Why not HTTP Basic authentication (https://user:password@…)? Tawked refuses a user name or password in a menu’s link, and browsers do not send credentials written into the address of a page shown in a frame. A 401 sign-in prompt inside the frame does not work either. Use a key in the link instead: it is the same idea, written in a way frames allow.

Security

  • Protect the page. Use a key, or your own sign-in where it works in a frame. An unprotected menu page lets anyone who learns its address look up your customers.
  • The conversation is a hint, not proof. Anyone who has your page’s link can open it with any values, and can send your page a message that looks like a conversation. Use the values to choose which customer to show, never as a signed-in user or as permission to change anything.
  • Only the page’s own key in the link. Your team members who use Tawked Chat can read the menu’s link. Never put a Tawked API key, a password or another service’s key in it, and never in the page’s code.
  • Signing in inside a frame. On the web your page is a frame on another site, so a session cookie needs SameSite=None; Secure to be sent, and browsers that block third-party cookies may not send it at all. Many sign-in pages also refuse to be framed. Where your sign-in cannot work in the frame, keep the key for the page and ask for the person’s own sign-in only for the actions that need it, in a new window.

For AI coding agents

The facts to get right, in one place:
  • Script: <script src="https://tawked.com/js/tawked-chat-menu.js"></script>, then TawkedChat.onConversation(function (c) { ... }). There is no other function.
  • c is exactly { conversation: { id }, customer: { name, phone, email }, agent: { name } }. conversation.id is always set (a number); the other four are strings or null.
  • The callback can run more than once (another conversation) and never runs outside Tawked Chat, except once with a sample customer in the console’s preview. Replace the page’s content each time; show a message if nothing arrives after about 8 seconds.
  • Link tokens: {customer_phone}, {customer_name}, {customer_email}, {conversation_id}. Values are URL-encoded and empty when missing. There is no token for the agent.
  • Link: https:// only, a public domain name (no IP address, no port but 443), at most 1024 characters. To try a page on your machine, use a public HTTPS tunnel. Name: 2 to 30 characters, unique among the application’s menus. At most 10 menus per application.
  • Where: a business’s menu is added by a person in the Tawked console at https://tawked.com (the application → Chat → Conversation menus), by the owner or an admin who manages the team, not in chat.tawked.com. It shows only in the conversations of that application’s WhatsApp number. A connected app adds its own menus to its connection’s application over the API (POST /v1/chat/menus with the app’s key, scope chat:menus; https://docs.tawked.com/integrations/connected-apps#add-a-conversation-menu-for-your-client). A business’s own API key, full access included, answers those calls 403 insufficient_scope.
  • Framing: send Content-Security-Policy: frame-ancestors 'self' https://chat.tawked.com and no X-Frame-Options DENY or SAMEORIGIN. Otherwise the web opens the page in a new window.
  • Protection (always build it): the link carries ?key=<random, at least 32 bytes, only for this page>; the server compares it in constant time (crypto.timingSafeEqual, hash_equals) on the page request and, from an X-Menu-Key header, on every API call the page makes; 403 otherwise. Send Referrer-Policy: no-referrer. No cookie session in the frame. HTTP Basic (user:password@) is refused: use the key.
  • The key proves the request came through the menu, not who the agent is; the customer values stay hints. Show what any support agent may see; for anything that changes data or spends money, check the acting person in the business’s own system. Never a Tawked API key or another service’s key in the link or the page.
  • A business adds its menus in the console, not by a request; only a connected app’s key adds, reads, changes and removes menus over the API, and only the ones its connection made. Give each customer’s menu its own key.
Last modified on October 15, 2026