Classic Chat API (CAPI)

On April 28, 2017, Blizzard announced an official API for the classic BNETv1 platform. This is intended to allow bots to easily connect to the platform using secure web sockets instead of needing to emulate the game protocols.

The latest revision of the CAPI protocol (V3) can be found in this document.

The chat API uses UTF-8 encoded JSON over secure websockets.

The connection endpoint is wss://connect-bot.classic.blizzard.com/v1/rpc/chat.

Instead of a username and password, the API requires a special key, which can be obtained by using the /register-bot command from your op or clan channel. The bot's name will be the username it was registered from, in lowercase and prefixed with [B].

Message Header

Messages sent to the server must contain a command, request_id, and payload. They will be returned with the same and optionally a status if an error occurred.

• request_id is a value used to match requests and responses, and should be a unique number not used for any other messages that are awaiting a response.
• payload is additional JSON containing the contents of the message.

An example message will look like this:

{ 
    "command": "Botapichat.ConnectEventRequest",
    "request_id": 1,
    "payload": {
        "channel": "Op BNETDocs"
    }
}

Connection Status Checking (PING/PONG)

The server sends a websocket PING request every 10-15 seconds, which should be responded to immediately with the appropriate PONG. Many websocket libraries will do this automatically. Not responding to these requests will cause you to be disconnected.

Connection Sequence

To connect and start receiving messages, you must send and receive the following messages:

• C->S Botapiauth.AuthenticateRequest (contains the API key)
• S->C Botapiauth.AuthenticateResponse
• C->S Botapichat.ConnectRequest (enters the chat environment)
• S->C Botapichat.ConnectResponse
• S->C Botapichat.UserUpdateEventRequest (contains your username and ID)
• S->C Botapichat.ConnectEventRequest (contains your channel name)
• You will then receive a series of UserUpdateEventRequest messages for each user in the channel, including yourself, and an extra UserUpdateEventRequest giving you the Moderator flag.
• If you are a WarCraft 3 (clan channel) bot you will receive the clan's Message of the Day as a MessageEventRequest with type ServerInfo.

Chat Messages

Chat messages are received with the Botapichat.MessageEventRequest message containing user_id, message, and type.

• user_id is the ID of the user who sent the message. This ID is linked to a username (known as a toon name) in the initial UserUpdateEventRequest messages. The user ID does not appear to be reused when a user leaves the channel.
• type is one of Whisper, Channel, ServerInfo, ServerError, or Emote. The Channel type is used for normal, public messages sent to the channel.

Chat messages are sent with the Botapichat.SendMessageRequest command.

• The payload for this message takes a single item, 'message', containing the sent message.
• Slash-commands such as /help, /whoami, /ban, etc are not supported through this interface. You must use their API equivalents, if available.

For example:

{
    "command": "Botapichat.SendMessageRequest",
    "request_id": 1,
    "payload": {
        "message": "Hello world!"
    }
}

Classic Command Equivalents

Here is a mapping of the classic slash-commands to their API equivalents:

• /me and /emote - Botapichat.SendEmoteRequest
• /w, /m, /msg, and /whisper - Botapichat.SendWhisperRequest (requires the ID of the target user)
• /ban - Botapichat.BanUserRequest (requires the ID of the target user)
• /unban - Botapichat.UnbanUserRequest (the only message to take a username/toon name as the target argument)
• /kick - Botapichat.KickUserRequest (requires the ID of the target user)
• /designate + /resign - Botapichat.SendSetModeratorRequest (requires the ID of the target user)

Limitations

The chat API is in the Alpha state and so has limited functionality. How much of these limitations will be lifted is not known.

• Chat API clients are limited to a single channel and cannot whisper or interact with users outside of this channel. Changing channels is not supported.
• Only one API key is permitted per channel, and must be registered by the channel owner.
• API clients do not have access to friends lists, clan, or game information and functions.
• Many commands, such as /channel, /options, and /away do not have an API equivalent.
• Messages are not supported for bans and kicks.
• You cannot ban a user that is not in the channel.
• You are limited to 3 connections per API key.

Known Bugs

• In the UserUpdateEventRequest message:
  • The flags and attributes field (as documented) are actually sent as flag and attribute.
  • The ProgramId attribute is not sent for all users. It only appears to work on WarCraft 2 and StarCraft users.
  • The Rate, Rank, and Wins attributes do not appear to be implemented.
  • attribute is actually a list of dictionaries, such as 'attribute': [ { 'key': 'ProgramId', 'value': 'W2BN' } ]
• Some messages are not properly UTF-8 encoded if the origin message (on the BNCS side) was not UTF-8.