Symphony Messaging Dev Docs
Developer CertificationREST API
  • Start Your Developer Journey
  • Bots
    • Building Bots
    • Planning Your Bot
      • Conversational Bot
      • Interactive Bot
      • Headless Bot
    • Getting Started
      • Getting Started with BDK
      • Creating a Service Account
      • Configuration
      • Truststores
    • Overview of REST API
      • REST API Architecture
      • Overview of Pod API
      • Overview of Key Manager API
      • Overview of Agent API
      • Bot Permissions
      • REST API Reference
    • Authentication
      • RSA Authentication Workflow
      • Certificate Authentication Workflow
    • Datafeed
      • Real-Time Events
      • Overview of Streams
    • Messages
      • MessageML
        • MessageML Basics
          • Content Grouping
          • Text formatting and semantics
          • Tables
          • Images
          • Tags and mentions
            • Enhanced tags notice
          • Style Attributes
          • Special Characters
          • Emojis
        • Elements Interactive Forms
          • Buttons
            • Icon set for Buttons
          • Text Field
          • Masked Text Field
          • Text Area
          • Checkbox
          • Radio Button
          • Dropdown Menu
          • Person Selector
          • Room Selector
          • Date Picker
          • Time Picker
          • Timezone Picker
          • Table Select
          • Regular Expressions - Regex
        • Extensibility UI Actions
          • OpenChat
          • Dialog
        • Entities
          • Standard Entities
          • Custom Entities
      • PresentationML
    • Bots Best Practices
    • Open Source Code Samples
  • Extension Apps
    • Building Extension Apps
    • Planning Your App
    • Getting Started
      • Getting Started with ADK
      • Application Manifest Bundle
      • Add an Extension App to a Symphony Pod
    • Overview of Extension API
      • Initialization
      • Register and Connect
      • Extension API Services
        • Service Interface
        • Register and Subscribe
        • Modules Service
        • Entity Service
          • Entity Advanced Templating
          • Message Format - ExtensionML
        • Applications-Nav Service
        • Share Service
        • Commerce Service
        • Dialogs Service
        • UI Service
          • Receiving Conversation and User Information
          • Filter Function
    • App Authentication
      • Circle of Trust Authentication
      • OBO Authentication
  • Developer Tools
    • Symphony Messaging Generator
    • Bot Developer Kit for Java
      • Build a Conversational Bot
      • Build an Interactive Bot
      • Build a Headless Bot
      • Integrate a Bot with an Identity Provider
    • Bot Developer Kit for Python
    • App Developer Kit
      • Build a Basic Extension App
      • Build an Extension App with App Views
        • Add Buttons and Handlers to an Extension App
        • Add BDK to an Extension App for Circle of Trust
      • Build an Extension App with Message Renderers
    • Postman
    • UI Style Guide
      • Colors
      • Form Elements
      • Buttons
  • Embedded Modules
    • Symphony Messaging URI
      • Symphony Messaging URI for Mobile (deprecated)
    • Desktop interoperability
      • FDC3 intents
        • Message format
      • Configuration guide
        • Configure Interop.io
        • Configure Here Core
        • Configure Finsemble
        • Configure with Embedded Mode
        • Troubleshooting
      • Change log
    • Embedded Mode
      • Get started
      • Configuration parameters
      • Open a chat
      • Send a message
      • Create a room
      • Pin a message
      • Notifications
      • Support for extension applications
      • Open an app
      • Embedded Mode with Sponsored Access
      • Pricing tiers
      • Logout
    • Universal Webhook
      • User guide
        • Example with Splunk
      • Installation guide
  • Symphony REST API
    • Messaging REST API
    • Federation
    • Sponsored Access API
    • Enhanced Directory API
  • Developer Certification
    • Developer Certification
  • Mobile Frameworks
    • Blackberry
    • MobileIron
  • Admin Guides
    • Change Logs
      • API Agent
        • Agent - 25.5
        • Agent - 25.3 (LTS)
        • Agent - 24.12 (LTS)
        • Agent - 24.9 (LTS)
        • Agent - 24.6 (LTS)
        • Archives
          • Agent - 24.11
          • Agent - 24.10
          • Agent - 23.9 (LTS)
          • Agent - 24.8
          • Agent - 24.3 (LTS)
          • Agent - 24.2
          • Agent - 24.1
          • Agent - 23.12 (LTS)
          • Agent - 23.11
          • Agent - 23.10
          • Agent - 23.7
          • Agent - 23.6 (LTS)
          • Agent - 23.4
          • Agent - 23.3 (LTS)
          • Agent - 23.1
          • Agent - 22.12 (LTS)
          • Agent - 22.11
          • Agent - 22.10
          • Agent - 22.9 (LTS)
          • Agent - 22.8
          • Agent - 22.7
          • Agent - 22.6 (LTS)
          • Agent - 20.14
          • Agent - 20.13
          • Agent - 20.12
          • Agent - 20.10
          • Agent - 20.9 (2.62)
          • Agent - 20.7 (2.61)
          • Agent - 20.6 (2.60)
          • Agent - 20.5 (2.59)
          • Agent - 20.4 (2.58)
      • SBE (Pod API)
        • SBE - 24.1
        • SBE - 20.16
        • SBE - 20.15
        • Archives
          • SBE - 20.14
          • SBE - 20.13
          • SBE - 20.12
          • SBE - 20.10
          • SBE - 20.9 (1.62)
          • SBE - 20.7 (1.61)
          • SBE - 20.6 (1.60)
          • SBE - 20.5 (1.59)
          • SBE - 20.4 (1.58)
      • Client 2.0 APIs
        • Client 2.0 - 25.05
        • Client 2.0 - 25.03
        • Client 2.0 - 24.12
        • Client 2.0 - 24.05
        • Client 2.0 - 23.02
        • Client 2.0 - 22.11
        • Archives
          • Client 2.0 - 20.4
          • Client 2.0 - 20.5
          • Client 2.0 - 20.6
          • Client 2.0 - 20.7
          • Client 2.0 - 20.9
          • Client 2.0 - 20.10
          • Client 2.0 - 20.12
          • Client 2.0 - 22.8
          • Client 2.0 - 22.10
      • Universal Webhook
        • Univ Webhook - 2.6
        • Univ Webhook - 2.4
        • Univ Webhook - 2.2
        • Univ Webhook - 2.1
        • Univ Webhook - 2.0
    • API Change Management
    • Global Throttling
    • Agent Guide
      • Network Topology
      • Agent Download
      • Agent Installation
      • Agent Configuration Fields
      • Agent Server High Availability
      • Agent Performance Tuning
