Simple Ajax Chat Pro (SAC Pro) provides two shortcodes. The first shortcode is the main shortcode, [sacpro], which displays a chat box on any post or page. The [sacpro] shortcode accepts many attributes for customizing features. The other shortcode, [sacpro_online], displays a “current online users” widget, and may be customized with a few attributes.

Contents

Shortcode: Display chat form

To display a chat box on any post or page, use the [sacpro] shortcode. This shortcode accepts a number of attributes for customizing functionality and features. Before jumping into the attributes, here are some important points when working with this shortcode:

  • Add only ONE form per post or page (multiple forms per post/page not supported).
  • Make sure the shortcode is written on one line, with no line breaks or returns in the code.
  • Use the plain-text block/editor (not RTE/Visual block/editor) when adding and editing shortcodes.
Attributes

Here are the available attributes for the [sacpro] shortcode.

Attribute Description Required?
form_id Specifies the form ID. Accepts any alphanumeric value. Yes
welcome_name Specifies the name used for the first (automatic) “welcome” chat. No
welcome_text Specifies the message used for the first (automatic) “welcome” chat. No
chat_order Sets the order in which chat messages are displayed. Accepts asc or desc. No
field_order Reverses display of chat form and chat box. Accepts true or false. No
small_input Display single-line input for chat messages. Accepts true or false. No
disable_scroll Disables automatic scrolling for new chat messages. Accepts true or false. No
chat_theme Determines the chat theme/styles. Accepts classic, dark, micro, giant, hero, synthetic, custom, or disable. No
max_chats_display Maximum number of chats to display in the chat box. No
max_chats_saved Maximum number of chats to save in the database. No
max_chars_name Maximum number of characters allowed in chat user names. No
max_chars_text Maximum number of characters allowed in chat messages. No
max_chars_url Maximum number of characters allowed in user URLs. No
max_users Maximum number of users allowed in the chat room. Accepts any number or unlimited (default). No
read_only Sets the chat box to “read-only” mode for non-logged users. So they can look but not add chats. Accepts true or false. No
read_only_message The message displayed to non-logged users when in “read-only” mode. No
logged_only Require the user to be logged in to access the chat box. Accepts true or false. No
logged_only_message The message displayed to non-logged users when login is required. No
user_name Determines which value to use for the chat user name. Accepts user_defined, auto_gen, user_login, nice_name, first_last, nick_name, or display_name. No
name_prefix Defines the prefix used for randomly generated user names. Default value is guest_. No
user_url Determines which value to use for the user URL. Accepts user_defined, profile_url, edit_url, archive_url, or disable_url. No
user_avatar Display an avatar (for logged-in users) next to user names in the chat box. The default avatar for visitors (not logged in) is the generic “person” icon. Accepts true or false. No
email_alerts Enables email alerts for new chat messages. Accepts any valid email address (separate multiple addresses with a comma), or false to disable alerts. No
display_meta Display the user role (for logged-in users) next to the user name. The default role for visitors (not logged in) is “visitor”. Accepts true or false. No
emoji_picker Display the emoji picker. Accepts true or false. No
private_chat Make it a private chat session. Accepts a comma-separated list of allowed user names, or false for public chat. No
auto_clear Enable automatic clearing/resetting of all chat messages. Accepts one_week, three_days, one_day, eight_hours, sixty_minutes, thirty_minutes, three_minutes, sixty_seconds, or null (to disable). No
auto_clear_alert Send an “auto-clear” email alert to one email address. Accepts one valid email address. No
Important: The [sacpro] shortcode can be used only once per page.

Learn more about the [sacpro] shortcode in the SAC Pro Quick Start Guide.

Shortcode: Display number of chat users

To display an “online users” widget on any post or page, use the [sacpro_online] shortcode. When added to your page, this shortcode displays a customizable widget that shows the active (online) status for chat users. Here is a screenshot:

Screenshot of online-users widgetScreenshot of the online-users widget

The online-users shortcode accepts the following attributes:

form_id

The form_id attribute is the only required attribute for this shortcode. It accepts any valid form ID. Important: make sure to use the correct value for the form_id attribute. It must match the form ID for your chat form. Once you’ve got that you’re all set.

style

The style attribute accepts one of the following values:

  • online_list — displays online status for any users active in the past 10 minutes (list format)
  • online_div — displays online status for any users active in the past 10 minutes (<div> format)
  • status_list — displays online status of all chat users (list format)
  • status_div — displays online status of all chat users (<div> format)
  • number_active — displays the number of active chat users (learn more)
display

The display attribute accepts one of the following values:

  • admin — display the widget to administrators (admins) only
  • all — display the widget to all users (default)
reset

The reset attribute does one thing: resets the online-users widget. To reset the widget for any form, include form_id and reset, like so:

[sacpro_online form_id="123" reset="true"]

The reset attribute is useful after making changes to form configuration. For example, if you change the user_name for your form, like changing from display_name to nickname for example. After making such changes, the form will continue to display the display_name for any existing users. so to get the new names to show, you can reset the chat user-name cache. This can be done by adding the reset="true" attribute to the shortcode.

Tip: To reset the cache of user names globally (for all forms), visit the plugin’s General settings and click “Reset Users”.
Important: The [sacpro_online] shortcode can be used only once per page.

Learn more about the [sacpro_online] shortcode.

Shortcode: Display number of chat messages

To display the current (live) number of chat messages, add the following shortcode to your post or page:

[sacpro_count form_id="WelcomeChat"]

Replace WelcomeChat with your actual form ID.

Important: In order for the shortcode to work, a chat form (with the same ID) must be included on the page. If the chat form does not exist on the page, the shortcode will not work. So for example this will work beautifully:

[sacpro form_id="WelcomeChat"]       // displays the chat form
[sacpro_count form_id="WelcomeChat"] // displays the message count

Notice the form_id attributes match with the same value. Perfect.

Important: The [sacpro_count] shortcode can be used only once per page.

Learn more about the [sacpro_count] shortcode.