Comment on page
Get started
ECP can be loaded in three different ways:
Unless you have specific technical constraints, you should use explicit rendering.
With explicit rendering, ECP will expose an API to the parent page, giving you fine-grained control over ECP.
There are three steps required to load a chat:
- 1.Loading the SDK script of ECP. You can be notified that the script has finished loading through a callback.
- 2.Rendering ECP, 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 ECP is ready through the promise returned by therender
method. Optionally you can specify astreamId
as a parameter, in which case the conversation will be opened as soon as ECP 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 theopenStream
method and you dont need to userender
again.
To load ECP 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 ECP APIs in the
window.symphony
object.By default, ECP will start in Focus mode, but you can choose Collaboration mode by setting the mode parameter
data-mode="full"
in the script tag above.Once the SDK is loaded, the first function you need to call to start ECP is
render
. The
render
method creates and adds the ECP iframe to the container with the class given as first parameter.Parameter | Type | Description |
---|---|---|
containerOrClassName | string | Class of the container into which ECP 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 ECP and trying to connect before redirecting to login)
Cannot be used in conjunction with popupLogin
Default false (optional) |
The
render
method returns a promise that resolves when the chat is ready. See the promise definition here.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 ECP in the background, in a hidden div. And then when ECP has been rendered, you can open the right conversation using the openStream
method, which is very quick.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 openStream
method when you just want to switch to another conversation.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);
}
}
Automatic rendering is not recommended, and is kept only for backwards compatibility with the previous ECM solution.
In automatic mode, ECP will create the iFrame for you, so you just need to add the ECP 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, ECP 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>
With automatic rendering, the parameters should then be added as
data-*
attributes to the div that will contain the iFrame:<div class="symphony-ecm"
data-stream-id="{streamId}"
data-mode="dark"
data-condensed="true">
</div>
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)
It is possible to load ECP using the iFrame rendering mode, which accepts basic configuration parameters, but does not allow any of the advanced features offered through the SDK.
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>
End users log into ECP 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 ECP uses an iFrame, some SSO systems will raise a Content Security Policy error (CSP) when ECP 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 ECP to do the login in a popup using the
ecpLoginPopup
parameter.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 here.
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 ECP 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 ECP from your web portal then you need to adapt the script tag that loads ECP and set
{your_pod_url}
to the URL of Company B's pod, so ECP 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.
In any case, as you onboard the user on your web portal you will need to identify what Symphony pod URL to load ECP from.
Use the following http endpoint to retrieve the Symphony pod URL of a user:
https://{your_pod_url}.symphony.com/webcontroller/podLoginInformation?emailAddress={userEmail}
The http response will be formatted as below:
{"podDomain":"corporate.symphony.com"}
If the user email is not found, the following error will be returned instead:
{"message":"No pod found for emailAddress: 'jane[email protected]' 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.
If you are using Community Connect to onboard users, please reach out to us to learn more on how you can identify the correct pod URL.
If you need to monitor the uptime of ECP, you can monitor that the following https request returns 200 OK.
https://{your_pod_url}.symphony.com/embed/version.json
Last modified 30d ago