Powered by GitBook
On this page
  • How to load Embedded Mode
  • Explicit rendering
  • Automatic rendering
  • Direct iFrame rendering
  • User login to Embedded Mode
  • SSO specificities
  • Allow users from different pods to log in
  • Health check

Was this helpful?

Export as PDF
  1. Embedded Modules
  2. Embedded Mode

Get started

Last updated 7 months ago

Was this helpful?

How to load Embedded Mode

Embedded Mode can be loaded in three different ways:

  • (recommended)

Unless you have specific technical constraints, you should use explicit rendering.

Explicit rendering

With explicit rendering, Embedded Mode will expose an API to the parent page, giving you fine-grained control over Embedded Mode.

There are three steps required to load a chat:

  1. Loading the Embedded Mode SDK script. You can be notified that the script has finished loading through a callback.

  2. Rendering Embedded Mode, using the render method. This step takes approximately 4s, and can be done in the background, typically in a hidden div. You can be notified that Embedded Mode is ready through the promise returned by the render method. Optionally, you can specify a streamId as a parameter, in which case the conversation will be opened as soon as Embedded Mode is ready.

  3. Opening a chat, using the openStream method. This is quick and can be done once the render method has completed. If you want to switch from one chat to the other, or to display additional chat containers in the webpage, you use the openStream method and you don't need to use render again.

1. Loading the SDK script

To load Embedded Mode in explicit mode, you need to add the following script in your web page:

<script
  id="symphony-ecm-sdk"
  render="explicit"
  data-onload="onECPSdkLoaded"
  data-partner-id="{partnerId}"
  src="https://{your_pod_url}.symphony.com/embed/sdk.js"
