Class Intent

Hierarchy (view full)

Intent
- EncryptedIntent

Constructors

constructor

new Intent(botSdkIntent, botClient, opts?): Intent
Create an entity which can fulfil the intent of a given user.
Parameters
- botSdkIntent: Intent
  The bot sdk intent which this intent wraps 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: IntentOpts = {}
  Options for this Intent instance.
Returns Intent
- Defined in src/components/intent.ts:166

Properties

`Readonly` botSdkIntent

botSdkIntent: Intent

The bot sdk intent which this intent wraps fulfilled e.g. the entity joining the room when you call intent.join(roomId).

`Protected` opts

opts: {
    backingStore: IntentBackingStore;
    caching: {
        size: number;
        ttl: number;
    };
    dontCheckPowerLevel?: boolean;
    dontJoin?: boolean;
    enablePresence: boolean;
    getJsSdkClient?: (() => any);
    onEventSent?: OnEventSentHook;
    registered?: boolean;
}

Type declaration

backingStore: IntentBackingStore
caching: {
size: number;
ttl: number;
}
- size: number
- ttl: number
Optional dontCheckPowerLevel?: boolean
Optional dontJoin?: boolean
enablePresence: boolean
Optional getJsSdkClient?: (() => any)
- - (): any
  - Returns any
Optional onEventSent?: OnEventSentHook
Optional registered?: boolean

Accessors

matrixClient

get matrixClient(): MatrixClient
Returns MatrixClient
- Defined in src/components/intent.ts:238

userId

get userId(): string
Returns string
- Defined in src/components/intent.ts:242

Methods

`Protected` _ensureHasPowerLevelFor

_ensureHasPowerLevelFor(roomId, eventType, isState): Promise<undefined | PowerLevelContent>
Ensures that the client has the required power level to post the event type.
Parameters
- roomId: string
  Required as power levels exist inside a room.
- eventType: string
- isState: boolean
  Are we checking for state permissions or regular event permissions.
Returns Promise<undefined | PowerLevelContent>
If found, the power level event
- Defined in src/components/intent.ts:1003

`Protected` _ensureJoined

_ensureJoined(roomIdOrAlias, ignoreCache?, viaServers?, passthroughError?): Promise<string>
Parameters
- roomIdOrAlias: string
- ignoreCache: boolean = false
- Optional viaServers: string[]
- passthroughError: boolean = false
Returns Promise<string>
- Defined in src/components/intent.ts:919

`Protected` _joinGuard

_joinGuard<T>(roomId, promiseFn): Promise<T>
Type Parameters
- T
Parameters
- roomId: string
- promiseFn: (() => Promise<T>)
  - - (): Promise<T>
    - Returns Promise<T>
Returns Promise<T>
- Defined in src/components/intent.ts:904

ban

ban(roomId, target, reason?): Promise<any>
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
- roomId: string
  The room to ban the user from.
- target: string
  The target of the ban operation.
- Optional reason: string
  Optional. The reason for the ban.
Returns Promise<any>
Resolved when banned, else rejected with an error.
- Defined in src/components/intent.ts:548

createAlias

createAlias(alias, roomId): Promise<any>
Create a new alias mapping.
Parameters
- alias: string
  The room alias to create
- roomId: string
  The room ID the alias should point at.
Returns Promise<any>
- Defined in src/components/intent.ts:682

createRoom

createRoom(opts): Promise<{
room_id: string;
}>
Create a room with a set of options.
Parameters
- opts: RoomCreationOpts
  Options.
Returns Promise<{
room_id: string;
}>
- Defined in src/components/intent.ts:471

createWidget

createWidget(roomId, widgetId, opts): Promise<string>
Create a widget in a room.
Parameters
- roomId: string
  The room to create the widget in.
- widgetId: string
  The widget ID
- opts: WidgetOpts
  Options for the widget.
Returns Promise<string>
An eventID if the event was created.
- Defined in src/components/intent.ts:834

ensureProfile

