The JOIN command indicates that the client wants to join one or more channels. It acts as a request, the server then checks whether or not the user can join those channels, and responds appropriately.


JOIN <channel>{,<channel>} [<key>{,<key>}]
JOIN 0
  • <channel>: Name of the channel(s) to join, separated by commas.
  • <key>: Optional key (password) for each joined channel, matching the list of given channels.

Servers process the parameters of this command together. For example, the first <channel> uses the first <key>, the second uses the second key, and so on.

A JOIN message may also be sent from the server to indicate that someone has joined a channel. In this case, the <prefix> indicates the user that’s joined. If a user’s JOIN command is successful, they receive one of these messages. In addition, all other clients also receive a JOIN message. For example, if dan and alice are on the channel #toast, and barry joins #toast, then dan and alice will receive a JOIN message indicating that barry has joined the channel.

Whether or not the join request succeeds depends on the channel modes currently set. The key, client limit, ban/exemption, invite-only/exemption, and other channel modes can prevent clients from joining a given channel.

If a user’s JOIN command is successful, the server:

  • Sends them a JOIN message described above.
  • May send a MODE message with the current channel’s modes.
  • Sends them RPL_TOPIC and RPL_TOPICTIME numerics if the channel has a topic set (if the topic is not set, the user is sent no numerics).
  • Sends them one or more RPL_NAMREPLY numerics (which also contain the name of the user that’s joining).

The examples illustrate some full channel join bursts.

While a user is joined to a channel, they receive all status messages related to that channel including new JOIN, PART, KICK, and MODE messages. They also receive all PRIVMSG and NOTICE messages sent to the channel, and see when any other users on the channel QUIT the network. These status messages let the client keep track of who’s in the channel, the topic, and the current channel modes.

If a user’s join request isn’t successful, they receive certain failure numerics. One of the ERR_CHANNELISFULL (limit), ERR_BADCHANNELKEY (key), ERR_INVITEONLYCHAN (invite-only), or ERR_BANNEDFROMCHAN (ban) numerics is returned if the related channel modes prevent the user from joining.

Servers may also limit how many channels a user can be in at one time (defined by the CHANLIMIT parameter). If the user can’t join the channel because the server simply won’t let them join any more, the server sends them a ERR_TOOMANYCHANNELS numeric.

The JOIN 0 command means “leave all channels” in some server software. If the server supports JOIN 0, then a client sending this is treated as though they have PARTed all channels. Some servers disallow this form since it can be abused to trick others into leaving all their channels.


Examples

C  ->  JOIN #test
S <-   :[email protected]::1 JOIN #test
S <-   :irc.example.com MODE #test +nt
S <-   :irc.example.com 353 dan = #test :@dan
S <-   :irc.example.com 366 dan #test :End of /NAMES list.

dan joining a new channel

C  ->  JOIN #test
S <-   :[email protected] JOIN #test
S <-   :irc.example.com 332 alice #test :This is my cool channel! https://irc.com
S <-   :irc.example.com 333 alice #test [email protected] 1547691506
S <-   :irc.example.com 353 alice @ #test :alice @dan
S <-   :irc.example.com 366 alice #test :End of /NAMES list.

alice joining an existing channel

C  ->  JOIN #irctoast
S <-   :[email protected] JOIN :#irctoast
S <-   :irc.example.com 353 patty = #irctoast :@patty
S <-   :irc.example.com 366 patty #irctoast :End of /NAMES list.
... some time passes ...
S <-   :[email protected] JOIN :#irctoast

patty seeing alice join a channel

C  ->  join #test
S <-   :irc.example.com 475 adrian #test :Cannot join channel (+k) - bad key

Failing to join a channel that has a key set

C  ->  JOIN #test mysecret
S <-   :[email protected] JOIN #test
S <-   :irc.example.com 353 adrian @ #test :adrian @dan
S <-   :irc.example.com 366 adrian #test :End of /NAMES list.

adrian joining a channel that has a key set

C  ->  join #toast,#ircv3 mysecret
S <-   :[email protected] JOIN #toast
S <-   :irc.example.com 353 alice = #toast :alice @dan
S <-   :irc.example.com 366 alice #toast :End of /NAMES list.
S <-   :[email protected] JOIN #ircv3
S <-   :irc.example.com 353 alice = #ircv3 :alice @dan
S <-   :irc.example.com 366 alice #ircv3 :End of /NAMES list.

Joining multiple channels, #toast having a key and #ircv3 having no key

C  ->  JOIN #test
S <-   :irc.example.com 471 alice #test :Cannot join channel (+l)

Failing to join a channel that has a limit set

C  ->  join #toast
S <-   :irc.example.com 474 alice #test :Cannot join channel (+b)

Failing to join a channel that has a ban set

C  ->  JOIN #test
S <-   :irc.example.com 473 alice #test :Cannot join channel (+i)

Failing to join a channel that has invite-only set

C  ->  join 0
S <-   :[email protected] PART #supercoolfriends :Left all channels
S <-   :[email protected] PART #ircv3 :Left all channels
S <-   :[email protected] PART #test :Left all channels

JOIN 0 succeeding

C  ->  join 0
S <-   :irc.example.com 476 dan 0 :Invalid channel name

JOIN 0 failing

C  ->  JOIN #ircv3
S <-   :irc.example.com 405 alice #ircv3 :You have joined too many channels

Joining too many channels


Compatibility


Related Numerics

  • RPL_TOPIC (332)
  • RPL_TOPICTIME (333)
  • RPL_NAMREPLY (353)
  • ERR_NOSUCHCHANNEL (403)
  • ERR_TOOMANYCHANNELS (405)
  • ERR_NEEDMOREPARAMS (461)
  • ERR_CHANNELISFULL (471)
  • ERR_INVITEONLYCHAN (473)
  • ERR_BANNEDFROMCHAN (474)
  • ERR_BADCHANNELKEY (475)

Contributors to this page: Daniel Oaks

You can edit and contribute changes to this page on GitHub here.

Latest change: 14 July 2020.