></script>

Optionally, you can define what needs to be done once the SDK is loaded (data-onload parameter).

window.onECPSdkLoaded = () => {
  // window.symphony is available
  // Typically: call the render() method documented below.
}

Please note the render="explicit" parameter in the script tag.

Once loaded, the SDK will expose the Embedded Mode APIs in the window.symphony object.

By default, Embedded Mode will start in Focus mode, but you can choose Collaboration mode by setting the mode parameter data-mode="full" in the script tag above.

2. Rendering Embedded Mode

Once the SDK is loaded, the first function you need to call to start Embedded Mode is render.

The render method creates and adds the Embedded Mode iframe to the container with the class given as first parameter.

Parameter
Type
Description

containerOrClassName

string

Class of the container into which Embedded Mode will be injected (optional). If not specified, the default value is "symphony-ecm".

configuration

Record<string, string | boolean | undefined>

fromLogin

boolean

Startup time optimisation linked to the checkAuth feature described below.

If you know the user is not logged in, you can set this parameter to true, and the user will be sent straight to the login page (instead of first loading Embedded Mode and trying to connect before redirecting to login) Cannot be used in conjunction with popupLogin

Default false (optional)

Example:

<!-- ECP iframe will be loaded in this div by the SDK -->
<div class="ecp-chat"></div>

<script>
window.onECPSdkLoaded = () => {
  window.symphony.render('ecp-chat', {
    mode: 'dark',
    condensed: true,
    streamId: 'VYfoWw6oIUv+5K80BPUjeX///oz1uTOEdA=='
  })
}
</script>

Note: It is not mandatory to pass a streamId to the render method. This is particularly useful when you want to render Embedded Mode in the background, in a hidden div. And then, when Embedded Mode has been rendered, you can open the right conversation using the openStream method, which is very quick.

To optimize the render process based on whether the user is already authenticated and the type of authentication (SSO or password), you can use the checkAuth method before calling render with the most appropriate configuration.

window.onECPSdkLoaded = async () => {
  const container = 'ecp-chat'
  const config = { mode: 'dark', condensed: true };
  
  const { isLoggedIn, authenticationType } = await symphony.checkAuth(null);
  if (!isLoggedIn) {
    if (authenticationType === 'password') {
      // Password Login
      await symphony.render(container, config, true);
    } else {
      // SSO Login - enable login popup
      await symphony.render(container, { ...config, ecpLoginPopup: true });
    }
  } else {
    // Already authenticated
    await symphony.render(container, config);
  }
}

3. Opening a chat

Important: Handle situations where a user interaction is needed

Embedded Mode may require a user interaction before being able to display a chat. For example, the user may need to accept the End User License Agreements, the Terms Of Use, request access to the required chat, etc.

If you decide to hide the Embedded Mode UI until a chat is ready to be rendered, then you may be blocked by this required interaction. To be notified that a user interaction is required (and therefore that you need to show Embedded Mode even before the render method returns), you need to register to onUserInteractionRequired() below.

onUserInteractionRequired({
  callback: (callbackPayload: {reason: string}) => void;
}): Promise<void>;

Once the user interaction is completed, you will eventually be notified that the UI is ready to be used with the render promise resolving (either with the chat information or an error).

Automatic rendering

Automatic rendering is not recommended, and is kept only for backwards compatibility with the previous ECM solution.

In automatic mode, Embedded Mode will create the iFrame for you, so you just need to add the Embedded Mode script tag and add a div in your page that has the symphony-ecm class, so that the script can find it and add the iFrame in it.

By default, Embedded Mode will start in Focus mode, but you can choose Collaboration mode by setting the mode parameter:data-mode="full" on the script tag.

<script
  id="symphony-ecm-sdk"
  data-partner-id="{partnerId}"
  src="https://{your_pod_url}.symphony.com/embed/sdk.js"
></script>
<div class="symphony-ecm" 
  data-stream-id="{streamId}"
  data-mode="dark"
  data-condensed="true">
</div>

Direct iFrame rendering

Direct iFrame rendering is very limited, and should only be used for situations where using explicit rendering is impossible (for example, if you only have an "iFrame widget" in a third-party application).

