| 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
print("Got message from", sender, ":", message)
end
end)
local function SendMessage(msg, target)
if not IsInInstance() then
C_ChatInfo.SendAddonMessage(ADDON_PREFIX, msg, "PARTY")
else
end
end
Chat Message Filter
ChatFrame_AddMessageEventFilter("CHAT_MSG_SAY", function(self, event, msg, author, ...)
if msg:find("badword") then
return true
end
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
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.