ensureProfile(displayname?, avatarUrl?): Promise<void>
Ensure that the user has the given profile information set. If it does not, set it.
Parameters
- Optional displayname: string
  The displayname to set. Leave undefined to ignore.
- Optional avatarUrl: string
  The avatar to set. Leave undefined to ignore.
Returns Promise<void>
- Defined in src/components/intent.ts:648

ensureRegistered

ensureRegistered(forceRegister?): Promise<undefined | "registered=true">
Parameters
- forceRegister: boolean = false
Returns Promise<undefined | "registered=true">
- Defined in src/components/intent.ts:1068

ensureWidgetInRoom

ensureWidgetInRoom(roomId, widgetId, opts): Promise<null | string>
Create a widget in a room, if one doesn't already exist
Parameters
- roomId: string
  The room to create the widget in.
- widgetId: string
  The widget ID
- opts: WidgetOpts
  Options for the widget.
Returns Promise<null | string>
An eventID if the event was created, otherwise null.
- Defined in src/components/intent.ts:859

getEvent

getEvent(roomId, eventId, useCache?): Promise<any>
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
- roomId: string
  The room to fetch the event from.
- eventId: string
  The eventId of the event to fetch.
- useCache: boolean = true
  Should the request attempt to lookup from the cache.
Returns Promise<any>
Resolves with the content of the event, or rejects if not found.
- Defined in src/components/intent.ts:745

getProfileInfo

getProfileInfo(userId, info?, useCache?): Promise<MatrixProfileInfo>
Get a user's profile information
Parameters
- userId: string
  The ID of the user whose profile to return
- info: UserProfileKeys = null
  The profile field name to retrieve (e.g. 'displayname' or 'avatar_url'), or null to fetch the entire profile information.
- useCache: boolean = true
  Should the request attempt to lookup state from the cache.
Returns Promise<MatrixProfileInfo>
A Promise that resolves with the requested user's profile information
- Defined in src/components/intent.ts:606

getStateEvent

getStateEvent(roomId, eventType, stateKey?, returnNull?): Promise<any>
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
- roomId: string
  The room to get the state from.
- eventType: string
  The event type to fetch.
- stateKey: string = ""
  The state key of the event to fetch.
- returnNull: boolean = false
  Return null on not found, rather than throwing
Returns Promise<any>
- Defined in src/components/intent.ts:762

invite

invite(roomId, target): Promise<any>
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
- roomId: string
  The room to invite the user to.
- target: string
  The user ID to invite.
Returns Promise<any>
Resolved when invited, else rejected with an error.
- Defined in src/components/intent.ts:515

join

join(roomIdOrAlias, viaServers?): Promise<string>
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
- roomIdOrAlias: string
  The room ID or room alias to join.
- Optional viaServers: string[]
  The server names to try and join through in addition to those that are automatically chosen.
Returns Promise<string>
- Defined in src/components/intent.ts:576

kick

kick(roomId, target, reason?): Promise<any>
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
- roomId: string
  The room to kick the user from.
- target: string
  The target of the kick operation.
- Optional reason: string
  Optional. The reason for the kick.
Returns Promise<any>
Resolved when kickked, else rejected with an error.
- Defined in src/components/intent.ts:530

leave

leave(roomId, reason?): Promise<any>
Leave a room

This will no-op if the user isn't in the room.
Parameters
- roomId: string
  The room to leave.
- Optional reason: string
  An optional string to explain why the user left the room.
Returns Promise<any>
- Defined in src/components/intent.ts:587

onEvent

onEvent(event): void
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
- event: WeakStateEvent
  The incoming event JSON
Returns void
- Defined in src/components/intent.ts:874

resolveRoom

resolveRoom(roomAliasOrId): Promise<string>
Resolve a roomId or alias into a roomId. If a roomId is given, it is immediately returned.
Parameters
- roomAliasOrId: string
  A roomId or alias to resolve.
Returns Promise<string>
Throws
If the provided string was incorrectly formatted or alias does not exist.
- Defined in src/components/intent.ts:251

roomState

