Automated updating of API pages at this location, to reflect patch changes, has ceased from 10.1.7 onwards.

Please use ChatThrottleLib or AceComm – otherwise you will blow up the server.

Sends a message over an addon comm channel.

success = 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

success

boolean - True if the message was successfully sent. This is regardless of being registered to its prefix or any server-side throttling.

Chat types

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.

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.

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:

• LibSerialize (stats)
• AceSerializer

Compress/Encode:

• LibDeflate (stats)
• LibCompress (stats)

Comms:

• ChatThrottleLib (docs, stats)
• AceComm

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 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 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