Goal

Get chat working end-to-end for a MAM Suite mobile app. After this recipe, signed-in users will see a Chat tab bar button, the unread message badge will populate on the next phone-data request, and the standard chat surfaces (thread list, individual conversation) will be reachable from the app.

This recipe covers the activation step and a smoke test only. To configure colors and styling, see Recipe: Style chat bubbles and behavior. To configure who answers admin/support messages, see Recipe: Configure the admin support chat.

Prerequisites

• WordPress admin access
• MAM Suite installed, with mam-main (≥ 1.9.1) activated under Mobile App Manager → Software
• A MAM Suite plugin entitlement that includes mam-chat-manager
• At least two test app users — chat is a two-party feature, so you cannot smoke-test it from a single account

If mam-chat-manager is not yet listed under Software, install it the same way as any other MAM Suite feature plugin. Plugin: mam-chat-manager describes the activation and entitlement gate in more detail.

How activation works

When mam-chat-manager loads:

1. It checks the mam_plugin_entitlement filter for the mam-chat-manager slug. If the entitlement is missing or blocked, the plugin returns silently — no hooks register, no admin pages appear.
2. It registers mam_has_chat_manager as __return_true, which is how other plugins detect that chat is available.
3. It hooks mam_get_phone_data_before_send so every phone-data response gets has_chat, ajaxurl, msg_nonce, and the unread/thread counts for the current user.
4. It registers the eight chat API actions (mam_chat_send_message, mam_chat_get_messages, mam_chat_get_message_by_id, mam_chat_update_read_message, mam_chat_hide_messages, mam_wc_chat_flag_user, mam_wc_chat_block_user, mam_wc_chat_un_block_user) on the mam_main_ajax dispatcher.
5. It contributes a Chat tab-bar button definition through mam_main_add_tab_bar_item_chat.

There is no global on/off setting to flip after activation. The plugin is on whenever its entitlement is present.

Steps

1. Activate the plugin

Go to Mobile App Manager → Software. Find Mobile App Manager Chat Manager in the list. Choose Install and Activate from the action dropdown and click Apply.

After the page reloads, confirm:

• The plugin’s row shows it as activated
• A Chat Settings entry appears in the Mobile App Manager sidebar
• A Chat History entry appears in the same sidebar

If those two admin pages don’t appear, the entitlement check is most likely failing. Check tsl_debug_items for mam_plugin_entitlement traces.

2. Place the chat tab bar button (optional but recommended)

Most apps want the standard chat thread list reachable from the tab bar. Open Mobile App Manager → App Settings → Tab Bar for the role you’re configuring and add the Chat entry. The icon, title, and action come from the plugin (black_chat, Chat, do_chat); the order is yours to set.

If your app uses a different navigation pattern (left menu, home screen icons), drop the mam_standard_chat content type into the appropriate slot instead.

3. Smoke-test as two users

Sign in to the mobile app as User A and:

1. Confirm the Chat tab bar button is visible.
2. Open it. Expect an empty thread list — that’s correct on a fresh install.

Sign in to the same app on a second device as User B and:

1. Open a listing or product detail screen that’s been wired up with Hook: mam_add_chat_to_detail (or, lacking that, the admin support chat — see Recipe: Configure the admin support chat).
2. Tap the message button and send a test message to User A.

Switch back to User A:

1. Pull-to-refresh or background-and-foreground the app.
2. The Chat tab bar button should now show an unread badge.
3. Opening Chat should show one thread with User B and the test message.

If the unread badge doesn’t appear, see Verification below for the most common cause.

4. Verify the unread count is correct

Open a fresh request to the phone-data endpoint (the app does this automatically on every refresh). The response should include:

{
  "has_chat": "yes",
  "ajaxurl": "https://yoursite/wp-admin/admin-ajax.php",
  "msg_nonce": "abc123…",
  "messages_unread": "1",
  "messages": "1"
}

messages_unread and messages are stringified integers. They reflect what the currently authenticated user sees, so they will differ across sessions.

Variations

Hide the chat tab bar globally for a role

The tab bar button definition runs through mam_main_skip_tab_bar_button before being added. Subscribe to that filter (in mam-main‘s tab-bar pipeline) to hide the chat button for specific roles or feature flags. The chat surfaces themselves remain available to any nav element that loads the mam_standard_chat or mam_admin_chat content type.

Move chat into the left menu instead of the tab bar

Drop into Mobile App Manager → App Settings → Left Menu for the role and add a menu item with content type Standard Chat. The phone-data pipeline cleans up any vc_type == 'chat' menu item that lacks a populated data array, so once you save the menu, the entry will only appear if it actually resolves to a thread list.

Verification

This article was last verified against:

• Plugin: mam-chat-manager v2.0.0
• mam-main (provides the entitlement, AJAX dispatcher, and tab bar pipeline)
• Source: mam-chat-manager.php, includes/mam_chat_manager_phone_data.php

Re-verify whenever the entitlement gate in mam_chat_manager::__construct() changes, the keys written by mam_chat_manager_phone_data::manage_phone_data() change, or the mam_main_add_tab_bar_item_chat slot is renamed.

Common gotchas

• Unread badge stays at 0 after a test message. The phone-data unread count uses the mam_thread_participant postmeta index — if a thread was created before the participant index was introduced, that thread’s unread messages will not be counted. Send the test message after both participants exist to ensure the index is populated; or run a one-off rebuild via Hook: mam_chat_add_to_chat_thread (which re-runs the index step).
• messages_unread is a string, not an int. Mobile clients that compare against 0 rather than "0" will mis-render the badge. This is part of the frozen mobile contract; it cannot be changed.
• Chat menu items disappearing. The phone-data pipeline runs clean_chat_menus() over homePageIcons and left_menu, dropping any vc_type=chat entry whose data is empty or non-array. If you add a chat menu item and it vanishes on the next phone-data response, the source content class isn’t returning a populated data array.

Related articles

• Plugin: mam-chat-manager
• Recipe: Style chat bubbles and behavior
• Recipe: Configure the admin support chat
• Hook: mam_add_chat_to_detail
• Hook: mam_chat_add_to_chat_thread

Metadata