A duo role-play

A duo is two people in one live conversation: a couple buying a home, a buyer and their finance director. By the end of this guide your team practises with one.

You need: a plan that includes duos, and the Node SDK.

1. Check you can use duos#

duo-role-play.ts

const access = await zentiq.getDuoAccess();
// builderOpen: duos are open to the organisation (until then every other duo operation is 404).
// canUse: the plan includes ready-made duos; upgrade names the plan that would, in words to show.
if (!access.builderOpen || !access.canUse) throw new Error(access.upgrade?.message ?? "Duos aren't open to this organisation yet.");

While duos aren't open to your organisation, every other duo operation answers 404; upgrade names the plan that would add what is missing, in words you can show.

GET/v1/duos/accessWhat the organisation may do with duosduos:read

2. Add a duo from the library#

duo-role-play.ts

const library = await zentiq.listDuoLibrary();
console.log(library.map((d) => `${d.key}: ${d.title} (${d.scenario ?? d.relationship})`)); // second_viewing: Mark & Susan (…)
const duo = await zentiq.createDuo({ source: "library", libraryKey: library[0].key }).catch((e: unknown) => {
  // A duo counts as a custom avatar: at the plan's limit, e.plan names the plan that lifts it.
  if (e instanceof UpgradeRequiredError) throw new Error(`Upgrade to ${e.plan} for another duo.`);
  throw e;
});

POST/v1/duosAdd a ready-made duoduos:write

The new duo is a draft, with a persona of its own named after both people ("Mark & Susan"). Only a duo is two people: giving a persona a name with an "&" doesn't make one.

3. Publish it#

Zentiq checks the pair renders well before anyone meets them. Publishing starts that check; the duo becomes live when it passes, or needs_changes with what to fix.

duo-role-play.ts

await zentiq.publishDuo(duo.id);
// Zentiq test-renders the pair first: this waits until it is live (a duo that needs changes throws, with its problems).
const live = await zentiq.waitUntilReady("getDuo", duo.id, { timeoutMs: 10 * 60_000 });

POST/v1/duos/{id}/publishPublish a duoduos:write

4. Use it#

duo-role-play.ts

// A practice portal around the duo…
await zentiq.createPortal({ name: "Home buyers practice", templates: ["duo-home-buyers"], personaId: live.personaId });

// …or a session in your own app. The token's persona is named "A & B": the browser SDK reads the two names from it.
try {
  const token = await zentiq.createSessionToken({ personaId: live.personaId, language: "fr" }); // a duo speaks ten languages
  console.log(token.persona.name);
} catch (e) {
  if (e instanceof DuoNotLiveError) console.log("Publish the duo first.");
  else throw e;
}

Before the duo is live, a portal or a session with it is refused (409 duo_not_live for a session).
A duo speaks fewer languages than one avatar: GET /v1/languages marks them with duo: true.
In the browser, the SDK names who is speaking in the captions: Browser.
A duo's persona is changed in the console's duo studio, not with PATCH /v1/personas/{id} (409 conflict, with details.reason duo_studio_only).