wow-api-social-chat

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

Function	Returns	Description
`C_ChatInfo.SendAddonMessage(prefix, message, chatType [, target])`	`success`	Send addon message (BLOCKED in instances)
`C_ChatInfo.SendAddonMessageLogged(prefix, message, chatType [, target])`	`success`	Send logged addon message (BLOCKED in instances)
`C_ChatInfo.RegisterAddonMessagePrefix(prefix)`	`success`	Register prefix for CHAT_MSG_ADDON
`C_ChatInfo.IsAddonMessagePrefixRegistered(prefix)`	`isRegistered`	Check if prefix registered
`C_ChatInfo.GetRegisteredAddonMessagePrefixes()`	`prefixes`	All registered prefixes
`C_ChatInfo.GetChannelInfoFromIdentifier(identifier)`	`info`	Channel info by identifier
`C_ChatInfo.GetChannelRuleset(channelIndex)`	`rulesetID`	Channel ruleset
`C_ChatInfo.GetChannelRulesetForChannelID(channelID)`	`rulesetID`	Ruleset by channel ID
`C_ChatInfo.GetChannelShortcut(channelIndex)`	`shortcut`	Channel shortcut
`C_ChatInfo.GetChannelShortcutForChannelID(channelID)`	`shortcut`	Shortcut by channel ID
`C_ChatInfo.GetChatLineSenderGUID(lineID)`	`guid`	GUID of message sender
`C_ChatInfo.GetChatLineSenderName(lineID)`	`name`	Name of message sender
`C_ChatInfo.GetChatLineText(lineID)`	`text`	Message text
`C_ChatInfo.GetChatTypeByID(chatTypeID)`	`chatType`	Chat type string from ID
`C_ChatInfo.GetColorForChatType(chatType)`	`r, g, b`	Default color for chat type
`C_ChatInfo.GetNumActiveChannels()`	`numChannels`	Number of active channels
`C_ChatInfo.GetActiveChannelList()`	`channels`	Active channel list
`C_ChatInfo.IsChannelRegional(chatType)`	`isRegional`	Is channel regional?
`C_ChatInfo.IsChatLineCensored(lineID)`	`isCensored`	Is message censored?
`C_ChatInfo.IsPartyPositionCategory(category)`	`isPartyPosition`	Is party position category?
`C_ChatInfo.IsRegionalServiceAvailable()`	`isAvailable`	Regional service available?
`C_ChatInfo.IsValidChatLine(lineID)`	`isValid`	Is line valid?
`C_ChatInfo.ReplaceIconAndGroupExpressions(message)`	`text`	Expand {rt1}, {skull}, etc.
`C_ChatInfo.ResetDefaultZoneChannels()`	—	Reset zone channels
`C_ChatInfo.SwapChatChannelsByChannelIndex(i1, i2)`	—	Swap channel order

Global Chat Functions

Function	Returns	Description
`SendChatMessage(msg [, chatType [, languageID [, target]]])`	—	Send chat message
`GetNumDisplayChannels()`	`numChannels`	Number of displayed channels
`GetChannelDisplayInfo(index)`	`name, header, collapsed, channelNumber, count, active, category, voiceEnabled, voiceActive`	Channel display info
`GetChannelName(idOrName)`	`id, name, instanceID, isCommChannel`	Channel name/ID lookup
`JoinChannelByName(name [, password [, frameID]])`	`type, name`	Join a channel
`LeaveChannelByName(name)`	—	Leave a channel
`ListChannelByName(name)`	—	List channel members
`GetChatWindowInfo(frameIndex)`	`name, fontSize, r, g, b, alpha, shown, locked, docked, uninteractable`	Chat window info
`SetChatWindowName(frameIndex, name)`	—	Set chat window name
`LoggingChat(enable)`	—	Toggle chat logging
`LoggingCombat(enable)`	—	Toggle combat logging

C_Club — Communities / Clubs

Club Management

Function	Returns	Description
`C_Club.GetSubscribedClubs()`	`clubs`	All joined clubs
`C_Club.GetClubInfo(clubId)`	`info`	Club info
`C_Club.GetClubMembers(clubId [, streamId])`	`members`	Club member list
`C_Club.GetMemberInfo(clubId, memberId)`	`info`	Member info
`C_Club.GetClubStreamNotificationSettings(clubId)`	`settings`	Stream notification settings
`C_Club.CreateClub(name, shortName, description, clubType, avatarId)`	—	Create new club
`C_Club.DestroyClub(clubId)`	—	Destroy a club
`C_Club.EditClub(clubId, name, shortName, description, avatarId, bgColorIndex)`	—	Edit club
`C_Club.LeaveClub(clubId)`	—	Leave a club
`C_Club.AcceptInvitation(clubId)`	—	Accept club invitation
`C_Club.DeclineInvitation(clubId)`	—	Decline club invitation
`C_Club.GetInvitationsForSelf()`	`invitations`	Pending invitations
`C_Club.SendInvitation(clubId, memberId)`	—	Invite to club

