Social & Chat API (Retail — Patch 12.0.0)

Comprehensive reference for chat, social, clubs/communities, friends, voice, BattleNet, and related APIs.

Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only.

CRITICAL: 12.0.0 Instance Restrictions

• •SendAddonMessage() is BLOCKED inside instances (dungeons, raids, BGs, arenas)
• •Chat messages in instances may be secret values (KStrings)
• •Addon communication must use alternative patterns outside instances
• •C_ChatInfo.SendAddonMessage() and C_ChatInfo.SendAddonMessageLogged() throw errors in instances

Scope

• •C_ChatInfo — Chat system, channels, addon messages
• •Chat Frame Functions — SendChatMessage, chat filters, chat bubbles
• •C_Club — Communities / clubs system
• •C_ClubFinder — Club finder / recruitment
• •C_FriendList — Friends list management
• •C_BattleNet — BattleNet friends, presence, game accounts
• •C_VoiceChat — Voice chat system
• •C_SocialRestrictions — Social restriction checks
• •C_SocialQueue — Social queue system
• •C_RecentAllies — Recent allies tracking
• •C_PingManager — In-world ping system
• •C_TTSSettings — Text-to-speech settings

C_ChatInfo — Chat System

Key Functions

Global Chat Functions

C_Club — Communities / Clubs

Club Management

Club Streams (Chat Channels within Clubs)

Club Types

C_ClubFinder — Club Finder / Recruitment

C_FriendList — Friends

C_BattleNet — BattleNet Friends

C_VoiceChat — Voice Chat

C_SocialRestrictions

C_SocialQueue — Social Queue

C_RecentAllies

C_PingManager — Ping System

C_TTSSettings — Text-to-Speech

Common Patterns

Register and Handle Addon Messages

local ADDON_PREFIX = "MyAddon"
C_ChatInfo.RegisterAddonMessagePrefix(ADDON_PREFIX)

local frame = CreateFrame("Frame")
frame:RegisterEvent("CHAT_MSG_ADDON")
frame:SetScript("OnEvent", function(self, event, prefix, message, channel, sender)
    if prefix == ADDON_PREFIX then
        -- Process addon message
        print("Got message from", sender, ":", message)
    end
end)

-- Send message (FAILS in instances in 12.0.0!)
local function SendMessage(msg, target)
    if not IsInInstance() then
        C_ChatInfo.SendAddonMessage(ADDON_PREFIX, msg, "PARTY")
    else
        -- In-instance: cannot send addon messages
        -- Consider using encounter events or built-in APIs instead
    end
end

Chat Message Filter

-- Filter chat messages to modify or suppress them
ChatFrame_AddMessageEventFilter("CHAT_MSG_SAY", function(self, event, msg, author, ...)
    if msg:find("badword") then
        return true -- suppress the message
    end
    -- Modify the message
    local newMsg = msg:gsub("hello", "|cff00ff00hello|r")
    return false, newMsg, author, ...
end)

Enumerate Friends

local function GetOnlineFriends()
    local friends = {}
    local numFriends = C_FriendList.GetNumFriends()
    for i = 1, numFriends do
        local info = C_FriendList.GetFriendInfoByIndex(i)
        if info and info.connected then
            table.insert(friends, info)
        end
    end
    -- Also check BNet friends
    local numBNet, numOnlineBNet = BNGetNumFriends()
    for i = 1, numBNet do
        local acctInfo = C_BattleNet.GetFriendAccountInfo(i)
        if acctInfo and acctInfo.gameAccountInfo and acctInfo.gameAccountInfo.isOnline then
            table.insert(friends, acctInfo)
        end
    end
    return friends
end

Key Events

Gotchas & Restrictions

1. •SendAddonMessage BLOCKED in instances — C_ChatInfo.SendAddonMessage() and SendAddonMessageLogged() throw errors inside dungeons, raids, BGs, and arenas in 12.0.0.
2. •Chat messages may be secret — In instances, chat message content from other players may be KStrings / secret values.
3. •Addon prefix limit — Maximum 16 characters for addon message prefixes.
4. •Addon message size limit — Maximum 255 characters per addon message.
5. •Chat throttle — SendChatMessage() is throttled. Sending too fast will disconnect you.
6. •Hardware event required — Some chat functions require a hardware event (mouse click/key press) to execute.
7. •BNet friend list — BNGetFriendInfo() is deprecated. Use C_BattleNet.GetFriendAccountInfo().
8. •Club type Guild — Guilds are treated as clubs with Enum.ClubType.Guild. Use C_Club to interact with guild chat streams.
9. •Voice chat login — Voice chat requires explicit login. Check C_VoiceChat.IsLoggedIn() before operations.
10. •Chat filters — ChatFrame_AddMessageEventFilter filters operate on ALL instances of the event across all chat frames.