Ninchat-embed NPM

Installation

install using npm i ninchat-embed or link main directly from ninchat.com:

<!DOCTYPE html>
<html>
    <head>
        <script src="https://ninchat.com/app/embed3.js"></script>
    </head>
    <body>
        <div id="ninchat-container"></div>
        <script>
            const Ninchat = new NinchatEmbed()

            const options = {
                configKey: SITE_CONFIG_KEY,
                containerId: 'ninchat-container',
            }

            Ninchat.on(Ninchat.Event.ActivityCount, (data) => {console.info('Activity from Ninchat', data)})
            Ninchat.on(Ninchat.Event.AudienceAccepted, (data) => {console.info('Audience accepted from Ninchat', data)})
            Ninchat.on(Ninchat.Event.AudienceClosed, (data) => {console.info('Audience closed from Ninchat', data)})
            Ninchat.on(Ninchat.Event.AudienceEnded, (data) => {console.info('Audience ended from Ninchat', data)})
            Ninchat.on(Ninchat.Event.Route, (data) => {console.info('Route change from Ninchat', data)})
            Ninchat.on(Ninchat.Event.Notification, (data) => {
                switch (data.type) {
                    case Ninchat.NotificationType.MessageReceivedChannel:
                        console.info('Channel message was received', data)
                        break
                    default:
                        console.info('Notification from Ninchat', data)
                }
            })
            Ninchat.on(Ninchat.Event.Error, (data) => {console.error('Error from Ninchat', data)})

            Ninchat.init(options)
        </script>
    </body>
</html>

Site config JSON

{
    "description": "Site config",
    "default": {
        "variant": "app"
    }
}

Init options

Key	Type	Description
`audienceMetadata`	object (optional)	Audience metadata passed to the expert.
`config`	object (optional)	Config used to override subset of the keys obtained via configKey and others.
`configKey`	string	Site config key to be used for initializing.
`configUrls`	array (optional)	List of URL addresses for self-hosted configs.
`containerId`	string	DOM element id for where the chat container is placed.
`postConfigUrls`	array (optional)	List of URL addresses for self-hosted configs loaded via POST request.
`environment`	array (optional)	List of environment keys. 'default' is always used, and can be omited.

Functions

Ninchat.destruct

Removes all event listeners and de-initialized Ninchat.

const onRemoveNinchat = () => {
    Ninchat.destruct()
}

Ninchat.init

Initializes Ninchat, and loads it in an iframe, which is placed inside container.

const options = {
    configKey: SITE_CONFIG_KEY,
    containerId: 'ninchat-container',
}

Ninchat.init(options)

Ninchat.off

Removes a NinchatEvent listener and its callback function.

const onNinchatErrorEvent = (data) => {
    console.error('Error from Ninchat', data)
}

Ninchat.off(Ninchat.Event.Error, onNinchatErrorEvent)

Ninchat.on

Adds a NinchatEvent listener and a callback function.

const onNinchatErrorEvent = (data) => {
    console.error('Error from Ninchat', data)
}

Ninchat.on(Ninchat.Event.Error, onNinchatErrorEvent)

Ninchat.route

Change a route on Ninchat in iframe.

Ninchat.route(Route)

Enums

Ninchat.Event

Enum value
`ActivityCount`
`AudienceAccepted`
`AudienceClosed`
`AudienceEnded`
`ContainerInitialized`
`Error`
`Notification`
`Route`

Ninchat.ErrorType

When received event is Ninchat.Event.Error, the error_type property is one of the following:

Enum value
`ContainerNotFoundError`
`SiteConfigFetchError`
`InvalidConfigKeyError`
`InvalidSiteConfigError`

Ninchat.NotificationType

When received event is Ninchat.Event.Notification, the type property is one of the following:

Enum value
`AudienceRegistered`
`MessageReceivedChannel`
`MessageReceivedChannelAudience`
`MessageReceivedChannelJoin`
`MessageReceivedDialogue`
`QueueUpdatedAudienceAcceptPeer`
`QueueUpdatedAudienceRequest`

Ninchat.RouteName

When received event is Ninchat.Event.Route, the route.name property is one of the following:

Enum value
`Channel`
`Else`
`Transcript`

Events

Currently, the following events are supported:

Ninchat.Event.ActivityCount

{
    event: Ninchat.Event.ActivityCount
    activity: number
    highlights: number
}

Typical use case for ActivityCount is to display activity as a number in host sites favicon. activity property contains the total activity including highlights.

