Viibe SDK

Viibe SDK allows to display a call iframe directly within your host application.

The call iframe allows to

• initiate a call
• schedule a call
• display past sessions

Constructor

const viibe = new Viibe({host, source})

Options

host (string, mandatory)

The ViiBE subdomain you want to display.

i.e : example.viibe.pro

source (string, mandatory)

The source where your want to integrate ViiBE.

The source will be added to the created ticket for reference.

i.e: example

Create a Call

⚠️ You will need a ViiBE token to display our iframe without login step.

viibe.createCallIframe(options): HTMLElement

This method will create an iframe element which will display a initialization call page of your viibe subdomain. The iframe should be appended to the host application's DOM.

viibe.createCallURL(options): string

The method will generate the URL to the call page (used by createCallUrl ). The host application can use this URL to display the call frame in a popin or modal instead of an iframe.

Options

Both above methods support the same options:

links[] (array, optional)

The list of contacts to add to the call. The contacts are only prefilled and can be removed by the user before initiating the call. Other contacts can be added by the user via an input.

Each item is an object with the following format:

category (string, mandatory)

The type of contact (email, expertise, or phone)

value (string, mandatory)

The contact itself;

• for email category, should be a valid email
• for phone category, should be a full phone number (including national prefix)
• for expertise category, should be an id_expertise

suggestions[] (array, optional)

A list of suggested contacts to call. Each item is an object with the following format:

category (string, mandatory)

The type of contact (email or phone)

value (string, mandatory)

The contact itself;

• for email category, should be a valid email
• for phone category, should be a full phone number (including national prefix)

description (string, optional)

An optional text to add information about the contact (his name for example). Displayed between brackets after the value field.

ticket

Represents the host application entity the call will be attached to. Viibe calls should typically be attached to a ticket, conversation or issue within the host application

integration

id (string, mandatory)

The external ID corresponding to ticket

title (string, optional)

The ticket title (will overwrite any existing ticket title)

token (string, optional)

A valid Viibe JWT token. If none is provided or the token is invalid, a authentication:error event will be triggered, and a "Login" button will be displayed within the iframe.

locale (string, optional)

An ISO 639-1 language code.

components (array, optional)

A list of visible components among call, schedule and session (example: ['call','schedule'])

o2m (boolean, optional, default = false)

Whether or not the user can call an expertise (i.e. a group of experts)

clipboard (boolean, optional, default = false)

If true, the user won't be able to edit the list of callees (links)

Authentication

While the iframe should contain a "Login" button if you don't pass a token or your token is invalid, the Viibe SDK allows to open an authentication popup to obtain a Viibe JWT token to be passed to the call iframe:

viibe.authenticate(provider): Promise<string>

The provider param depends on the third-party authentication methods setup for your Viibe domain.

Events

The host application can register event listeners to react to events occuring in the call iframe

viibe.on(event, handler)

handler will receive the event emitted by the call iframe

Supported events

• event resize
• handler payload {height: number}

Triggered when the height of the iframe content changes. The host app should likely resize the iframe to the appropriate size

• event click:session
• handler payload {uuid: string, slug: string}

Triggered when the user clicks on a past session. The host app may open a modal or popup to display the session {host}/session/{uuid}/{slug}

• event click:call
• handler payload {uuid: string, slug: string}

Triggered when the user clicks on an ongoing call. The host app may open a modal or popup to join the call ({host}/call/{slug}/{uuid})

• event authentication:error
• handler payload: error: string

Triggered when the user is not authenticated. The host app may display a login button in place of the iframe (api-{host}/auth/login/{provider}). Otherwise the iframe should display a "login" button with username / password method

• event authentication:token
• handler payload: {token: string}

Triggered when the user was successfully authenticated from an authenticate() call, or when the authentication token has changed within the app

Example

viibe.on('authentication:error', (error) => {
  console.log('authentication:error', error)
  if (error === 'not authenticated') {
    element.innerHTML = '';
  }
});

viibe.on('click:session', (event) => {
  console.log('click:session', event)
});

viibe.on('click:call', (event) => {
  console.log('click:call', event)
});

viibe.on('resize', (event) => {
  console.log('resize', event)
});

Iframe API

Global Query Parameters

Dev note: to be handled globally, either in integration boot or in IntegrationLayout

• locale (string, optional) : language to display the app into (e.g. fr-FR)
• source (string, optional) : identifier for the host application (e.g. zendesk, mdynamics, salesforce)
• token (string, optional) : a Viibe token to authenticate the user

Legacy intercom parameters

To be kept for backward compatibility, but should be isolated to the postMessage module

• uuid (string) : the UUID of the iframe, typically generated by viibe.js for interframe com
• data (boolean) : whether the host page will send initial postMessage data to the frame
• resize (boolean) : whether the frame should emit postMessages when its content changes size

Call Parameters

Dev note: to be handled at component level via a vue-router router

The "call feature" is actually attached to a ticket, and allows to create, renew or schedule calls within this ticket

Ticket identifier

Tickets displayed in integration iframes are usually identified by the host id (or thirdPartyId). Either of the following params must be present.

• thirdPartyId (string) : an identifier of the host ticket to attach the Viibe ticket to (currently via [ticket.integration.id](http://ticket.integration.id))
• slug (string) : a viibe ticket slug (currently not supported)

Call modifiers

The following parameters are passed from the host to the iframe to alter the current ticket

• title (string, optional) : the title of the ticket, saved to the viibe ticket every time a call is created or scheduled.
• links (array, optional) : a list of links to display in the "call" and "schedule" forms (i.e. to be added to the associated session on "call", "renew" or "schedule"). The array values are separated by comma (,) where each value has a category (e.g. email, phone, username, expertise, ...) and a value separated by a colon (example: links=email:[email protected],username:charles,phone:+3361867999999)

UI options (call feature only)

• components (array, optional): a list of strings indicating the UI components to enable among "call", "schedule" and "session" (default: all, example: components=call,schedule,session)
• clipboard (boolean, optional): controls whether the "smart input" to add new links is visible or not
• o2m (boolean, optional) : controls whether the user can make one-to-many calls (i.e. can call expertises)