Class: Intent

Intent(client, botClient, opts)

new Intent(client, botClient, opts)

Create an entity which can fulfil the intent of a given user.
Parameters:
Name Type Description
client MatrixClient The matrix client instance whose intent is being fulfilled e.g. the entity joining the room when you call intent.join(roomId).
botClient MatrixClient The client instance for the AS bot itself. This will be used to perform more priveleged actions such as creating new rooms, sending invites, etc.
opts Object Options for this Intent instance.
Properties
Name Type Attributes Default Description
registered boolean True to inform this instance that the client is already registered. No registration requests will be made from this Intent. Default: false.
dontCheckPowerLevel boolean True to not check for the right power level before sending events. Default: false.
backingStore Object <optional>
 An object with 4 functions, outlined below. If this Object is supplied, ALL 4 functions must be supplied. If this Object is not supplied, the Intent will maintain its own backing store for membership and power levels, which may scale badly for lots of users.
Properties
Name Type Description
getMembership function A function which is called with a room ID and user ID which should return the membership status of this user as a string e.g "join". `null` should be returned if the membership is unknown.
getPowerLevelContent function A function which is called with a room ID which should return the power level content for this room, as an Object. `null` should be returned if there is no known content.
setMembership function A function with the signature: function(roomId, userId, membership) which will set the membership of the given user in the given room. This has no return value.
setPowerLevelContent function A function with the signature: function(roomId, content) which will set the power level content in the given room. This has no return value.
dontJoin boolean True to not attempt to join a room before sending messages into it. The surrounding code will have to ensure the correct membership state itself in this case. Default: false.
enablePresence boolean <optional>
 true True to send presence, false to no-op.
caching.ttl Number How long requests can stay in the cache, in milliseconds.
caching.size Number How many entries should be kept in the cache, before the oldest is dropped.
Source:

Methods

ban(roomId, target, reason) → {Promise}

Ban a user from a room.

This will automatically make the client join the room so they can send the ban if they are not already joined.
Parameters:
Name Type Description
roomId string The room to ban the user from.
target string The target of the ban operation.
reason string Optional. The reason for the ban.
Source:
Returns:
Resolved when banned, else rejected with an error.
Type
Promise

createAlias(alias, roomId) → {Promise}

Create a new alias mapping.
Parameters:
Name Type Description
alias string The room alias to create
roomId string The room ID the alias should point at.
Source:
Returns:
Type
Promise

createRoom(opts) → {Promise}

Create a room with a set of options.
Parameters:
Name Type Description
opts Object Options.
Properties
Name Type Description
createAsClient boolean True to create this room as a client and not the bot: the bot will not join. False to create this room as the bot and auto-join the client. Default: false.
options Object Options to pass to the client SDK /createRoom API.
Source:
Returns:
Type
Promise

getClient() → {MatrixClient}

Return the client this Intent is acting on behalf of.
Source:
Returns:
The client
Type
MatrixClient

getEvent(roomId, eventId, useCacheopt) → {Promise}

Get an event in a room. This will automatically make the client join the room so they can get the event if they are not already joined.
Parameters:
Name Type Attributes Default Description
roomId string The room to fetch the event from.
eventId string The eventId of the event to fetch.
useCache boolean <optional>
 true Should the request attempt to lookup from the cache.
Source:
Returns:
Resolves with the content of the event, or rejects if not found.
Type
Promise

getProfileInfo(userId, info, useCacheopt) → {Promise}

Get a user's profile information

Parameters:
Name Type Attributes Default Description
userId string The ID of the user whose profile to return
info string The profile field name to retrieve (e.g. 'displayname' or 'avatar_url'), or null to fetch the entire profile information.
useCache boolean <optional>
 true Should the request attempt to lookup state from the cache.
Source:
Returns:
A Promise that resolves with the requested user's profile information
Type
Promise

getStateEvent(roomId, eventType, stateKeyopt) → {Promise}

Get a state event in a room. This will automatically make the client join the room so they can get the state if they are not already joined.
Parameters:
Name Type Attributes Default Description
roomId string The room to get the state from.
eventType string The event type to fetch.
stateKey string <optional>
 "" The state key of the event to fetch.
Source:
Returns:
Type
Promise

invite(roomId, target) → {Promise}

Invite a user to a room.

This will automatically make the client join the room so they can send the invite if they are not already joined.
Parameters:
Name Type Description
roomId string The room to invite the user to.
target string The user ID to invite.
Source:
Returns:
Resolved when invited, else rejected with an error.
Type
Promise

join(roomId, viaServers) → {Promise}

Join a room

This will automatically send an invite from the bot if it is an invite-only room, which may make the bot attempt to join the room if it isn't already.
Parameters:
Name Type Description
roomId string The room to join.
viaServers Array.<string> The server names to try and join through in addition to those that are automatically chosen.
Source:
Returns:
Type
Promise

kick(roomId, target, reason) → {Promise}

Kick a user from a room.

