C_ChatInfo .SendAddonMessage
C_ChatInfo.SendAddonMessage |
+ 8.0.1 / 1.13.2 | ||
C_ChatInfo.SendAddonMessageLogged |
+ 8.0.1 / 1.13.2 | ||
SendAddonMessage |
+ 1.12.0 |
Please use ChatThrottleLib or AceComm – otherwise you will blow up the server. |
Sends a message over an addon comm channel.
result = C_ChatInfo.SendAddonMessage(prefix, message [, chatType, target]) = C_ChatInfo.SendAddonMessageLogged
Arguments
- prefix
- string - Message prefix, can be used as your addon identifier; at most 16 characters.
- message
- string - Text to send, at most 255 characters. All characters (decimal ID 1-255) are permissible except NULL (ASCII 0).
- chatType
- string?
= PARTY
- The addon channel to send to. - target
- string|number? - The player name or custom channel number receiving the message for
"WHISPER"
or"CHANNEL"
chatTypes.
Returns
- result
- Enum.SendAddonMessageResult - Result code indicating if the message has been enqueued by the API for submission. This does not mean that the message has yet been sent, and may still be subject to any server-side throttling.
Chat types
chatType | Retail | Classic | Description |
---|---|---|---|
"PARTY" | Addon message to party members. | ||
"RAID" | Addon message to raid members. If not in a raid group, the message will instead be sent on the PARTY chat type. | ||
"INSTANCE_CHAT" | Addon message to grouped players in instanced content such as dungeons, raids and battlegrounds. | ||
"GUILD" | Addon message to guild members. Prints a "You are not in a guild." system message if you're not in a guild. | ||
"OFFICER" | Addon message to guild officers. | ||
"WHISPER" | Addon message to a player. Only works for players on the same or any connected realms. Use player name as target argument. Prints a "Player is offline." system message if the target is offline. | ||
"CHANNEL" | Addon message to a custom chat channel. Use channel number as target argument. Disabled on Classic to prevent players communicating over custom chat channels. | ||
"SAY"[1] | Addon message to players within /say range. Subject to heavy throttling and certain specific characters are disallowed.[2] | ||
"YELL"[1] | Addon message to players within /yell range. Subject to heavy throttling and certain specific characters are disallowed.[2] |
Details
- Recipients must register a prefix using C_ChatInfo.RegisterAddonMessagePrefix() to receive its messages via CHAT_MSG_ADDON. This prefix can be max 16 characters long and it's recommended to use the addon name if possible so other authors can easily see which addon a registered prefix belongs to.
- Prior to Patch 11.0.0, Blizzard has provided a deprecation wrapper for this API that shifts the result code to the second return position. A forward-compatible way to reliably access the enum return value is to use a negative select index to grab the last return value.
C_ChatInfo.SendAddonMessageLogged
Addons transmitting user-generated content should use this API so recipients can report violations of the Code of Conduct.
- Fires CHAT_MSG_ADDON_LOGGED when receiving messages sent via this function.
- The message has to be plain text for the game masters to read it. Moreover, the messages will silently fail to be sent if it contains an unsupported non-printable character. Some amount of metadata is tolerated, but should be kept as minimal as possible to keep the messages readable for Blizzard's game masters. [3]
- This function has been introduced as a solution to growing issues of harassment and doxxing via addon communications, where players would use addons to send content against the terms of service to other players (roleplaying addons are particularly affected as they offer a free form canvas to share a RP profiles). As regular addon messages are not logged they cannot be seen by game master, they had no way to act upon this content. If you use this function, game masters will be able to check the addon communication logs in case of a report and act upon the content. Users should report addon content that is against the terms of service using Blizzard's support website via the Harassment in addon text option.
Message throttling
Communications on all chat types are subject to a per-prefix throttle. Additionally, if too much data is being sent simultaneously on separate prefixes then the client may be disconnected. For this reason it is strongly recommended to use ChatThrottleLib or AceComm to manage the queueing of messages.
- Each registered prefix is given an allowance of 10 addon messages that can be sent.
- Each message sent on a prefix reduces this allowance by 1.
- If the allowance reaches zero, further attempts to send messages on the same prefix will fail, returning
Enum.SendAddonMessageResult.AddonMessageThrottle
to the caller. - Each prefix regains its allowance at a rate of 1 message per second, up to the original maximum of 10 messages.
- This restriction does not apply to whispers outside of instanced content.
- All numbers provided above are the default values, however these can be dynamically reconfigured by the server at any time.
Example
Whispers yourself an addon message when you login or /reload
local prefix = "SomePrefix123"
local playerName = UnitName("player")
local function OnEvent(self, event, ...)
if event == "CHAT_MSG_ADDON" then
print(event, ...)
elseif event == "PLAYER_ENTERING_WORLD" then
local isLogin, isReload = ...
if isLogin or isReload then
C_ChatInfo.SendAddonMessage(prefix, "You can't see this message", "WHISPER", playerName)
C_ChatInfo.RegisterAddonMessagePrefix(prefix)
C_ChatInfo.SendAddonMessage(prefix, "Hello world!", "WHISPER", playerName)
end
end
end
local f = CreateFrame("Frame")
f:RegisterEvent("CHAT_MSG_ADDON")
f:RegisterEvent("PLAYER_ENTERING_WORLD")
f:SetScript("OnEvent", OnEvent)
Libraries
There is a server-side throttle on in-game addon communication so it's recommended to serialize, compress and encode data before you send them over the addon comms channel.
Serialize:
Compress/Encode:
Comms:
The LibSerialize project page has detailed examples[4] and documentation for using LibSerialize + LibDeflate and AceComm:
-- Dependencies: AceAddon-3.0, AceComm-3.0, LibSerialize, LibDeflate
MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceComm-3.0")
local LibSerialize = LibStub("LibSerialize")
local LibDeflate = LibStub("LibDeflate")
function MyAddon:OnEnable()
self:RegisterComm("MyPrefix")
end
-- With compression (recommended):
function MyAddon:Transmit(data)
local serialized = LibSerialize:Serialize(data)
local compressed = LibDeflate:CompressDeflate(serialized)
local encoded = LibDeflate:EncodeForWoWAddonChannel(compressed)
self:SendCommMessage("MyPrefix", encoded, "WHISPER", UnitName("player"))
end
function MyAddon:OnCommReceived(prefix, payload, distribution, sender)
local decoded = LibDeflate:DecodeForWoWAddonChannel(payload)
if not decoded then return end
local decompressed = LibDeflate:DecompressDeflate(decoded)
if not decompressed then return end
local success, data = LibSerialize:Deserialize(decompressed)
if not success then return end
-- Handle `data`
end
Patch changes
Retail
Patch 10.2.7 (2024-05-07): All chat types are now subject to a per-prefix throttle. Now returns a result code, rather than a boolean.
Patch 10.2.0 (2023-11-07): The "PARTY" chat type now has a per-prefix throttle.
Patch 10.0.2 (2022-11-15): The "RAID" chat type now has a per-prefix throttle as of a hotfix build around Jan 12 2023.
Patch 8.0.1 (2018-07-17): Moved to C_ChatInfo.SendAddonMessage()
and added C_ChatInfo.SendAddonMessageLogged()
Patch 6.0.2 (2014-10-14): Added "CHANNEL" chat type.
Patch 4.1.0 (2011-04-26): Added "OFFICER" chat type. Addons should now register which prefixes they want to receive addon messages for using C_ChatInfo.RegisterAddonMessagePrefix()[5]
Patch 2.1.0 (2007-05-22): Added "WHISPER" chat type was, as servers will begin to rate throttle regular whispers to alleviate spam problems.
Patch 1.12.0 (2006-08-22): Added as SendAddonMessage()
[6]
Classic
Patch 4.4.0 (2024-04-30): All chat types are now subject to a per-prefix throttle. Now returns a result code, rather than a boolean.
Patch 1.13.4 (2020-03-10): Addon comms are now more severely rate throttled (Applied in a hotfix during build 32466 on May 24 2020) [7]
Patch 1.13.3 (2019-12-10): "SAY" and "YELL" are now supported chat types, coincident with removing "CHANNEL" to prevent looking-for-group style addons from proliferating in Classic.[1]
See also
- C_ChatInfo.GetRegisteredAddonMessagePrefixes()
- C_ChatInfo.IsAddonMessagePrefixRegistered()
- BNSendGameData() - Battle.net equivalent.
References
- ^ a b c Kaivax 2019-12-09. [WoW Classic] Patch 1.13.3 Lua API Change.
- ^ a b LenweSaralonde 2019-12-20. String with special characters truncated when sent with C_ChatInfo.SendAddonMessage() over SAY and YELL.
- ^ TheDanW 2018-06-14. #wowuidev IRC chat.
- ^ Ross Nichols. LibSerialize.
- ^ Zarhym 2011-03-12. Patch 4.1: Addon Messages Will Be Filtered.
- ^ slouken 2006-07-12. Re: Upcoming 1.12 changes - Concise List. Archived from the original
- ^ Questie 2020-05-25. QuestieSerializer.lua (LUA) errors #1974.