wow-api-social-chat

name

wow-api-social-chat

description

Complete reference for WoW Retail Chat, Social, Club/Community, Friend List, Voice Chat, BattleNet, Ping, Social Queue, and Addon Messaging APIs. Covers C_ChatInfo, C_Club, C_ClubFinder, C_FriendList, C_BattleNet, C_VoiceChat, C_SocialRestrictions, C_SocialQueue, C_RecentAllies, C_PingManager, C_TTSSettings, ChatFrame functions, chat filters, addon message system, and 12.0.0 instance restrictions (SendAddonMessage blocked, chat messages may be secret). Use when working with chat output, chat channels, communities, friend lists, voice chat, BattleNet friends, addon communication, social features, or ping system.

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

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.