Club Streams (Chat Channels within Clubs)

Function	Returns	Description
`C_Club.GetStreams(clubId)`	`streams`	All streams for club
`C_Club.GetStreamInfo(clubId, streamId)`	`info`	Stream info
`C_Club.CreateStream(clubId, name, subject, leadersAndModeratorsOnly)`	—	Create stream
`C_Club.DestroyStream(clubId, streamId)`	—	Remove stream
`C_Club.EditStream(clubId, streamId, name, subject, leadersAndModeratorsOnly)`	—	Edit stream
`C_Club.GetMessagesBefore(clubId, streamId, messageId, count)`	`messages`	Fetch messages before ID
`C_Club.GetMessagesAfter(clubId, streamId, messageId, count)`	`messages`	Fetch messages after ID
`C_Club.GetMessagesInRange(clubId, streamId, oldest, newest)`	`messages`	Messages in range
`C_Club.SendMessage(clubId, streamId, message)`	—	Send message to stream
`C_Club.FocusStream(clubId, streamId)`	—	Focus a stream
`C_Club.UnfocusStream(clubId, streamId)`	—	Unfocus a stream
`C_Club.SetAutoAdvanceStreamViewMarker(clubId, streamId)`	—	Auto-advance view marker

Club Types

Enum	Value	Description
`Enum.ClubType.BattleNet`	0	BattleNet community
`Enum.ClubType.Character`	1	Character community
`Enum.ClubType.Guild`	2	Guild (treated as club)
`Enum.ClubType.Other`	3	Other

C_ClubFinder — Club Finder / Recruitment

Function	Returns	Description
`C_ClubFinder.RequestClubsList(type, isLinkedSearch, searchText, specIDs)`	—	Search for clubs
`C_ClubFinder.GetRecruitingClubInfoFromClubID(clubId)`	`recruitInfo`	Recruitment info for club
`C_ClubFinder.GetTotalMatchingCommunityListSize()`	`size`	Total matching communities
`C_ClubFinder.GetTotalMatchingGuildListSize()`	`size`	Total matching guilds
`C_ClubFinder.RequestPostingInformationFromClubId(clubId)`	—	Request posting info
`C_ClubFinder.PostClub(clubId, minIlvl, minLevel, ...)`	—	Post club listing
`C_ClubFinder.RequestApplicantList(type)`	—	Request applicant list
`C_ClubFinder.GetApplicantInfoList()`	`applicants`	Get applicants
`C_ClubFinder.RespondToApplicant(clubFinderGUID, playerGUID, accepted, ...)`	—	Respond to applicant

C_FriendList — Friends

Function	Returns	Description
`C_FriendList.GetNumFriends()`	`numFriends`	Character friends count
`C_FriendList.GetNumOnlineFriends()`	`numOnline`	Online friends count
`C_FriendList.GetFriendInfoByIndex(index)`	`info`	Friend info by index
`C_FriendList.GetFriendInfoByName(name)`	`info`	Friend info by name
`C_FriendList.GetFriendInfoByGUID(guid)`	`info`	Friend info by GUID
`C_FriendList.AddFriend(name [, notes])`	—	Add friend
`C_FriendList.RemoveFriend(name)`	—	Remove friend
`C_FriendList.SetFriendNotes(name, notes)`	—	Set friend notes
`C_FriendList.AddOrRemoveFriend(name, notes)`	—	Toggle friend
`C_FriendList.IsFriend(guid)`	`isFriend`	Is GUID a friend?
`C_FriendList.AddIgnore(name)`	—	Add to ignore list
`C_FriendList.DelIgnore(name)`	—	Remove from ignore list
`C_FriendList.GetNumIgnores()`	`numIgnores`	Ignore list count
`C_FriendList.GetIgnoreName(index)`	`name`	Ignored player name
`C_FriendList.IsIgnored(name)`	`isIgnored`	Is player ignored?
`C_FriendList.IsIgnoredByGUID(guid)`	`isIgnored`	Is GUID ignored?
`C_FriendList.ShowFriends()`	—	Refresh friends list
`C_FriendList.GetSelectedFriend()`	`index`	Selected friend index
`C_FriendList.SetSelectedFriend(index)`	—	Select friend