Make sure to give the iframe the correct permissions according to usage (e.g. clipboard access)

For the Focus mode:

<iframe
  src="https://{your_pod_url}.symphony.com/embed/index.html?streamId={STREAM_ID}&partnerId={partnerId}&mode=dark&condensed=true"
></iframe>

For the Collaboration mode:

<iframe
  src="https://{your_pod_url}.symphony.com/client-bff/index.html?embed=true&streamId={STREAM_ID}&partnerId={partnerId}&mode=dark&condensed=true"
></iframe>

User login to Embedded Mode

SSO specificities

End users log in to Embedded Mode using their usual Symphony credentials. If they have an SSO setup, they will automatically be redirected to their authentication page, just like what would happen in the Symphony Desktop Application.

Note: As Embedded Mode uses an iFrame, some SSO systems will raise a Content Security Policy error (CSP) when Embedded Mode tries to redirect the user. In that case, you can either update your SSO system to allow framing within your pod domain, or alternatively you can configure Embedded Mode to do the login in a popup using the ecpLoginPopup parameter.

Allow users from different pods to log in

End users can only log in the Symphony pod where their credentials are defined. Meaning that depending on who are the users of your web portal, you may not always want to load Embedded Mode from a unique pod URL (e.g a single pod).

If you are Company A, but you want Symphony users from Company B to be able to log in to Embedded Mode from your web portal then you need to adapt the script tag that loads Embedded Mode and set {your_pod_url} to the URL of Company B's pod, so Embedded Mode will be loaded from the right pod.

If that user does not have already a Symphony account, or if you prefer to control this user account, you can also create a new dedicated account for that user.

Onboarding this user on a new Symphony pod can be done thanks to our Customer Connect offering, or through our Community or Channel Connect offering. To learn more about Customer Connect and Community Connect please reach out to your Symphony representative.

Identify the right pod URL

In any case, as you onboard the user on your web portal you will need to identify what Symphony pod URL to load Embedded Mode from.

Use the following http endpoint to retrieve the Symphony pod URL of a user:

https://loginservice.symphony.com/webcontroller/podLoginInformation?emailAddress={userEmail}&fs={userEmail}

The http response will be formatted as below:

{"podDomain":"corporate.symphony.com"}

If the user email is not found, the pod with the most users sharing the same root email domain will be returned.

If the company is not at all present on Symphony, the following error will be returned instead:

{"message":"No pod found for emailAddress: 'janedoe@acme.com' and companyDomain: 'acme.com'","status":"NOT_FOUND"}

If you have onboarded this user on your Customer Connect pod, the service will return an error, as users onboarded on Customer Connect pods are not listed for confidentiality reasons. In this situation, you can either persist the pod information when you onboard the user on the Customer Connect pod, or you can use the pod APIs of the Customer Connect pod to identify the user.

Health check

If you need to monitor the uptime of Embedded Mode, you can monitor that the following https request returns 200 OK.

https://{your_pod_url}.symphony.com/embed/version.json

Set the data-partner-id with the Partner Id that was provided to you. More info on Partner Id .

(optional)

The render method returns a promise that resolves when the chat is ready. See the promise definition .

Note: Even if the render method can be used to switch from one conversation to another in Focus mode, it is not advised as it re-creates the iFrame entirely, which takes time. Prefer the method when you just want to switch to another conversation.

Once the rendering is completed, you can open a conversation using the openStream method documented or start a new chat using the startRoom method documented .

You can register your callback function as soon as the .

Set the data-partner-id with the Partner Id that was provided to you. More info on Partner Id .

With automatic rendering, the should then be added as data-* attributes to the div that will contain the iFrame:

It is possible to load Embedded Mode using the iFrame rendering mode, which accepts basic , but does not allow any of the advanced features offered through the SDK.

Set the partnerId with the Partner Id that was provided to you. More info on Partner Id .

If you are a partner and uses ChannelConnect to onboard new Symphony users, you can also set up your own SSO. More information is available .

parameters
configuration parameters
here
Explicit rendering
Automatic rendering
Direct iFrame rendering
Configuration
here
here
here
openStream
here
here
SDK is loaded
here