roomState(roomId, useCache?): Promise<unknown>
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
- roomId: string
  The room to get the state from.
- useCache: boolean = false
  Should the request attempt to lookup state from the cache.
Returns Promise<unknown>
- Defined in src/components/intent.ts:454

sendEvent

sendEvent(roomId, type, content): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- type: string
  The event type
- content: Record<string, unknown>
  The event content
Returns Promise<{
event_id: string;
}>
The event ID wrapped inside an object (for legacy reasons)
- Defined in src/components/intent.ts:396

sendMessage

sendMessage(roomId, content): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- content: Record<string, unknown>
  The event content
Returns Promise<{
event_id: string;
}>
The eventId of the sent message
- Defined in src/components/intent.ts:381

sendReadReceipt

sendReadReceipt(roomId, eventId): Promise<void>
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.
Parameters
- roomId: string
  The room to send to.
- eventId: string
  The event ID to set the receipt mark to.
Returns Promise<void>
- Defined in src/components/intent.ts:341

sendStateEvent

sendStateEvent(roomId, type, skey, content): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- type: string
  The event type
- skey: string
  The state key
- content: Record<string, unknown>
  The event content
Returns Promise<{
event_id: string;
}>
The event ID wrapped inside an object (for legacy reasons)
- Defined in src/components/intent.ts:422

sendText

sendText(roomId, text): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- text: string
  The text string to send.
Returns Promise<{
event_id: string;
}>
The Matrix event ID.
- Defined in src/components/intent.ts:265

sendTyping

sendTyping(roomId, isTyping): Promise<void>
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
- roomId: string
  The room to send to.
- isTyping: boolean
  True if typing
Returns Promise<void>
- Defined in src/components/intent.ts:328

setAvatarUrl

setAvatarUrl(url): Promise<any>
Set the user's avatar URL
Parameters
- url: string
  The new avatar URL
Returns Promise<any>
- Defined in src/components/intent.ts:637

setDisplayName

setDisplayName(name): Promise<any>
Set the user's display name
Parameters
- name: string
  The new display name
Returns Promise<any>
- Defined in src/components/intent.ts:627

setPowerLevel

setPowerLevel(roomId, target, level): Promise<void>
Set the power level of the given target.
Parameters
- roomId: string
  The room to set the power level in.
- target: string
  The target user ID
- level: undefined | number
  The desired level. Undefined will remove the users custom power level.
Returns Promise<void>
- Defined in src/components/intent.ts:352

setPresence

setPresence(presence, statusMsg?): Promise<any>
Set the presence of this user.
Parameters
- presence: PresenceState
  One of "online", "offline" or "unavailable".
- Optional statusMsg: string
Returns Promise<any>
Resolves if the presence was set or no-oped, rejects otherwise.
- Defined in src/components/intent.ts:693

setRoomAvatar

setRoomAvatar(roomId, avatar, info?): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- avatar: string
  The url of the avatar.
- Optional info: string
  Extra information about the image. See m.room.avatar for details.
Returns Promise<{
event_id: string;
}>
- Defined in src/components/intent.ts:313

setRoomDirectoryVisibility

setRoomDirectoryVisibility(roomId, visibility): Promise<any>
Set the visibility of a room in the homeserver's room directory.
Parameters
- roomId: string
  The room
- visibility: "public" | "private"
  Should the room be visible
Returns Promise<any>
- Defined in src/components/intent.ts:802

setRoomDirectoryVisibilityAppService

setRoomDirectoryVisibilityAppService(roomId, networkId, visibility): Promise<void>
Set the visibility of a room in the appservice's room directory. This only works if you have defined the protocol in the registration file.
Parameters
- roomId: string
  The room
- networkId: string
  The network (not protocol) that owns this room. E.g. "freenode" (for an IRC bridge)
- visibility: "public" | "private"
  Should the room be visible
Returns Promise<void>
- Defined in src/components/intent.ts:814

setRoomName

setRoomName(roomId, name): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- name: string
  The room name.
