Application scoping in Connect Customer agent workspace

Every application has two scope settings that together determine how the application behaves with respect to contacts:

• A registration-time scope, selected by the application publisher when the application integration is registered with Amazon Connect.

• A launch-time scope, passed by the agent application in AppLaunchOptions.scope when it calls launchApp.

The launch-time scope always takes precedence. It is the value that AppManager uses to determine the lifecycle of the application instance, regardless of the registration-time scope. The registration-time scope is advisory: it indicates the launch-time scope that the publisher recommends for typical use of the application, but the agent application is free to launch the application with a different scope. For example, a registration-time "Cross contacts" application launched with scope.type: "contact" is destroyed when the associated contact ends.

Registration-time contact handling scope

The contact handling scope is selected by the application publisher when the application integration is registered with Amazon Connect. It is a property of the application and cannot be changed by the agent application at launch time. The following values are supported.

Scope	Description
Per contact	AppManager maintains a separate application instance for each contact. Each instance's data access is scoped to its associated contact, and the instance is destroyed when that contact ends. To launch the application with this behavior, set the launch-time scope to contact.
Cross contacts	AppManager maintains a single application instance that persists across contacts for the lifetime of the browser session. The instance is not bound to any specific contact and is not destroyed when contacts end. This scope is suitable for utilities, knowledge bases, dashboards, and other applications whose content is session-level rather than contact-level. To launch the application with this behavior, set the launch-time scope to idle.

Launch-time scope

The launch-time scope is the value that the agent application passes in AppLaunchOptions.scope when calling launchApp. It applies to both per-contact and cross-contact applications and determines the lifecycle of the resulting application instance. The following values are supported.

• contact – The application instance is bound to a single contact and can access data only for that contact. AppManager automatically destroys the instance when the associated contact ends, and emits the onDestroying and onDestroyed lifecycle events so that the agent application can clean up the user interface. This behavior applies regardless of the application's registration-time scope. A cross-contact application launched with the contact scope is destroyed when the associated contact ends.

• idle – The idle state refers to the period when the agent is not handling any contact. An application launched with the idle scope is not bound to any contact, does not have access to contact data, and persists for the lifetime of the page or until the agent application calls destroy(). Use this scope for cross-contact applications that must remain open across contacts, and for per-contact applications that must remain available when the agent is not handling a contact.

The following table describes the launch-time scope to use for each registration-time scope, including the default behavior when the agent application does not pass a scope value at launch. An active contact exists whenever the agent is handling one or more contacts; the idle state is the period when the agent is not handling any contact.

Registration-time scope	Launch-time scope	Resulting behavior
Per contact	contact	AppManager creates one instance per contact and automatically destroys the instance when the contact ends.
	idle	The application is available when the agent is idle and is not destroyed when contacts end. The application cannot access contact data.
	Not specified	If an active contact exists at launch, behaves the same as contact. If the agent is idle at launch, behaves the same as idle.
Cross contacts	idle	The application persists across contacts and is destroyed only when the page session ends or the agent application calls destroy().
	contact	The application can access contact data, but AppManager destroys the instance when the associated contact ends. This prevents the application from persisting across contacts as the publisher intends.
	Not specified	If an active contact exists at launch, behaves the same as contact. If the agent is idle at launch, behaves the same as idle.

Note

The registration-time scope is not used as the implicit default when no launch-time scope is provided. To guarantee a specific behavior regardless of whether an active contact exists at launch time, set scope.type explicitly to "contact" or "idle".

Launch an application with an explicit scope

To control the scope under which an application runs, provide a scope object in the AppLaunchOptions parameter of launchApp.

Launch with contact scope:

Provide the contact type and the ID of the contact to which the application is bound:

const launchOptions: AppLaunchOptions = {
    scope: {
        type: "contact",
        contactId: contactId  // The ID of the contact to scope this application to
    }
};

// Launch the application scoped to the specified contact
const appHost = await appManager.launchApp(app.arn, launchOptions);

// Create and configure the iframe for the application
const appIframe = document.createElement("iframe");
appHost.setIFrame(appIframe);

Launch with idle scope:

Provide the idle type to launch an application that is not bound to the lifecycle of any contact:

const launchOptions: AppLaunchOptions = {
    scope: {
        type: "idle"
    }
};

// Launch an application that does not have access to contact data and
// persists regardless of which contact the agent is handling
const appHost = await appManager.launchApp(app.arn, launchOptions);

// Create and configure the iframe for the application
const appIframe = document.createElement("iframe");
appHost.setIFrame(appIframe);