Events & scheduling
Events are named signals that can be send and received by bot conversations.
Receiving events¶
In Bubblescript, events can be caught using an event trigger, either on a dialog, or on a task:
dialog event: "status_update" do
say "A status update came in: #{event.payload.text}"
end
task event: "status_update" do
log "status update: " + event.payload.text
end
Sending events¶
Sending events from Bubblescript is done using emit
:
emit "status_update", text: "#{user.first_name} started using the bot"
By default, emit
sends it event to the client, where it can be
picked up by for instance the Javascript SDK (Botsqd.onEmit("event",
....)
), but it can also send events to other processes, for instance
the master
process or a local group.
emit "status_update", [], to: "master"
Sends a message to the bot's master process. In that process it will be
handled using the dialog event: "..."
trigger.
to:¶
These are the emit to:
targets:
:client
-- Sends the event to the code that is hosting the chat, e.g., the Javascript SDK. In the SDK, it can be caught using theonEmit()
function. (this is the default value):chat_bubble
-- Sends the event to the chat bubble that hosts the conversation. This is only possible when the "web widget" connection is configured in the bot and the live visitors setting of the web widget is enabled. This can be used to send an event to the instance of the ChatBubble class of the ChatBubble JS SDK.:master
-- Sends the event to the bot'smaster
process, if amaster
script was defined. See multiple processes."string"
-- When the recipient is a string, it is considered a user ID, and sends the event there.
emit
is "fire and forget" -- No warnings / errors are generated when sending of the message fails. If you need to check whether the message was arrived, usequery
.
Scheduling events¶
The platform contains a scheduling system, so that events can be
scheduled to be sent in the future. Use either in:
or at:
as
arguments to emit
to schedule events in the future.
The following send a "status_update"
event to the client, in 10 seconds from now:
emit "status_update", [], in: 10
The following send a "wakeup"
event to the client, in one year:
emit "wakeup", [], in: "1y", to: :self
Specifying an absolute point in time is also possible:
emit "status_update", [], at: "tomorrow at 10:00"
When using at:
, the Duckling date parser
is used to parse the given date string. If the parsing fails, a
runtime error is thrown.
Note: It is not possible to schedule events in the past.
Naming events¶
While scheduling, you can give the event a name that you can use to cancel it again. You can also use it to reschedule the event, because the name is unique; scheduling a second emit with the same name will cancel out the first (if it was not yet fired).
emit "status_update", [], in: 10, name: "update"
emit "status_update", [], in: 20, name: "update"
This will only send out one emit, in 20 seconds.
Cancelling named events¶
When a scheduled emit has a name, it is possible to cancel it by calling cancel_emit()
:
emit "status_update", [], in: 10, name: "update"
result = cancel_emit "update"
Request / response¶
Using the query
function, you can send an event and wait for a reply.
reply = query :master, "ping"
say reply
In the other script, define a task or dialog that catches the ping
event,
and use the reply
construct to send a payload back:
task event: "ping" do
reply "pong"
end
Make sure that the handling task / dialog in the other process finishes quickly. If there is no reply received within 1 second, the value
:timeout
is returned in the calling process.