discord.js/docs/docs_client.rst

.. include:: ./vars.rst

Client Documentation
====================

This page contains documentation on the `Discord.Client` class. This should be used when you want to start creating things with the API.

It might be beneficial to use CTRL+F to search for what you're looking for, or use the navigation provided by readthedocs on the left.

Attributes
----------

options
~~~~~~~
An `Object` containing a configuration for the Client. Currently can only be configured like so:

.. code-block:: js

    {
        queue : false // whether messages should be sent one after the other or
                      // just send straight away.
    }

token
~~~~~
A `String` that is the token received after logging in. It is used to authorise the Client when joining WebSockets or making HTTP requests. Example token:

.. code-block:: js

    ODAzTOc4MTA2BjQ2MjY4ODg.COmrCA.fEtD_Tc0JU6iZJU_11coEWBOQHE

state
~~~~~
An `Integer` representing what state of connection the Client is in.

- **0** is idle, meaning the Client has been created but no login attempts have been made.
- **1** is logging in, meaning the Client is in the process of logging in.
- **2** is logged in, meaning the Client is logged in but not necessarily ready.
- **3** is ready, meaning the Client is ready to begin listening.
- **4** is disconnected, meaning the Client was disconnected due to any reason.

See also ready_.

.. code-block:: js

    if( bot.state === 3 ) // ready to go
    
user
~~~~
A `User`_ object representing the account of the signed in client. This will only be available when the client is in the ready state (3).
    
.. code-block:: js

    bot.user.username; // username of the account logged in
    
email
~~~~~
A `String` that is the email used to sign the client in.

password
~~~~~~~~
A `String` that is the password used to sign the client in.
    
readyTime
~~~~~~~~~
A `Number` representing the unix timestamp from when the client was ready. `Null` if not yet ready.

.. code-block:: js

    bot.readyTime; // 1443378242464
    
uptime
~~~~~~
A `Number` representing how many milliseconds have passed since the client was ready. `Null` if not yet ready.

.. code-block:: js

    if( bot.uptime > 5000 ) // true if the client has been up for more than 5 seconds

ready
~~~~~
A `Boolean` that is true if the client is ready. A shortcut to checking if ``bot.state === 3``.

servers
~~~~~~~
An `Array` of Server_ objects that the client has access to.

channels
~~~~~~~~
An `Array` of Channel_ objects that the client has access to.

users
~~~~~
An `Array` of User_ objects that the client has access to.

PMChannels
~~~~~~~~~~
An `Array` of PMChannel_ objects the client has access to.

messages
~~~~~~~~
An `Array` of Message_ objects the client has received over its uptime.

Functions
---------

.. note :: Any functions used here that take callbacks as an optional parameter can also be used as Promises_. Promises take the exact same parameters for each use case, except errors are moved to catch statements instead of then. For example, you can do:

.. code-block:: js

    bot.login(email, password).then(success).catch(err);
    
    function success(token){
    
    }
    
    function err(error){
    
    }
    
    // OR use callbacks:
    
    bot.login(email, password, function(error, token){
    
    });
    
-----

login(email, password, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Logs the client in to set it up. Use this after registering your event listeners to ensure they are called.

- **email** - A `String` which is the email you want to sign in with.
- **password** - A `String` which is the password you want to sign in with.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **token** - if successful, it is the received authorisation token.
    
logout(`callback`)
~~~~~~~~~~~~~~~~~~

Logs the client out if it is logged in. If successful, ``bot.state == 4``.

- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    
createServer(name, region, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a server with the specified name or region. See valid regions below:

- **name** - A `String` that will be the name of your server.
- **region** - A `String` that is a valid Discord region. Currently **us-west**, **us-east**, **singapore**, **london**, **sydney** or **amsterdam**. Providing an invalid region will result in an error. To find the latest available regions, check the `official API here`_.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **server** - A Server_ that represents the created Server.
    
joinServer(invite, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Accepts a given invite to join a server. The server is automatically cached ASAP.

- **invite** - An `Invite Resolvable`_ which is the invite that should be accepted.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **server** - A Server_ that represents the joined Server.
    
leaveServer(server, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Leaves the given server.

- **server** -  A `Server Resolvable`_ that represents the server you want to leave.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    
createInvite(channel, options, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates an invite for the given channel and returns an Invite_.

- **channel** - A `Channel Resolvable`_ that is the channel you want to create an invite for.
- **options** - An `object` containing configurable options for the invite. See below for possible configurations.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **invite** - An Invite_ object that contains the details about the created invite.
    
.. code-block:: js

    // default configuration of the options variable:

    options = {
        max_age : 0, //A number signifying the expiry time for the invite. 0 means infinite.
        max_uses : 0, //A number signifying the amount of uses of the invite. 0 means infinite.
        temporary : false, //boolean - whether users who use it are kicked unless promoted within 24h.
        xkcd : false //boolean - whether the invite's URL should be human-readable
    }
    
createChannel(server, channelName, channelType, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a channel in the given server.

- **server** - A `Server Resolvable`_ that will be the server the channel is created in.
- **channelName** - A `String` that is the name of the channel.
- **channelType** - A `String` that is the type of the channel, either **voice** or **text**.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **channel** - An Channel_ object that represents the created channel.
    
deleteChannel(channel, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Deletes the specified channel.

- **channel** - A `Channel Resolvable`_ that will be the channel to delete.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    
getChannelLogs(channel, `amount`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Gets previous messages from the specified channel.

- **channel** - A `Channel Resolvable`_ to take logs from.
- **amount** - A `Number` that defaults to **500**. This is the amount of messages to try and get.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **logs** - An `Array` of Message_ objects that represent the previous messages.
    
.. warning:: If the logs contain messages from a user who is no longer in the server, the user object *MAY* be malformed.

sendMessage(channel, message, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sends a message to the specified channel.

- **channel** - A `Channel Resolvable`_ to send the message to.
- **message** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **message** - A Message_ representing the sent message.
    
sendFile(channel, file, `fileName`, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sends a file to the specified channel. Note that **fileName is necessary in certain cases** for when a file other than an image is sent. For example, if you send a file containing JS code, fileName should be something like ``myCode.js``.

- **channel** - A `Channel Resolvable`_ to send the file to.
- **file** - The file to send, either a `Buffer` or `String` - if a String, it should be a relative (`./`) or absolute path to a file.
- **fileName** - A `String` containing the file's name and extension, used by Discord (I didn't make this please don't shoot me :s) Examples include `picture.png`, `text.txt`, `wowanamazingscript.js`

- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **message** - A Message_ representing the sent file.
    
updateMessage(message, content, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Updates/edits a message with new content.

- **message** - A Message_ that should be updated.
- **content** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **message** - A Message_ representing the updated message.
    
reply(message, yourMessage, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alias for sendMessage, but prepends a mention to whoever sent the specified mention. Useful shortcut for directing a message at a user.

.. code-block:: js

    // example usage:
    
    the user 'bob' sent a message
    
    bot.reply(message, "hello");
    // will send the message '@bob, hello' to the channel the message that bob sent was in.
    
- **message** - A Message_ that should be replied to.
- **yourMessage** - A `String` or an Array of strings. If an Array, the array will be joined with a new line as a delimiter and this will be the message to be sent.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    - **message** - A Message_ representing the sent message.
    
setUsername(newName, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sets the username of the logged in client.

- **newName** - The new name of the client, a `String`.
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.
    
startTyping(channel, *stopTime*)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Makes the client appear to be typing in the specified channel.

- **channel** - A `Channel Resolvable`_ that should be the channel to start typing in
- **stopTime** - A `Number` in ms which should make the client stop typing after. Allow 5 seconds.

stopTyping(channel)
~~~~~~~~~~~~~~~~~~~

Makes the client stop typing in a specified channel.

- **channel** - A `Channel Resolvable`_ that should be the channel to stop typing in.

setStatusOnline()
~~~~~~~~~~~~~~~~~

**Aliases**: ``setStatusActive()`` and ``setStatusHere()``

Sets the client's status to online; green.

setStatusIdle()
~~~~~~~~~~~~~~~~~

**Aliases**: ``setStatusAway()``

Sets the client's status to idle; orange.

setTopic(channel, topic, `callback`)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sets the topic of the specified channel

- **channel** - A `Channel Resolvable`_ that is the channel you want to change the topic of
- **topic** - A `String` that is the topic you want
- **callback** - A `function` that can take the following parameters:

    - **error** - An error if one occurred, otherwise it is null.

getUser(key, value)
~~~~~~~~~~~~~~~~~~~

Gets a User_ that matches the specified criteria. E.g:

.. code-block:: js

    bot.getUser("id", 1243987349) // returns a user where user.id === 1243987349
    
- **key** - a `String` that is the key
- **value** - a `String` that is the value

getServer(key, value)
~~~~~~~~~~~~~~~~~~~~~

Gets a Server_ that matches the specified criteria. E.g:

.. code-block:: js

    bot.getServer("id", 1243987349) // returns a server where server.id === 1243987349
    
- **key** - a `String` that is the key
- **value** - a `String` that is the value


getChannel(key, value)
~~~~~~~~~~~~~~~~~~~~~~

Gets a Channel_ that matches the specified criteria. E.g:

.. code-block:: js

    bot.getChannel("id", 1243987349) // returns a Channel where channel.id === 1243987349
    
- **key** - a `String` that is the key
- **value** - a `String` that is the value


getPMChannel(key, value)
~~~~~~~~~~~~~~~~~~~~~~~~

Gets a PMChannel_ that matches the specified criteria. E.g:

.. code-block:: js

    bot.getPMChannel("id", 1243987349) // returns a PMChannel where pmchannel.id === 1243987349
    
- **key** - a `String` that is the key
- **value** - a `String` that is the value

-----

Event Management
----------------

Events are a useful way of listening to events and are available in every API.

Registering Events
~~~~~~~~~~~~~~~~~~

.. code-block:: js

    bot.on("eventName", function(arg1, arg2...){
        // code here is called when eventName is emitted.
    })
    
.. note:: You can only have one listening function per event

Unregistering Events
~~~~~~~~~~~~~~~~~~~~

.. code-block:: js

    bot.off("eventName")
    // eventName is no longer listened for
    
Event Types
-----------

ready
~~~~~

Called when the bot is ready and you can begin working with it.

disconnected
~~~~~~~~~~~~

Called when the bot is disconnected for whatever reason.

error
~~~~~

Called whenever there is an error.

**Parameters**

- **error** - the encountered error

.. note:: There may be more parameters supplied depending on the errors. Use the ``arguments`` variable to check for this for advanced debugging.

debug
~~~~~

Called when the client debugs some information that might be useful for a developer but not for an end user.

**Parameters**

- **message** - the debug message as a `String`

message
~~~~~~~

Called when a message has been received by the client.

**Parameters**

- **message** - the received Message_.

messageDelete
~~~~~~~~~~~~~

Called when a message has been deleted.

**Parameters**

- **channel** - The Channel_ that the deleted message was in.
- **message** - *May* be available. If the message wasn't previously cached, this will not be supplied and all you would know is that a message was deleted in the channel. If it is available, it will be in the format of a Message_.

messageUpdate
~~~~~~~~~~~~~

Called when a message has been updated.

**Parameters**

- **newMessage** - The updated Message_.
- **oldMessage** - The old Message_ before it was updated.

serverDelete
~~~~~~~~~~~~

Called when a server is deleted.

**Parameters**

- **server** - The deleted Server_.

channelDelete
~~~~~~~~~~~~~

Called when a channel is deleted.

**Parameters**

- **channel** - The deleted Channel_.

serverCreate
~~~~~~~~~~~~

Called when a server is created/joined.

**Parameters**

- **server** - The created Server_.

channelCreate
~~~~~~~~~~~~

Called when a channel is created.

**Parameters**

- **channel** - The created Channel_.

serverNewMember
~~~~~~~~~~~~~~~

Called when a new member is added to a server.

**Parameters**

- **user** - The User_ that was added.
- **server** - The Server_ that the user was added to.

serverRemoveMember
~~~~~~~~~~~~~~~~~~

Called when a member of a server leaves or is kicked out.

**Parameters**

- **user** - The User_ that was removed.
- **server** - The Server_ that the user was removed from.

userUpdate
~~~~~~~~~~

Called when information about a user changes, such as their username.

**Parameters**

- **newUser** - A User_ object representing the changes to the old user (this will be in the cache)
- **oldUser** - A User_ object representing the user before the update.

presence
~~~~~~~~

Called when a user goes online/offline/away or starts/stops playing a game.

**Parameters**

- **dataObject** - Instead of separate arguments, presence update takes an object containing the following information:

    - **user** - A User_ representing the User that had a presence update
    - **status** - The status change as a `String`.
    - **server** - The Server_ that the presence change occurred in.
    - **gameId** - A `Number` representing the game they are playing if any. Currently, discord.js has no internal support for converting this into a game name.
    
unknown
~~~~~~~

Called when an unknown packet was received or there is no handler for it.

**Parameters**

- **data** - A `JSON Object` which is the message received over WebSocket.

raw
~~~

Called when a WebSocket message is received and it gives you the message.

**Parameters**

- **data** - A `JSON Object` which is the message received over WebSocket.

.. _official API here : https://discordapp.com/api/voice/regions