C_BattleNet — BattleNet Friends

Function	Returns	Description
`C_BattleNet.GetFriendAccountInfo(index)`	`accountInfo`	BNet friend account info
`C_BattleNet.GetFriendGameAccountInfo(index, gameAccountIndex)`	`gameAccountInfo`	Game account info
`C_BattleNet.GetFriendNumGameAccounts(index)`	`numGameAccounts`	Game accounts for friend
`C_BattleNet.GetAccountInfoByID(bnetAccountID)`	`accountInfo`	Account info by ID
`C_BattleNet.GetAccountInfoByGUID(guid)`	`accountInfo`	Account info by GUID
`C_BattleNet.GetGameAccountInfoByID(gameAccountID)`	`gameAccountInfo`	Game account info
`C_BattleNet.GetGameAccountInfoByGUID(guid)`	`gameAccountInfo`	Game account by GUID
`BNGetNumFriends()`	`numFriends, numOnline`	BNet friend count
`BNGetNumFriendInvites()`	`numInvites`	Pending BNet invites
`BNSendWhisper(bnetAccountID, message)`	—	Send BNet whisper
`BNInviteFriend(bnetAccountID)`	—	Invite to group
`BNRequestInviteFriend(presenceID)`	—	Request BNet friend add
`BNRemoveFriend(bnetAccountID)`	—	Remove BNet friend
`BNSetFriendNote(bnetAccountID, note)`	—	Set friend note
`BNSetCustomMessage(message)`	—	Set BNet status message
`BNConnected()`	`isConnected`	Connected to BNet?

C_VoiceChat — Voice Chat

Function	Returns	Description
`C_VoiceChat.GetActiveChannelID()`	`channelID`	Active voice channel
`C_VoiceChat.GetChannel(channelID)`	`channel`	Channel info
`C_VoiceChat.GetChannelForChannelType(channelType)`	`channel`	Channel by type
`C_VoiceChat.GetChannelForCommunityStream(clubId, streamId)`	`channel`	Club voice channel
`C_VoiceChat.GetMasterVolumeScale()`	`scale`	Master volume
`C_VoiceChat.SetMasterVolumeScale(scale)`	—	Set master volume
`C_VoiceChat.GetInputVolume()`	`volume`	Mic volume
`C_VoiceChat.SetInputVolume(volume)`	—	Set mic volume
`C_VoiceChat.GetOutputVolume()`	`volume`	Speaker volume
`C_VoiceChat.SetOutputVolume(volume)`	—	Set speaker volume
`C_VoiceChat.IsMuted()`	`isMuted`	Is muted?
`C_VoiceChat.SetMuted(muted)`	—	Set mute
`C_VoiceChat.IsDeafened()`	`isDeafened`	Is deafened?
`C_VoiceChat.SetDeafened(deafened)`	—	Set deafen
`C_VoiceChat.IsSilenced()`	`isSilenced`	Is silenced (by Blizzard)?
`C_VoiceChat.ActivateChannel(channelID)`	—	Activate voice channel
`C_VoiceChat.DeactivateChannel(channelID)`	—	Deactivate voice channel
`C_VoiceChat.IsLoggedIn()`	`isLoggedIn`	Voice chat logged in?
`C_VoiceChat.Login()`	—	Log in to voice chat
`C_VoiceChat.Logout()`	—	Log out of voice chat
`C_VoiceChat.GetMemberName(memberID, channelID)`	`name`	Voice member name
`C_VoiceChat.GetMemberVolume(memberID, channelID)`	`volume`	Member volume
`C_VoiceChat.SetMemberVolume(memberID, channelID, volume)`	—	Set member volume
`C_VoiceChat.IsMemberMuted(memberID, channelID)`	`isMuted`	Is member muted?
`C_VoiceChat.SetMemberMuted(memberID, channelID, muted)`	—	Mute member

C_SocialRestrictions

Function	Returns	Description
`C_SocialRestrictions.IsChatDisabled()`	`isDisabled`	Is chat restricted?
`C_SocialRestrictions.IsMuted()`	`isMuted`	Is player muted?
`C_SocialRestrictions.IsSilenced()`	`isSilenced`	Is player silenced?
`C_SocialRestrictions.IsSquelched()`	`isSquelched`	Is player squelched?

