A multilingual assistant

By the end of this guide one assistant answers each customer in their own language, from help centres written in several, and your app can switch a live session from one language to another.

You need: a key with personas:write, knowledge:write, portals:write, content:write and sessions:write (the Website assistant preset has most of them), and the Node SDK.

1. The languages#

multilingual-assistant.ts

const catalogue = await zentiq.listLanguages();
console.log(`${catalogue.languages.length} languages`);
const forDuos = catalogue.languages.filter((l) => l.duo).map((l) => l.name); // the ones a duo speaks

GET/v1/languagesThe languages avatars speak, the voice engines and the accent keys

Every language is given by its code (es, pt-BR), or its English name on input.

2. A persona that follows the person's language#

multilingual-assistant.ts

const lucia = await zentiq.createPersona({
  name: "Lucía",
  systemPrompt: "You are Lucía, Acme's support assistant. Answer from the help centre.",
  settings: { language: "es", languageMode: "follow" }, // starts in Spanish, then follows the person's language
});

follow answers each person in the language they speak; fixed keeps the persona's language whatever they use.

3. Knowledge in each language#

multilingual-assistant.ts

const es = await zentiq.createKnowledgeBase({ name: "Help centre (ES)" });
const fr = await zentiq.createKnowledgeBase({ name: "Help centre (FR)" });
await zentiq.createDocument(es.id, { url: "https://www.acme.example/es/ayuda" });
await zentiq.createDocument(fr.id, { url: "https://www.acme.example/fr/aide" });
await zentiq.updatePersona(lucia.id, { knowledge: { baseIds: [es.id, fr.id] } });

4. FAQs asked every way#

On a website assistant, each FAQ can list the ways people ask it in other languages:

multilingual-assistant.ts

const desk = await zentiq.createPortal({ name: "Acme Front Desk", templates: ["receptionist"] });
await zentiq.updateSubjectContent(desk.subjects[0].id, {
  set: {
    faqs: [{ q: "What are your opening hours?", a: "Nine to five, Monday to Friday.", ask: ["¿Cuál es su horario?", "Quels sont vos horaires ?"] }],
  },
});

5. The website assistant's rule for visitors#

A website subject answers each visitor in the language they use (visitorLanguage: "follow", the default). Keep it to the subject's own languages with listed, or to English with english; null goes back to your organisation's own setting. It changes what the next conversation does straight away, with no new version to publish:

PATCH/v1/subjects/{id}Change a subjectcontent:write

visitorLanguage on a subject that isn't a website assistant, or one your organisation has locked in Settings, is 409 conflict.

6. Switch languages during a session#

multilingual-assistant.ts

const token = await zentiq.createSessionToken({ personaId: lucia.id, language: "fr" });
await zentiq.steerSession(token.sessionId, { language: "de" }); // from the next turn, in German
await zentiq.sessionSay(token.sessionId, { text: "Un momento, por favor.", language: "es" }); // one line in Spanish
try {
  await zentiq.sessionSay(token.sessionId, { text: "Hello", language: "xx" });
} catch (e) {
  if (e instanceof InvalidRequestError) console.log(e.param, e.message); // names GET /v1/languages
}
await zentiq.endSession(token.sessionId);

A language that isn't in the catalogue is 400 invalid_request, naming GET /v1/languages.

7. The words of your own sessions#

For sessions your app starts, the words can come back turn by turn: name transcript.final in a webhook made with includeConversation (by a key holding transcripts:read).

multilingual-assistant.ts

// The words of your own app's sessions, turn by turn: only when you ask for them, on a key allowed to read them.
await zentiq.createWebhook({
  url: "https://support.acme.example/zentiq/turns",
  events: ["transcript.final"], // must be named: "*" never includes it
  includeConversation: true,
});