Documentation Hub

Appearance

Web Services: 3rd Party Clients ​

Your own client application can connect to the Dialogue Branch Web Service directly, without going through the BFF used by Dialogue Branch Studio. This page walks through a typical workflow for such a "direct API client".

JavaScript: @dialoguebranch/client-js ​

If your client is JavaScript-based, you may not need to hand-roll the workflow below at all. @dialoguebranch/client-js's default export, DialogueBranchClient, is a playback-only client for exactly this scenario — running dialogues against a Web Service from outside Dialogue Branch Studio — with no framework dependency, so it runs in a browser, Node, or (in principle) React Native. (The package also ships DialogueBranchAuthoringClient, at its ./authoring subpath, for project/dialogue authoring — that's what Dialogue Branch Studio itself uses; a playback-only consumer never needs it.) It lives at packages/client-js in the platform monorepo, is published as plain ESM with no build step required, and its constructor takes the transport (a fetch implementation, credentials mode, and hooks for attaching auth, logging calls, and handling a 401) as options rather than assuming a particular environment.

Install from npm

@dialoguebranch/client-js is published to the npm registry with every release, at the same version as the Web Service: npm install @dialoguebranch/client-js. Dialogue Branch Studio itself consumes it as a local dependency within the monorepo.

Authenticating ​

Authenticate the user directly with Keycloak, using the Authorization Code + PKCE flow, to obtain an access token, then include it in the header (name: Authorization, value: Bearer <your-access-token>) for all subsequent calls to the Web Service. See Direct API Clients for the full explanation.

Dialogue Execution ​

A typical workflow for a client application interacting with the Web Service is a follows:

  1. Authenticate the user directly with Keycloak (Authorization Code + PKCE flow) to obtain an access token — see Authentication.
  2. Include the access token in the header (name: Authorization, value: Bearer <your-access-token>) for all subsequent calls to the Web Service.
  3. Start the execution of a dialogue, by calling the /dialogue/start end-point, providing projectSlug, dialogueName, language and timeZone.
  4. Render the resulting JSON object (a DialogueMessage) as a dialogue user interface to the user, and store the loggedDialogueId and loggedInteractionIndex.
  5. When the user selects a reply, call the /dialogue/progress end-point, providing the previously memorized loggedDialogueId and loggedInteractionIndex, as well as the selected replyId.
  6. The result is a JSON object with the same structure as received in step 4, which can again be rendered, repeating the process.

Sequence diagram for a typical User to Client to Server scenario of authenticating and executing dialogues with the Dialogue Branch Web Service

The /dialogue/* end-points also support resuming an interrupted session (/dialogue/continue, /dialogue/get-ongoing), reverting to a previous step (/dialogue/back), explicitly ending a session (/dialogue/cancel), and (for users with the editor or admin role) listing all dialogues available in a project (/dialogue/list-dialogues). See the Swagger UI for the full set of parameters for each end-point.

Working with Variables ​

Your client can set and retrieve Dialogue Branch Variables via the /variables/* end-points — see Working with Variables on the API Service page.

Acting on Behalf of Other Users ​

If your "client" is a server-side component that serves many end users, let each end user authenticate, and forward their own access token to the Web Service with each request made for them. Don't use one admin account to act for all of them through delegateUser: that parameter is meant for an administrator's testing and support work, and acting through it changes the other user's real data. See Acting on behalf of another user on the Authentication page.

Note

If you found errors or have questions about this page, please consider reporting an issue at https://github.com/dialoguebranch/platform or sending an email to info@dialoguebranch.com.