Integration

Prerequisites

To render the Widget for your study, you need at least:

• A studyId
• A supported locale

All of these are provided by Trialbee.

Install the Widget

Place the container where the chat should appear, configure it with data-* attributes and load the widget script. No CSS file or API key is needed.

index.html

<!-- Trialbee chatbot — place the container where the chat should appear -->
<div
  id="chatbot-widget-container"
  data-studyid="YOUR_STUDY_ID"
  data-locale="en_US"
  data-landingpage="https://your-study-site.example/landing"
></div>
<script src="https://chatbot-widget.trialbee.com/chatbot-widget.iife.js"></script>

The container must have the exact id chatbot-widget-container.

tip

Serve the page over https. The conversation cookie is only marked Secure on https.

Attribute reference

Attribute	Required	Description
data-studyid	Yes	Study ID provided by Trialbee. The study's chatbot prescreener must be published, otherwise the chat cannot load.
data-locale	No	Locale of the conversation, default en_US. Must match a locale the prescreener is published in.
data-landingpage	Recommended	Full URL of the page hosting the widget. Used as the base URL for resume links and as the source of the referrer token.
data-trackname	No	Selects a questionnaire track. Only meaningful when the study has tracks configured.
data-initialphase	No	screening (default) starts with the first screening question. pre-assessment starts in a free-chat phase where the applicant can ask about the study first.
data-manuscriptmode	No	For studies with a secondary screening: ai (default) lets the AI conduct the interview.

What you receive from Trialbee

Item	Description
Study ID	Identifies the study the applicant is applying to.
Locales	The locales the study's prescreener is published in.
Track names	Only if the study uses several questionnaire tracks.
Referrer tokens	One per recruitment partner or campaign, if used.

Tracks

A study's prescreener can have several tracks, which are variants of the questionnaire. Set data-trackname to the exact track name provided by Trialbee to start the conversation on that track. If the study has no tracks, omit the attribute.

<div
  id="chatbot-widget-container"
  data-studyid="TBX1"
  data-locale="en_US"
  data-trackname="social-media"
  data-landingpage="https://my-study.com/landing"
></div>

Referrer tokens

The referrer token ties an application to a recruitment partner or campaign. There is no data-* attribute for it. Instead, the widget reads a referrerToken (or ref) query parameter from the data-landingpage URL and strips it from the stored URL.

So a campaign link like https://my-study.com/landing?referrerToken=XYZ works as long as your page passes its own URL as data-landingpage:

<script>
  document
    .getElementById('chatbot-widget-container')
    .setAttribute('data-landingpage', window.location.href);
</script>
<script src="https://chatbot-widget.trialbee.com/chatbot-widget.iife.js"></script>

Avoid personal information in the landing page URL. It is stored as-is and not anonymized. See Candidate Privacy.

Query parameters

If the container has no data-studyid, the widget reads the same configuration from the page URL's query string instead. This is mainly useful for test and preview pages.

https://my-study.com/preview?studyId=TBX1&locale=en_US&trackName=social-media

Query parameter	Maps to
studyId (required)	data-studyid
locale	data-locale
landingPage	data-landingpage
referrerToken	Referrer token (here it is its own parameter)
trackName	data-trackname
phase	data-initialphase
manuscriptMode	data-manuscriptmode

When both are present, data-initialphase and data-manuscriptmode on the container take precedence over the query parameters.

Resume links

When an eligible applicant submits their contact details and the study continues into a secondary screening, Trialbee emails them a resume link. The link is your landing page URL plus a resumeToken query parameter:

https://my-study.com/landing?resumeToken=…

When the applicant opens it, the widget exchanges the token for the conversation, opens the chat and removes the token from the URL. If your page has not created the container yet, the widget mounts its own container.

The URL you pass as data-landingpage must keep serving a page that loads the widget script, otherwise resume links break. If no landing page is set and the referrer or current URL is not usable either, no resume email is sent.

The resumeToken grants access to the applicant's conversation, so treat it as a secret.

How the conversation works

Every phase renders inside the same chat transcript. The badges on each phase say who drives it: the AI, or the deterministic flow that controls the questionnaire and eligibility.

1. Pre-assessment

AI optional

Only when the customer embeds the widget with the pre-assessment starting phase. The chatbot introduces itself as an AI assistant that cannot give medical advice or guarantee eligibility, and invites questions about the study. When the applicant says they want to start, the chatbot hands over to the questionnaire. Otherwise the conversation starts directly at step 2.

2. Screening

Deterministic

The prescreener questions appear one at a time as chat bubbles with the right control for each type: yes/no, single or multiple choice, dropdown, number, date of birth, gender, free text. Branching (visible-if) applies exactly as in the form widget. Answered bubbles collapse and can be edited. A recap bubble asks the applicant to confirm before submission. The free-text box stays open throughout so the applicant can ask the chatbot anything.

3. Eligibility outcome

Deterministic

The questionnaire service evaluates the eligibility rules of the prescreener and the consent questionnaire. Eligible applicants see the configured eligible message and continue. Ineligible applicants see the not-eligible message and the chat conversation stops for them.

4. Contact details and consents

Deterministic

The contact form fields configured for the study (by default name, email with confirmation, phone, preferred contact hours) are asked one by one, followed by the consent questions. Personal data stays in the browser until the applicant confirms the whole batch, so nothing personal reaches Trialbee before data consent is given. Email and phone are validated before sending.

5. Secondary screening

AI Deterministic optional

Only when the study has a published manuscript with presenter set to Chatbot. If the study also has a manuscript for human callers, the applicant is asked how they prefer to continue: "I want to be called by a human" or "I want to continue the chat". Trialbee emails a resume link at this point so the applicant can come back within 14 days.

In AI mode the chatbot conducts the interview in free text, following the phone script, records the answers, recaps them and asks for confirmation before submitting. During the interview the chatbot finds the closest study sites from a postal code or city and assigns one. A disqualifying answer ends the interview the way a human caller would.

6. Completion

Deterministic

The applicant sees the configured completion message. After that, the message names the assigned site and says the site will call. Applicants who chose the human call are told which number will call them. The chat stays open for further questions.