C_SocialQueue — Social Queue

Function	Returns	Description
`C_SocialQueue.GetAllGroups()`	`groups`	All social queue groups
`C_SocialQueue.GetGroupInfo(guid)`	`info`	Group queue info
`C_SocialQueue.GetGroupMembers(guid)`	`members`	Group member list
`C_SocialQueue.GetGroupQueues(guid)`	`queues`	Group queues

C_RecentAllies

Function	Returns	Description
`C_RecentAllies.GetRecentAllies()`	`allies`	Recent group allies

C_PingManager — Ping System

Function	Returns	Description
`C_PingManager.GetPingTypeFromUIMouseButton(button)`	`pingType`	Ping type from mouse button
`C_PingManager.TogglePingListener(enabled)`	—	Toggle ping listening

C_TTSSettings — Text-to-Speech

Function	Returns	Description
`C_TTSSettings.GetChatTypeEnabled(chatType)`	`enabled`	Is TTS enabled for chat type?
`C_TTSSettings.SetChatTypeEnabled(chatType, enabled)`	—	Toggle TTS for chat type
`C_TTSSettings.GetSetting(setting)`	`value`	Get TTS setting
`C_TTSSettings.SetSetting(setting, value)`	—	Set TTS setting
`C_TTSSettings.GetVoiceOptionID(voiceType)`	`optionID`	Get voice option

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

Event	Payload	Description
`CHAT_MSG_SAY`	msg, author, language, channelString, target, flags, ...	/say message
`CHAT_MSG_YELL`	msg, author, ...	/yell message
`CHAT_MSG_PARTY`	msg, author, ...	Party message
`CHAT_MSG_PARTY_LEADER`	msg, author, ...	Party leader message
`CHAT_MSG_RAID`	msg, author, ...	Raid message
`CHAT_MSG_RAID_LEADER`	msg, author, ...	Raid leader message
`CHAT_MSG_GUILD`	msg, author, ...	Guild message
`CHAT_MSG_OFFICER`	msg, author, ...	Guild officer message
`CHAT_MSG_WHISPER`	msg, author, ...	Incoming whisper
`CHAT_MSG_WHISPER_INFORM`	msg, target, ...	Outgoing whisper
`CHAT_MSG_BN_WHISPER`	msg, author, ...	BNet whisper received
`CHAT_MSG_BN_WHISPER_INFORM`	msg, target, ...	BNet whisper sent
`CHAT_MSG_CHANNEL`	msg, author, language, channelString, target, flags, zoneChannelID, channelIndex, channelBaseName, ...	Channel message
`CHAT_MSG_ADDON`	prefix, message, channel, sender	Addon message received
`CHAT_MSG_ADDON_LOGGED`	prefix, message, channel, sender	Logged addon message
`CHAT_MSG_SYSTEM`	msg	System message
`CHAT_MSG_EMOTE`	msg, author, ...	Emote message
`CHAT_MSG_TEXT_EMOTE`	msg, author, ...	/emote text
`FRIENDLIST_UPDATE`	—	Friends list changed
`BN_FRIEND_LIST_SIZE_CHANGED`	—	BNet list changed
`BN_FRIEND_INFO_CHANGED`	bnetAccountID	BNet friend updated
`BN_CONNECTED`	—	Connected to BNet
`BN_DISCONNECTED`	—	Disconnected from BNet
`CLUB_ADDED`	clubId	Joined a club
`CLUB_REMOVED`	clubId	Left a club
`CLUB_UPDATED`	clubId	Club info updated
`CLUB_MESSAGE_ADDED`	clubId, streamId, messageId	New club message
`CLUB_MEMBER_ADDED`	clubId, memberId	Member joined club
`CLUB_MEMBER_REMOVED`	clubId, memberId	Member left club
`CLUB_MEMBER_UPDATED`	clubId, memberId	Member info updated
`VOICE_CHAT_CHANNEL_ACTIVATED`	channelID	Voice channel activated
`VOICE_CHAT_CHANNEL_DEACTIVATED`	channelID	Voice channel deactivated
`VOICE_CHAT_CHANNEL_MEMBER_ADDED`	memberID, channelID	Member joined voice
`VOICE_CHAT_CHANNEL_MEMBER_REMOVED`	memberID, channelID	Left voice channel

Gotchas & Restrictions

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

About this skill

CRITICAL: 12.0.0 Instance Restrictions

Scope

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

Chat Message Filter

Enumerate Friends

Key Events

Gotchas & Restrictions