Voice sessions: how they run, end, and start from a course button

What a learner sees in a voice session, how it ends, what is charged, and how to start or end a simulation's or coach's session from a Storyline button.

A voice session is a live spoken conversation between a learner and the character of a simulation or a coach. This page describes what the learner sees from start to end, what is recorded and charged, and how to start and end a voice session from your own Storyline buttons. Voice sessions are available on every plan and use credits. To turn voice on and choose its settings, see Setting up voice for a simulation or coach.

Starting a session

A voice simulation opens on a start surface with the heading "Voice Simulation", a microphone button and the line "Tap to start". If the simulation has a start screen, the learner sees that first.

The learner taps the microphone button.
The browser asks for microphone access if the learner has not already allowed it. When the simulation is embedded in a page that does not let it use the microphone, or in a browser where that cannot be checked from inside an embedded frame, such as Safari, the session opens in a separate voice window instead. See Voice simulations on iPhone and iPad.
While the session connects, the learner sees "Connecting..." and "Starting session...", and the microphone button cannot be pressed.
When the simulation is set so the character speaks first and it has a welcome message, the character speaks and the learner's microphone stays off until it finishes. Otherwise the session starts listening straight away.

A coach opened from a voice link shows the same start surface. With Offer text mode on voice links selected, it also shows a Use text control there, so the learner can choose text before any voice session starts. When a learner switches a coach from text to voice, the session starts from that selection with no second tap. See Letting learners switch between text and voice.

During the session

The bar at the top shows the character's name, the session clock next to the session time limit, and an End button.

Taking turns: While the learner's microphone is open the status reads "Listening...". While the character talks, the learner sees the character's name followed by "is speaking" and the status "Mic off". The microphone is off for as long as the character is speaking and opens again a moment after it finishes.
Mute: The learner taps the microphone button to mute, and the status changes to "Muted, tap to unmute". Tapping again unmutes. If the character is still speaking at that moment, the microphone opens when it finishes. The session clock keeps running while the learner is muted.
Microphone button: The button uses the colors from the simulation's or coach's appearance settings. It is dimmed while the session connects and while the character speaks, and turns dark with a red line through it when muted.
Transcript: A Transcript panel lists what was said, labeled "You" and the character's name. When the transcript is set to show by default, the panel opens once the first turn is complete. The learner can select Hide and Show transcript at any time, whatever the default. Each of the character's lines appears in full when the character finishes saying it, and the learner's words appear after they finish speaking.
Silence: In a simulation, if the learner says nothing after the character finishes, the character checks in once, in character, and then waits quietly until the learner speaks. A coach waits without checking in. The session stays open while the learner is quiet, and the clock keeps running.
Time limit: When the clock reaches the session time limit, the session ends.
Turn limit: A simulation's turn limit applies to voice only when you opt in from the voice settings. Each thing the learner says counts as one turn, and the character's welcome is not counted. On the last turn the character replies and wraps up, and the session then ends. See How a simulation ends. A coach's turn limit is not applied in voice.

The session also writes the session start, timer, speaking and completion variables to the course. See Storyline variables a simulation or coach writes.

How a simulation's voice session ends

A simulation's voice session ends when:

The character recognizes one of your end conditions, or the opted-in turn limit is reached. The session ends after the character's closing line has played.
The learner selects End.
The session clock reaches the time limit.
Your course calls endVoiceSession() (described below).

In each case the learner sees "Simulation complete." and the completion variable is set to true. A session the learner ends early is treated the same as any other completed attempt. If evaluation is turned on, "Evaluating your performance..." shows until the result is ready, and the result variables are then written. If the simulation offers another attempt, the Try Again button appears once any evaluation has finished. See Evaluation and scoring.

How a coach's voice session ends

A coach has two kinds of ending:

The session is over: When the learner selects End, or the coach recognizes one of its end conditions, the panel shows "Session complete." and the coach's completion variable is set to true.
The conversation moves to text: When the learner selects Use text, or the session clock reaches the time limit, the learner sees "Returning to chat…" and the conversation continues in text, with the spoken turns included in the thread. On a coach voice link with Offer text mode on voice links cleared, Use text is not offered and a session that reaches the time limit returns to the voice start surface.

If a linked simulation starts while a coach voice session is open, the voice session is closed and the coach posts a notice in the text conversation. See Coach sessions across slides, reloads, and course restarts.

When a session cannot start or loses its connection

Whether the screens below offer text depends on Offer text mode if voice mode disconnects, a setting on the simulation or coach that starts selected. With it cleared, Use text mode is not shown, the wording does not mention text mode, and the learner stays in voice. On a coach the setting applies to voice links: a learner who moved to voice from a text link is always offered text. See Letting learners switch between text and voice.

Microphone blocked: The learner sees "Microphone access was blocked" and "Allow microphone access in your browser, then try again.", with Try again and, when text is offered, Use text mode.
No connection: If the session has not connected after a short wait, the learner sees "Having trouble connecting your microphone." with Try again and, when text is offered, Use text mode. If voice fails with an error before it connects, the conversation continues in text mode. With the setting cleared, the learner sees this screen instead.
Not enough credits, or another start failure: The learner sees "Voice mode isn't available right now" and "This voice session couldn't be started. You can continue in text mode instead." With the setting cleared, the second line is "This voice session couldn't be started. Please try again." and the button is Try Again, which returns to the start surface.
Daily spending cap reached: The learner sees "Daily usage limit reached" and no button to continue, because the cap applies to text as well. See Daily spending caps.
No attempts left: In a simulation with an attempt limit, a learner who has used every attempt sees "No attempts left" and no button to continue.
Connection lost during the session: The learner sees "Connection lost" and the session clock stops. The simulation is not marked complete, and no evaluation runs at that point. The learner can choose:
- Resume session: the conversation continues where it stopped. The character repeats its last line, the clock carries on from where it stopped with a little time handed back for reconnecting, and the turn count carries on.
- Start over: the learner returns to the start surface. In a simulation the transcript is cleared and the next session is a new attempt. In a coach the next voice session opens from the coach's first line again, in the same conversation.
- Use text mode: the learner continues in text. Not offered when Offer text mode if voice mode disconnects is cleared.
On the last attempt of a simulation with an attempt limit, only Resume session is offered.