highlights are activity which has importance based on users settings or their role. Eg. highlight can be a name mention or a visitor requesting an audience.

Ninchat.Event.AudienceAccepted

{
    audience_id: string
    event: Ninchat.Event.AudienceAccepted
    metadata?: []
}

AudienceAccepted event is emitted when a new chat session is started by interaction in current user interface.

metadata array follows specifications described at AudienceRoute,

Ninchat.Event.AudienceClosed

{
    audience_id: string
    event: Ninchat.Event.AudienceClosed
}

AudienceClosed event is emitted when the chat is closed.

Ninchat.Event.AudienceEnded

{
    audience_id: string
    event: Ninchat.Event.AudienceEnded
}

AudienceEnded event is emitted when the chat session is ended.

Ninchat.Event.ContainerInitialized

{
    event: Ninchat.Event.ContainerInitialized
}

Ninchat.Event.Error

{
    error_type: string
    event: Ninchat.Event.Error
}

Ninchat.Event.Notification

{
    audio?: boolean
    channel_name?: string
    desktop?: boolean
    event: Ninchat.Event.Notification
    queue_name?: string
    realm_name?: string
    type: Ninchat.NotificationType
    user_name?: string
}

Notification event is emited whenever user would receive either a desktop or an audio notification based on users preferences. When Ninchat is embedded, instead of firing a desktop or audio notification, a Notification event is emited instead.

Ninchat.Event.Route

{
    event: Ninchat.Event.Route
    route: AudienceRoute | ChannelRoute | ElseRoute | TranscriptRoute
}

Route event is emited whenever users route in Ninchat is changed. Host site can distinquish between different routes based on the passed properties. metadata in AudienceRoute and TranscriptRoute contains pre-whitelisted subset of audience customers metadata.

AudienceRoute

{
    audience_id: string
    name: Ninchat.RouteName.Channel
    metadata?: []
    params: {
        channel_id: string
    }
}

metadata array contains secure metadata which is exposed to the parent on purpose. Array is used here, since in conversation can be multiple users with metadata.

⚠️ The array is shuffled to prevent misconceptions that index 0 would contain specific users metadata. Since the array is in random order, if there is a need to distinguish between users, an identifying field needs to be added while generating secure metadata.

Example: secure metadata containing following shared field..

{
    shared: {
        data: {
            CustomerID: 123,
            CustomerName: 'Kathryn Janeway'
        },
        parent: [HOST_SITE_ORIGIN],
    }
}

..would lead to a following AudienceRoute event:

{
    audience_id: string
    name: Ninchat.RouteName.Channel
    metadata?: [
        {
            CustomerID: 123,
            CustomerName: 'Kathryn Janeway'
        }
    ],
    params: {
        channel_id: string
    }
}

ChannelRoute

{
    name: Ninchat.RouteName.Channel
    params: {
        channel_id: string
    }
}

ElseRoute

{
    name: Ninchat.RouteName.Else
}

TranscriptRoute

{
    audience_id: string
    name: Ninchat.RouteName.Transcript
    metadata?: []
    params: {
        audience_id: string
    }
}

metadata array follows specifications described at AudienceRoute,

Examples

SSO

SSO using email address:

const options = {
    config: {
        default: {
            sso: {
                email: EMAIL_ADDRESS,
                type: 'email',
            }
        },
    },
    configKey: SITE_CONFIG_KEY,
    containerId: 'ninchat-container',
}

Ninchat.init(options)

SSO using provider name:

const options = {
    config: {
        default: {
            sso: {
                name: PROVIDER_NAME,
            }
        },
    },
    configKey: SITE_CONFIG_KEY,
    containerId: 'ninchat-container',
}

Ninchat.init(options)

Initial route

Define a forced initial route on load:

const options = {
    config: {
        default: {
            initialRoute: {
                name: 'Channel',
                params: {channel_id: CHANNEL_ID},
        },
    },
    configKey: SITE_CONFIG_KEY,
    containerId: 'ninchat-container',
}

Ninchat.init(options)

Change a route on Ninchat in iframe

Calling Ninchat.route() to change route:

const route = {
    name: 'Channel',
    params: {channel_id: CHANNEL_ID},
}

Ninchat.route(route)

Release history

v1.0.6

Fixed video screen share functionality
Fixed video fullscreen functionality

v1.0.5

Ninchat.init() config initialRoute
Ninchat.route()

@everything-registry/sub-chunk-2292

9 months ago

10 months ago

11 months ago

1 year ago

2 years ago

2 years ago

2 years ago