This will automatically make the client join the room so they can send the kick if they are not already joined.
Parameters:
Name Type Description
roomId string The room to kick the user from.
target string The target of the kick operation.
reason string Optional. The reason for the kick.
Source:
Returns:
Resolved when kickked, else rejected with an error.
Type
Promise

leave(roomId) → {Promise}

Leave a room

This will no-op if the user isn't in the room.
Parameters:
Name Type Description
roomId string The room to leave.
Source:
Returns:
Type
Promise

onEvent(event)

Inform this Intent class of an incoming event. Various optimisations will be done if this is provided. For example, a /join request won't be sent out if it knows you've already been joined to the room. This function does nothing if a backing store was provided to the Intent.
Parameters:
Name Type Description
event Object The incoming event JSON
Source:

roomState(roomId, useCacheopt) → {Promise}

Get the current room state for a room.

This will automatically make the client join the room so they can get the state if they are not already joined.
Parameters:
Name Type Attributes Default Description
roomId string The room to get the state from.
useCache boolean <optional>
 false Should the request attempt to lookup state from the cache.
Source:
Returns:
Type
Promise

sendEvent(roomId, type, content) → {Promise}

Send a message event to a room.

This will automatically make the client join the room so they can send the message if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
type string The event type
content Object The event content
Source:
Returns:
Type
Promise

sendMessage(roomId, content) → {Promise}

Send an m.room.message event to a room.

This will automatically make the client join the room so they can send the message if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
content Object The event content
Source:
Returns:
Type
Promise

sendReadReceipt() → {Promise}

Send a read receipt to a room.

This will automatically make the client join the room so they can send the receipt event if they are not already joined.
Source:
Returns:
Type
Promise

sendStateEvent(roomId, type, skey, content) → {Promise}

Send a state event to a room.

This will automatically make the client join the room so they can send the state if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
type string The event type
skey string The state key
content Object The event content
Source:
Returns:
Type
Promise

sendText(roomId, text) → {Promise}

Send a plaintext message to a room.

This will automatically make the client join the room so they can send the message if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
text string The text string to send.
Source:
Returns:
Type
Promise

sendTyping(roomId, isTyping) → {Promise}

Send a typing event to a room.

This will automatically make the client join the room so they can send the typing event if they are not already joined.
Parameters:
Name Type Description
roomId string The room to send to.
isTyping boolean True if typing
Source:
Returns:
Type
Promise

setAvatarUrl(url) → {Promise}

Set the user's avatar URL

Parameters:
Name Type Description
url string The new avatar URL
Source:
Returns:
Type
Promise

setDisplayName(name) → {Promise}

Set the user's display name

Parameters:
Name Type Description
name string The new display name
Source:
Returns:
Type
Promise

setPowerLevel(roomId, target, level) → {Promise}

Set the power level of the given target.
Parameters:
Name Type Description
roomId string The room to set the power level in.
target string The target user ID
level number The desired level
Source:
Returns:
Type
Promise

setPresence(presence, status_msg) → {Promise}

Set the presence of this user.
Parameters:
Name Type Description
presence string One of "online", "offline" or "unavailable".
status_msg string The status message to attach.
Source:
Returns:
Resolves if the presence was set or no-oped, rejects otherwise.
Type
Promise

setRoomAvatar(roomId, avatar, info) → {Promise}

Set the avatar of a room.

This will automatically make the client join the room so they can set the topic if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
avatar string The url of the avatar.
info string Extra information about the image. See m.room.avatar for details.
Source:
Returns:
Type
Promise

setRoomName(roomId, name) → {Promise}

Set the name of a room.

This will automatically make the client join the room so they can set the name if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
name string The room name.
Source:
Returns:
Type
Promise

setRoomTopic(roomId, topic) → {Promise}

Set the topic of a room.

This will automatically make the client join the room so they can set the topic if they are not already joined. It will also make sure that the client has sufficient power level to do this.
Parameters:
Name Type Description
roomId string The room to send to.
topic string The room topic.
Source:
Returns:
Type
Promise

unban(roomId, target) → {Promise}

Unban a user from a room.

This will automatically make the client join the room so they can send the unban if they are not already joined.
Parameters:
Name Type Description
roomId string The room to unban the user from.
target string The target of the unban operation.
Source:
Returns:
Resolved when unbanned, else rejected with an error.
Type
Promise

unstableSignalBridgeError(roomID, eventID, networkName, reason, reason_body, affectedUsers) → {Promise}

Signals that an error occured while handling an event by the bridge. **Warning**: This function is unstable and is likely to change pending the outcome of https://github.com/matrix-org/matrix-doc/pull/2162.
Parameters:
Name Type Description
roomID string ID of the room in which the error occured.
eventID string ID of the event for which the error occured.
networkName string Name of the bridged network.
reason BridgeErrorReason The reason why the bridge error occured.
reason_body string A human readable string d
affectedUsers Array.<string> Array of regex matching all affected users.
Source:
Returns:
Type
Promise