API Snap Conversation

Caligrafy\Snap\Conversation

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

Part of Snap.

namespace Caligrafy\Snap;

class Conversation

Source: framework/core/Snap/Conversation.php:19

The Snap shell's two spaces (2.23.0):

Home       the starting workspace: the agent's message for the situation, prompt suggestions (and "What else can
           I do"), the input; then the cards: Needs you (alerts, tasks waiting on you, changes to confirm),
           For you (offers), In progress (tasks), Shortcuts. Only the sections that have something.
Task space the engagement: the conversation minimized to the agent's latest answer (back and forth, history,
           rating, a different answer, the input on demand); only the cards of that answer.

Each turn is kept (snap_turns): what was asked, the caption, the cards, the suggestions, how it was answered.

Constants

• TABLE = 'caligrafy_snap_turns'
• MORE = 'What else can I do?'
• HOME = 'Back to Home'

Methods

• Conversation::installed()
• Conversation::save()
• Conversation::turns()
• Conversation::last()
• Conversation::history()
• Conversation::rate()
• Conversation::memory()
• Conversation::suggestions()
• Conversation::empty()
• Conversation::lower()
• Conversation::home()
• Conversation::open()
• Conversation::needs()
• Conversation::insights()
• Conversation::progress()

Conversation::installed()

public static function installed()

Whether Snap's tables are there (php caligrafer.php platform install): checked once per request

Source: framework/core/Snap/Conversation.php:28

Conversation::save()

public static function save(Context $context, $conversation, $text, array $answer)

No doc comment.

Parameters

• $context Context
• $conversation
• $text
• $answer array

Source: framework/core/Snap/Conversation.php:44

Conversation::turns()

public static function turns(Context $context, $conversation)

No doc comment.

Parameters

• $context Context
• $conversation

Source: framework/core/Snap/Conversation.php:52

Conversation::last()

public static function last(Context $context, $turnId)

No doc comment.

Parameters

• $context Context
• $turnId

Source: framework/core/Snap/Conversation.php:74

Conversation::history()

public static function history(Context $context, $limit = 20)

This person's conversations, newest first: their first question is their title

Parameters

• $context Context
• $limit, default 20

Source: framework/core/Snap/Conversation.php:86

Conversation::rate()

public static function rate(Context $context, $turnId, $rating)

No doc comment.

Parameters

• $context Context
• $turnId
• $rating

Source: framework/core/Snap/Conversation.php:103

Conversation::memory()

public static function memory(Context $context, $conversation, $sent)

The conversation's memory for the next ask: its earlier turns (what was asked, what was shown), what is on the person's screen now, what they chose since (opened, picked, confirmed), and what it is about (the focus: "it"). What the page sends is checked and cut to size; it is the person's own context, and the planner is told it is data from the app, never instructions.

Parameters

• $context Context
• $conversation
• $sent

Returns array: ['focus' => array|null, 'text' => string] (text empty: nothing to remember)

Source: framework/core/Snap/Conversation.php:121

Conversation::suggestions()

public static function suggestions(array $cards, Context $context)

What the person may want to do next, beyond the buttons of the cards on screen: the optional details a form still takes, what follows a change (another one, the list it belongs to), what a list leads to, then "What else can I do?". Each suggestion carries what it runs, so a click is at once a card, without a model.

Parameters

• $cards array
• $context Context

Source: framework/core/Snap/Conversation.php:174

Conversation::empty()

public static function empty(array $card)

No doc comment.

Parameters

• $card array

Source: framework/core/Snap/Conversation.php:232

Conversation::lower()

public static function lower($text)

No doc comment.

Parameters

• $text

Source: framework/core/Snap/Conversation.php:324

Conversation::home()

public static function home(Context $context)

Home, for this person, now: an orchestrator of what to concentrate on, in this order:

Needs you      alerts, tasks waiting on the person, changes to confirm (the focus)
insights       numbers, each with the action it calls for (none without one)
For you        offers (what they usually do now, routines)
In progress    running tasks
discover       the things this app is about, to browse: more like what they looked at, new, available
Just done, Your shortcuts

The message says the focus and nudges the conversation on; the suggestions start with the focus's action and a pick to look at. One card per capability (the latest task of a capability is its only card) and per object. Each card carries its key: opening it (snap_ask open) shows it in the task space.

Parameters

• $context Context

Source: framework/core/Snap/Conversation.php:343

Conversation::open()

public static function open(Context $context, $key)

A Home card opened in the task space, by its key: a shortcut runs what it saved; anything else is shown in full, with the assistant's line

Parameters

• $context Context
• $key

Returns array: the answer: caption, cards, via, text

Source: framework/core/Snap/Conversation.php:436

Conversation::needs()

public static function needs(Context $context, ?array $tasks = null)

Needs you: alerts (a hint 'alert' on a read capability whose rows carry a flag), tasks that wait on the person (needs your answer, could not finish), routines waiting for their confirm. Each one carries its next step.

Parameters

• $context Context
• $tasks ?array, default null

Source: framework/core/Snap/Conversation.php:481

Conversation::insights()

public static function insights(Context $context)

Insights: numbers that call for something. One per read capability with an 'insight' hint, shown only when there is something to act on (a count above zero) and this person may take its action; each carries that action.

'insight' => array('label', 'icon', 'action' => array('capability', 'text'),
                   'since' => array('field', 'days')?   count only what was added lately
                   'ring' => array('of', 'label', 'invert')?)   and a share of another count

Parameters

• $context Context

Source: framework/core/Snap/Conversation.php:535

Conversation::progress()

public static function progress(Context $context)

The person's progress: what they got done today through the app, and how many days in a row they did something (from Caligrafy's audit log: their successful changes; the assistant's own bookkeeping is left out)

Parameters

• $context Context

Source: framework/core/Snap/Conversation.php:582