Returns Promise<{
event_id: string;
}>
The Matrix event ID.
- Defined in src/components/intent.ts:282

setRoomTopic

setRoomTopic(roomId, topic): Promise<{
event_id: string;
}>
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
- roomId: string
  The room to send to.
- topic: string
  The room topic.
Returns Promise<{
event_id: string;
}>
- Defined in src/components/intent.ts:297

setRoomUserProfile

setRoomUserProfile(roomId, profile): Promise<void>
Parameters
- roomId: string
- profile: MatrixProfileInfo
Returns Promise<void>
- Defined in src/components/intent.ts:661

unban

unban(roomId, target): Promise<any>
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
- roomId: string
  The room to unban the user from.
- target: string
  The target of the unban operation.
Returns Promise<any>
Resolved when unbanned, else rejected with an error.
- Defined in src/components/intent.ts:562

unstableSignalBridgeError

unstableSignalBridgeError(roomID, eventID, networkName, reason, affectedUsers): Promise<{
event_id: string;
}>
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
- roomID: string
  ID of the room in which the error occured.
- eventID: string
  ID of the event for which the error occured.
- networkName: undefined | string
  Name of the bridged network.
- reason: BridgeErrorReason
  The reason why the bridge error occured.
- affectedUsers: string[]
  Array of regex matching all affected users.
Returns Promise<{
event_id: string;
}>
- Defined in src/components/intent.ts:714

uploadContent

uploadContent(content, opts?): Promise<string>
Upload a file to the homeserver.
Parameters
- content: string | Buffer
  The file contents
- opts: FileUploadOpts = {}
  Additional options for the upload.
Returns Promise<string>
A MXC URL pointing to the uploaded data.
- Defined in src/components/intent.ts:781

Class Intent

Hierarchy (view full)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

botSdkIntent: Intent

botClient: MatrixClient

opts: IntentOpts = {}

Returns Intent

Properties

Readonly botSdkIntent

Protected opts

Type declaration

backingStore: IntentBackingStore

caching: { size: number; ttl: number; }

size: number

ttl: number

Optional dontCheckPowerLevel?: boolean

Optional dontJoin?: boolean

enablePresence: boolean

Optional getJsSdkClient?: (() => any)

Returns any

Optional onEventSent?: OnEventSentHook

Optional registered?: boolean

Accessors

matrixClient

Returns MatrixClient

userId

Returns string

Methods

Protected _ensureHasPowerLevelFor

Parameters

roomId: string

eventType: string

isState: boolean

Returns Promise<undefined | PowerLevelContent>

Protected _ensureJoined

Parameters

roomIdOrAlias: string

ignoreCache: boolean = false

Optional viaServers: string[]

passthroughError: boolean = false

Returns Promise<string>

Protected _joinGuard

Type Parameters

T

Parameters

roomId: string

promiseFn: (() => Promise<T>)

Returns Promise<T>

Returns Promise<T>

ban

Parameters

roomId: string

target: string

Optional reason: string

Returns Promise<any>

createAlias

Parameters

alias: string

roomId: string

Returns Promise<any>

createRoom

Parameters

opts: RoomCreationOpts

Returns Promise<{ room_id: string; }>

createWidget

Parameters

roomId: string

widgetId: string

opts: WidgetOpts

Returns Promise<string>

ensureProfile

Parameters

Optional displayname: string

`Readonly` botSdkIntent

`Protected` opts

caching: {
size: number;
ttl: number;
}

`Optional` dontCheckPowerLevel?: boolean

`Optional` dontJoin?: boolean

`Optional` getJsSdkClient?: (() => any)

`Optional` onEventSent?: OnEventSentHook

`Optional` registered?: boolean

`Protected` _ensureHasPowerLevelFor

`Protected` _ensureJoined

`Optional` viaServers: string[]

`Protected` _joinGuard

`Optional` reason: string

Returns Promise<{
room_id: string;
}>

`Optional` displayname: string

`Optional` avatarUrl: string

`Optional` viaServers: string[]

`Optional` reason: string

`Optional` reason: string