What is recorded and charged

Credits are held at the start: A session starts only if the workspace balance covers a full-length session at the session time limit. That amount is held when the session starts, and the unused part is returned when it ends.
What is charged: Voice is charged at 120 credits per minute of session time, plus the AI usage of the character's replies. devlin.ai measures session time itself, from the moment the learner starts the session, including the time it takes to connect, until it ends, and never beyond the session time limit. If the end is never reported, time is counted up to the last turn that was saved.
Resumed sessions: Each part of a resumed session is held and charged as its own session.
Closing the page: If the learner closes the page during a session, the session is ended and charged for the time used.
The transcript used for evaluation: Evaluation uses the final transcript of the call when it is available, and otherwise the turns saved during the session. For a resumed session it includes the turns from before the drop.
Sessions that never finished: On a published simulation with evaluation turned on, a session that lost its connection and was not resumed, or whose page was closed, can still be evaluated afterwards for your results. The learner does not see that result in the simulation.

For balances and usage history, see Credits and usage.

Start and end a voice session from a course button

In Articulate Storyline you can start and end a voice session from your own buttons, so learners do not have to use the controls inside the simulation or coach. This works for simulations and for coaches.

When voice is turned on for a simulation, the Publish stage shows Optional: Start and End Voice Sessions from Course Buttons in the Storyline 360 section. A coach's Publish stage does not show this block, and the same two functions work for it.

The slide must already hold the voice simulation or coach in a Web Object and the JavaScript trigger from the Storyline setup, because that trigger loads the script that provides these functions. See Embedding a simulation in Articulate Storyline.

Add an Execute JavaScript trigger to a button, with one of these lines as its code:

startVoiceSession() starts the session.
endVoiceSession() ends the session.

If one slide holds more than one simulation or coach, pass the embed key in quotes to target one of them, for example endVoiceSession("your-embed-key"). Without a key:

On a slide with simulations only or coaches only, the command is sent to each of them.
On a slide that holds both a simulation and a coach, the command is sent to the simulations only. A simulation that goes live closes a coach's voice session, so starting both would end the coach's session at once. To command the coach on such a slide, pass the coach's embed key.

The command is not sent to evaluators or to frames from other sites.

What `startVoiceSession()` does

It does the same thing as the learner tapping the microphone button. If the simulation's start screen is showing and asks the learner for nothing, the start screen is closed first. If the start screen asks for a learner identifier or a required identity field that has not been given yet, the command is refused: the start screen stays, and the learner fills it in and starts from there. If the start screen was closed and the session then cannot start, the start screen comes back.

The command is accepted only when the simulation is in voice mode and waiting to start: on the start surface, or on the microphone-blocked or connection-trouble screens. It does nothing while a session is connecting or live, so a second click cannot restart a running session. It also does nothing after the session has ended. For another attempt, the learner uses Try Again in the simulation, or your course calls restartSimulation().

A coach accepts the command under the same conditions, and only while its voice screen is the one showing: on a voice link, or after the learner has moved to voice. A coach showing its text conversation does not start voice from this command. A coach also refuses it while a linked simulation is running and after the coach session has ended. A coach's start screen asks the learner for nothing, so an accepted start closes it.

What `endVoiceSession()` does

For a simulation it does the same thing as the learner selecting End: the session wraps up, the completion variable is set, the evaluation runs if it is turned on, and the results are written to your Storyline variables.

For a coach it does the same thing as the learner selecting Use text: the voice session closes and the conversation continues in text. It does not end the coach session and does not set the coach's completion variable. On a coach voice link with Offer text mode on voice links cleared, the coach returns to the voice start surface.

While a session is still connecting, the command cancels the start: the session does not go live, the learner is back on the start surface, and nothing is evaluated. It does nothing when no session is connecting or live.

Browsers that need a tap in the simulation

The button the learner clicks is in your course, not inside the simulation, and some browsers only start voice from a tap inside the simulation itself.

In Chrome and Edge the session usually starts right away. The learner may see the browser's microphone prompt.
Safari needs a tap inside the simulation. After your trigger runs, the session does not start, and the simulation stays on its start surface with "Tap to start". The learner taps the microphone button in the simulation, a separate voice window opens, and the learner selects Start voice session there. The window is described in Voice simulations on iPhone and iPad.

Leave the simulation visible on the slide and tell learners to tap its microphone button if the session does not start. endVoiceSession() does not depend on a tap.

Where the functions work

A simulation or coach accepts these commands only from the page that directly contains it. If it sits inside another frame between it and the page that calls the function, the command is ignored.

Each function returns true when it sent the command to at least one simulation or coach on the page (with a key: the one with exactly that embed key), and false when it sent none. It sends only to simulations and coaches served from the same site as the script the JavaScript trigger loads, with or without www. A true does not mean the command was accepted. The simulation or coach answers a command with a browser message of type SIM_CONTROL_ACK, with a command of voice-start or voice-end and an accepted value of true or false, which your own script can listen for. A simulation's answer to a start can take a few seconds while it loads, and repeated start calls in that time get a single answer.