How to embed in your system

Backend issues a short-lived token; frontend calls OralEmbed.mount; completion follows the API.

oraldeveloper

Audience: integrating developers · Applies to: DodoSpeak Oral

Goal: Embed practice / tasks / History / exams in your pages along a fixed path.

Prep: What to prepare before you start. Compare paths: Two formal embed methods. Scores and History: How to get exam scores and view records. For a live sample, sign up on the website, log in to Oral Console (default Manager — set embed method and roster in Organization profile), then switch to Developer and open How to embed.

Fixed path

Provision a tenant and receive a tenant key (backend only).
When a learner opens your page, your backend POST /api/v2/oral/embed-sessions and receives a short-lived embed token.
The frontend passes that token to OralEmbed.mount with a surface (practice / assignment / report / exam).
After the learner speaks or finishes an exam, your backend confirms completion and usage via Oral API (or a webhook).

The browser holds only the short-lived token, never the tenant key.

Where to look (Lab)

Oral Console → switch to Developer → sidebar How to embed: three steps (copy the key, allow your site, mint then mount). That is a sample, not a product you must clone.

Frontend mount (sketch)

<div id="oral"></div>
<script src="https://(embed-script-host)/oral-embed.js"></script>
<script>
  OralEmbed.mount("#oral", {
    token: window.__ORAL_EMBED_TOKEN__,
    surface: "practice",
    locale: "en",
    onCompleted: function () {
      /* confirm completion with your backend */
    }
  });
</script>

token must come from your backend. Script URL and API base come from your onboarding pack.

Surfaces and plans

All four surfaces stay listed. If the plan does not include a surface, the API rejects the request (typically unauthorized). Do not hide buttons by plan.

Surface	Purpose	Typical plan floor
Practice `practice`	Speak	Lite
Tasks `assignment`	Complete published tasks	Class
History `report`	View results (same idea as SaaS student History)	Assess
Exams `exam`	Formal exam	Exam

Details: Plans, entitlements, and usage.

How to confirm success

The embed UI appears; after mic permission the learner can speak.
Your backend can load the matching session / completion record.
A surface below the plan is rejected by the API, not missing from the UI.

Common failures