Developer notes

Overview · Installation · Configuration · Usage · FAQ

Technical reference for developers who customize WhatsApp Chat Button.

Add-on identity

Item	Value
Add-on id	kv_whatsapp_chat_button
Function prefix	fn_kv_whatsapp_chat_button_
Language variables	kv_whatsapp_chat_button.*
CSS scope	.kv-whatsapp-chat-button, .kv-wcb*
PHP namespace	Tygh\Addons\KvWhatsappChatButton
Privileges	view_kv_wcb, manage_kv_wcb (group “WhatsApp chat”, section Marketing)

How it works

1. dispatch_before_display (storefront, full pages only) builds the configuration of the current page with Storefront::build(): page type (from controller and mode), the active agents with their weekly hours and time zones, the store channels, the product (on products.view), the vendor (Multi-Vendor product and vendor pages), the cart summary (cart and checkout pages only) and the texts. It returns nothing when the add-on is switched off, unlicensed or no contact is set.
2. The template hook index:footer prints an empty root <div id="kv-wcb"> with CSS variables and window.kvWcbConfig = {...}.
3. js/addons/kv_whatsapp_chat_button/func.js builds the button, the panel and the greeting, inserts Ask about this product after .ty-product-block__button (fallback: the anchor printed by products:product_detail_bottom) and the cart help link, evaluates the online states in the browser and creates the links.
4. A click sends a beacon to index.php?dispatch=kv_whatsapp_chat_button.click&ch=<channel>&s=<source>[&a=<agent_id>|&v=<vendor_id>] (GET, fetch with keepalive, credentials omitted). The controller validates the channel, the source, the agent (active, same channel, same storefront) and the vendor number, adds 1 to the day’s counter and answers 204.

Full page cache (4.21)

• On cacheable pages the configuration depends only on the page, the settings and the agents, never on the session, so every guest gets the same HTML. Online states are computed in the browser from the static weekly schedule, so a cached page never shows a stale “online”.
• The visitor’s cart is read only on checkout.cart / checkout.checkout, which are never cached; after cart changes the script reloads the summary from kv_whatsapp_chat_button.cart_summary (JSON, Cache-Control: no-store).
• The click and cart_summary dispatches are not in the full page cache list, so they always reach PHP. The add-on writes nothing to storage_data from the storefront.
• The product page anchor is static per product, so the block cache of the product page needs no extra key.

Hooks used

Hook	Where	What
dispatch_before_display	fn.control.php	storefront configuration (see above)
delete_company	fn.companies.php	removes the vendor number and the click counts of a deleted vendor (Ultimate: also the storefront’s own agents)
init_templater_post		self-healing upgrade synchronizer (only while an upgrade is pending)
index:footer (template, post)	storefront	root element and configuration
products:product_detail_bottom (template, post)	storefront	anchor of the Ask about this product button
index:scripts, index:styles (template, post)	storefront	script and styles
index:styles (template, post)	admin	admin styles

Storefront script API and events

The script listens to ce.commoninit (re-places the product button and the cart link after AJAX page updates) and ce.ajaxdone (refreshes the cart summary).

Event	Where	Detail
kv:chat-click	document (CustomEvent)	{chat_channel, chat_agent, chat_source, chat_online, page_type}
kv_chat_open, kv_chat_click	window.dataLayer / gtag / kvGa4.send	see Usage

Example: count chat clicks in your own script.

document.addEventListener('kv:chat-click', function (e) {
    console.log('chat opened', e.detail.chat_channel, e.detail.chat_source);
});

The cookie consent integration reads window.kvConsent.get(category) and listens to kvConsent.on('change', ...) (our Cookie Consent add-on).

Database tables

Table	Content
?:kv_wcb_agents	agent_id, company_id (Ultimate storefront; 0 = all), status, position, channel, contact (normalised: digits for WhatsApp, + and digits for phone/SMS, page or user name for Messenger/Telegram), name, role, message, timezone, hours (JSON {"1":["09:00","17:00"],...}, 0 = Sunday; empty = always available), updated_at. Photos are core image pairs with object type kv_wcb_agent.
?:kv_wcb_vendors	company_id, status, whatsapp, message, timezone, hours, updated_at (Multi-Vendor vendor numbers)
?:kv_wcb_stats	stat_date, company_id (Ultimate storefront or Multi-Vendor vendor), channel, agent_id, source, clicks

All tables are created with CREATE TABLE IF NOT EXISTS and dropped on uninstall.

Template overrides

The storefront templates are tiny (the script builds the UI). To change the look, override the styles in your theme (all selectors start with .kv-wcb), or set the colours, size and position in the settings. CSS variables on #kv-wcb: --kv-wcb-color, --kv-wcb-text, --kv-wcb-size, --kv-wcb-x, --kv-wcb-y, --kv-wcb-m. Do not edit the add-on’s files; they are replaced on update.

File map

app/addons/kv_whatsapp_chat_button/
  addon.xml  init.php  func.php
  controllers/backend/kv_whatsapp_chat_button.php        agents manage/update/delete/status, stats, vendors, vendor
  controllers/backend/kv_whatsapp_chat_button_license.php
  controllers/frontend/kv_whatsapp_chat_button.php       click (204), cart_summary (JSON)
  schemas/menu/{menu,menu_vendor,actions}.post.php
  schemas/permissions/{admin,vendor_multivendor}.post.php
  Tygh/Addons/KvWhatsappChatButton/{Config,Agents,Schedule,Stats,Vendors,Storefront}.php
  Tygh/Addons/KvWhatsappChatButton/License/*  Tygh/Addons/KvWhatsappChatButton/Upgrade/Synchronizer.php
design/backend/templates/addons/kv_whatsapp_chat_button/
  views/kv_whatsapp_chat_button/{manage,update,stats,vendors,vendor}.tpl  components/{nav,hours}.tpl
  hooks/index/styles.post.tpl  hooks/addons/*  license/*
design/backend/css/addons/kv_whatsapp_chat_button/{styles,license}.less
var/themes_repository/responsive/templates/addons/kv_whatsapp_chat_button/
  hooks/index/{footer,scripts,styles}.post.tpl  hooks/products/product_detail_bottom.post.tpl
var/themes_repository/responsive/css/addons/kv_whatsapp_chat_button/styles.less
js/addons/kv_whatsapp_chat_button/func.js
var/langs/en/addons/kv_whatsapp_chat_button.po

Storefront templates and styles ship for the Responsive theme and reach Bright, Nova and other child themes by inheritance.