Dialogue

Dialogues control which paths are available and for how long. Passing messages into a dialogue will match against the current path and route any replies.

Where paths are self-replicating steps, the dialogue persists along the journey.

Kind: global class

• Dialogue
  • new Dialogue(res, [options], [key])
  • .end() ⇒ boolean
  • .send(…strings) ⇒ Promise
  • .onTimeout([override])
  • .clearTimeout()
  • .startTimeout()
  • .addPath([prompt], [branches], [options], [key]) ⇒ Promise
  • .addBranch(regex, [message], [callback])
  • .receive(res) ⇒ Promise

---

new Dialogue(res, [options], [key])

Param	Type	Description
res	Response	Hubot Response object
[options]	Object	Key/val options for config
[options.sendReplies]	boolean	Toggle replying/sending (prefix with “@user”)
[options.timeout]	number	Allowed time to reply (in miliseconds) before cancelling listeners
[options.timeoutText]	string	What to send when timeout reached, set null to not send
[key]	string	Key name for this instance

Example (listener sets up dialogue with user on match (10 second timeout))

robot.hear(/hello/, (res) => {
  let dlg = new Dialogue(res, { timeout: 10000 })
  // ...proceed to add paths
})

---

dialogue.end() ⇒ boolean

Shutdown and emit status (for scene to disengage participants).

Kind: instance method of Dialogue
Returns: boolean - Shutdown status, false if was already ended

---

dialogue.send(…strings) ⇒ Promise

Send or reply with message as configured (@user reply or send to room).

Kind: instance method of Dialogue
Returns: Promise - Resolves with result of send (respond middleware context)

Param	Type	Description
…strings	string	Message strings

---

dialogue.onTimeout([override])

Default timeout method sends message, unless null or method overriden.

If given a method it will call that or can be reassigned as a new function.

Kind: instance method of Dialogue

Param	Type	Description
[override]	function	New function to call (optional)

---

dialogue.clearTimeout()

Stop countdown for matching dialogue branches.

Kind: instance method of Dialogue

---

dialogue.startTimeout()

Start (or restart) countdown for matching dialogue branches.

Catches the onTimeout method because it can be overriden and may throw.

Kind: instance method of Dialogue

---

dialogue.addPath([prompt], [branches], [options], [key]) ⇒ Promise

Add a dialogue path, with branches to follow and a prompt (optional).

Any new path added overwrites the previous. If a path isn’t given a key but the parent dialogue has one, it will be given to the path.

Kind: instance method of Dialogue
Returns: Promise - Resolves when sends complete or immediately

Param	Type	Description
[prompt]	string	To send on path setup (e.g. presenting options)
[branches]	array	Array of args for each branch, each containing: - RegExp for listener - String to send and/or - Function to call on match
[options]	Object	Key/val options for path
[key]	string	Key name for this path

Example

let dlg = new Dialogue(res)
let path = dlg.addPath('Turn left or right?', [
  [ /left/, 'Ok, going left!' ]
  [ /right/, 'Ok, going right!' ]
], 'which-way')

---

dialogue.addBranch(regex, [message], [callback])

Add a branch to dialogue path, which is usually added first, but will be created if not.

Kind: instance method of Dialogue

Param	Type	Description
regex	RegExp	Matching pattern
[message]	string	Message text for response on match
[callback]	function	Function called when matched

---

dialogue.receive(res) ⇒ Promise

Process incoming message for match against path branches.

If matched, restart timeout. If no additional paths or branches added (by matching branch handler), end dialogue.

Overrides any prior response with current one.

Kind: instance method of Dialogue
Returns: Promise - Resolves when matched/catch handler complete

Param	Type	Description
res	Response	Hubot Response object

---