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.