Events¶
Events in opsdroid represent things that happen on the services that opsdroid connects to. They are both sent and received by the connectors.
All events are a subclass of the base Event
class. Each event also defines its own set of attributes which are specific to that type of event.
Event
¶
The base Event
class has the following attributes and methods.
- class opsdroid.events.Event(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)¶
A generic event type.
Initiates an Event object with the most basic information about its creation.
- Parameters
user_id (string, optional) – String id of user sending message
user (string, optional) – String name of user sending message
target (string, optional) – String name of the room or chat channel in which message was sent
connector (Connector, optional) – Connector object used to interact with given chat service
raw_event (dict, optional) – Raw message as provided by chat service. None by default
raw_parses (dict, optional) – Raw response as provided by parse service. None by default
event_id (object, optional) – The unique id for this event as provided by the connector.
linked_event (Event, optional) – An event to link to this one, i.e. the event that a reaction applies to.
- connector¶
A pointer to the opsdroid connector object which received the message.
- created¶
A timestamp of when this event was instantiated.
- entities¶
A dictionary mapping of entities created by parsers. These could be values extracted form sentences like locations, times, people, etc.
- event_id¶
A unique identifier for this event as provided by the connector.
- linked_event¶
Another event linked to this one, for example the event that a Message replies to.
- target¶
A string normally containing the name of the room or chat channel the event was sent in.
- raw_event¶
The raw event received by the connector (may be None).
- raw_parses¶
The raw response provided by the parser service.
- responded_to¶
A boolean (True/False) flag indicating if this event has already had its respond method called.
- user¶
A string containing the username of the user who created the event.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Note: For the sake of flexibility, Opsdroid only supports a single user on any given event. If you use Slack’s (or any other chat platforms supported by Opsdroid that have the possibility of a single event corresponding to multiple users) API call to invite users to a channel, the API call takes a list of users as the input. In that case, you need to create multiple ‘single-user’ events instead of trying to create one ‘multi-user’ event. If concerned about the performance, the Skill can call the API directly rather than emitting multiple events.
OpsdroidStarted
¶
The OpsdroidStarted
event is triggered once Opsdroid’s loader has completed.
Skills can respond to this in order to perform startup actions which require connectors, databases, etc. to be available first.
- class opsdroid.events.OpsdroidStarted(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)¶
An event to indicate that Opsdroid has loaded.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Message
¶
The Message
object is the most common event type, it represents textual events, and has the following attributes in addition to the base Event
attributes.
- class opsdroid.events.Message(text, *args, **kwargs)¶
A message object.
Stores messages in a format that allows OpsDroid to respond or react with delays for thinking and typing as defined in configuration YAML file.
- Parameters
text (string) – String text of message
target (string, optional) – String name of the room or chat channel in which message was sent
connector (Connector, optional) – Connector object used to interact with given chat service
raw_event (dict, optional) – Raw message as provided by chat service. None by default
raw_parses (dict, optional) – Raw response as provided by parse service. None by default
- created¶
Local date and time that message object was created
- user¶
String name of user sending message
- target¶
String name of the room or chat channel in which message was sent
- connector¶
Connector object used to interact with given chat service
- text¶
Text of message as string
- raw_event¶
Raw message provided by chat service
- raw_parses¶
Raw response provided by the parser service
- raw_match¶
A match object for a search against which the message was matched. E.g. a regular expression or natural language intent
- responded_to¶
Boolean initialized as False. True if event has been responded to
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async respond(response_event)¶
Respond to this message using the connector it was created by.
Creates copy of this message with updated text as response. Delays message if thinking or typing delay present in config. file. Updates responded_to attribute to True if False. Logs response and response time in OpsDroid object stats.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Typing
¶
An event to represent a typing indication.
- class opsdroid.events.Typing(trigger, timeout=None, *args, **kwargs)¶
An event to set the user typing.
- Parameters
trigger (bool) – Trigger typing on or off.
timeout (float, optional) – Timeout on typing event.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Reaction
¶
A reaction to a message, normally an emoji or a string representing one.
- class opsdroid.events.Reaction(emoji, *args, **kwargs)¶
Event class to support Unicode reaction to an event.
- Parameters
emoji (string) – The emoji to react with.
target (string, optional) – The room in which the reaction should be sent.
linked_event (opsdroid.events.Event) – The event to react to.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
File
¶
A file event. All files should be representable as bytes. A File
can be constructed using either a url or a bytes
object, if a url is specified the File.file_bytes
property will retrieve the url and store the response as bytes
.
- class opsdroid.events.File(file_bytes=None, url=None, url_headers=None, name=None, mimetype=None, *args, **kwargs)¶
Event class to represent arbitrary files as bytes.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async get_file_bytes()¶
Return the bytes representation of this file.
- async get_mimetype()¶
Return the mimetype for the file.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Image
¶
The Image
event is a subclass of File
, so in the same way File
can an Image
can be either a url or bytes, but should always be representable as bytes
.
- class opsdroid.events.Image(file_bytes=None, url=None, url_headers=None, name=None, mimetype=None, *args, **kwargs)¶
Event class specifically for image files.
- async get_dimensions()¶
Return the image dimensions
(w,h)
.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async get_file_bytes()¶
Return the bytes representation of this file.
- async get_mimetype()¶
Return the mimetype for the file.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct
Video
¶
The Video
event is a subclass of File
, so in the same way File
can an Video
can be either a url or bytes, but should always be representable as bytes
.
- class opsdroid.events.Video(file_bytes=None, url=None, url_headers=None, name=None, mimetype=None, *args, **kwargs)¶
Event class specifically for video files.
- async get_bin()¶
Return the binary representation of video.
- get_entity(name)¶
Get the value of an entity by name.
- Parameters
name (string) – Name of entity
- Returns
The value of the entity. Returns
None
if no such entity.
- async get_file_bytes()¶
Return the bytes representation of this file.
- async get_mimetype()¶
Return the mimetype for the file.
- async get_properties()¶
Get the video properties like codec, resolution.Returns Video properties saved in a Dictionary.
- async respond(event)¶
Respond to this event with another event.
This implies no link between the event we are responding with and this event.
- update_entity(name, value, confidence=None)¶
Add or update an entitiy.
Adds or updates an entitiy entry for an event.
- Parameters
name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct