Events and Rich Output

A reply is more than the sentence the hub speaks. Alongside the text there can be display items for a screen, the raw events the runtime emitted while it worked, and a policy decision when access was refused. Read the normalized fields first; they answer most apps. Reach for the richer ones when you need them, not before.

What A Reply Contains

Output	Use it for
text	The collected answer text, which can contain SSML.
display_text	Answer text with markup removed for visual display.
display_items()	Text, choices, tables, images, and attachments.
events	The collected events, including their name, data, and context.
handled, ok, and failure_event	Whether the request completed and any recorded runtime failure.

Those are the Python names; Node spells them displayText, displayItems(), and failureEvent, and its events array carries the same events. Nothing called speech, raw_event, or policy_denied exists on a reply in any SDK, whatever older examples suggest. The language’s SDK page has the exact API.

Event Names

Where a language exposes constants for these, use them. The names underneath don’t change from one SDK to the next.

Event	Meaning
recognizer_loop:utterance	A client sends a user utterance.
speak	The hub returns speech or reply text.
ovos.intent.unmatched	A request matched no skill (current OVOS name).
complete_intent_failure	A request matched no skill (legacy Mycroft name; still emitted by older runtimes).
hive.policy.denied	Access policy blocked the request.
mycroft.skill.handler.start	A skill handler started.
mycroft.skill.handler.complete	A skill handler finished.

Display Items

Display items exist so an app with a screen never has to parse the spoken sentence to find the table inside it.

Text

A paragraph, title, subtitle, or status message.

Choice

A selectable option that can map back to send_action.

Table

Rows and columns for comparison, status, or inventory style output.

Image

A URL or attachment reference that the client can render.

Python Example

from thalovant import ThalovantClient

with ThalovantClient.from_identity_file("_identity.json") as client:
    reply = client.ask("Show the next maintenance steps.")

print(reply.display_text)

for item in reply.display_items():
    print(item.kind, item.text, item.data, item.url)

A choices item keeps its choices in item.data; each one can carry a title and a string payload, and the payload is what the app hands to send_action when the person picks it. Render the kinds your app understands and skip the rest.

Client Behavior

Case	Recommended handling
Answer text is present	Show display_text in a visual client; handle text or utterances according to your voice renderer’s SSML support.
display_items() returns items	Render the items the client understands and ignore unknown kinds.
A hive.policy.denied event arrives	Show a safe denied message and keep the request ID for troubleshooting.
A request raises a runtime error	Handle it as a failed request; some failures are raised before a reply object exists. Intent inventory also has a typed policy error.
A reply has no useful output	Check handled, failure_event, and event names before presenting it as an answer. Redact event data before logging diagnostics.

Tip

Unknown display item kinds should be ignored, not treated as fatal. That keeps older clients compatible with newer skills.