# Contact Center Smart Embed

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

The Contact Center Smart Embed (CCSE, or Smart Embed) is a fast and flexible solution that lets developers quickly embed a softphone for Contact Center in their third-party web application.

-   Administrators can allow third-party applications to use the app when they install it and configure approved domains.
-   End users can sign in to the Smart Embed in their third-party app by using their Zoom credentials.

Learn to add Smart Embed to your web applications that control the Smart Embed, such as click-to-call, receive calls, notifications for inbound and outbound calls, auto call logging, and support for custom notes pages.

## Prerequisites

-   You must have a [Contact Center license](https://zoom.us/pricing/zoom-contact-center).
-   Administrators must be able to access Zoom to configure an integration in Contact Center for Contact Center Smart Embed.
-   Smart Embed is an iframe based web solution that communicates with the parent web application by exchanging `postMessage` events. The web application where Smart Embed is embedded must support this type of integration.

### Supported platforms

-   Browser-based apps - Chrome, Edge

### Supported channels

-   Voice
-   Video
-   Web chat
-   SMS
-   Work item

## Add Smart Embed to your web apps

Add Contact Center Smart Embed to third-party web apps with a code snippet.

1. Embed the Computer Telephony Integration (CTI) iframe into your web page or web application. For the origin parameter in the `src` attribute, include the domain where this iframe will be embedded.

    If your company uses single sign-on (SSO) via SAML integration with your Zoom account, and requires your call center agents to authenticate to Zoom through your SSO system, streamline your agents' Smart Embed login process by editing the iframe's `src` attribute and inserting your company's vanity URL and `.` right after the `https://`. For example, if your company's vanity URL is `VanityURL`

    `https://zoom.us/cci/callbar/crm/?origin=https://YOUR_DOMAIN`

    becomes

    `https://VanityURL.zoom.us/cci/callbar/crm/?origin=https://YOUR_DOMAIN`.

    ```html
    <iframe
        src="https://zoom.us/cci/callbar/crm/?origin=https://YOUR_DOMAIN"
        sandbox="allow-forms allow-popups allow-popups-to-escape-sandbox allow-scripts allow-same-origin allow-downloads"
        allow=";autoplay;microphone;camera;display-capture;midi;encrypted-media;clipboard-write;"
        id="zoom-embeddable-phone-iframe"
    ></iframe>
    ```

    ```html
    <iframe
        src="https://zoom.us/crm-int/callbar/?origin=https://YOUR_DOMAIN"
        sandbox="allow-forms allow-popups allow-popups-to-escape-sandbox allow-scripts allow-same-origin allow-downloads"
        allow=";autoplay;microphone;camera;display-capture;midi;encrypted-media;clipboard-write;"
        id="zoom-embeddable-phone-iframe"
    ></iframe>
    ```

2. Set the initial size using CSS.

    ```html
    <style>
        #zoom-embeddable-phone-iframe {
            height: 700px;
            width: 840px;
        }
    </style>
    ```

## Control the Smart Embed

The Contact Center Smart Embed provides APIs that let you control the softphone. Use these APIs to add these features.

-   Initialize the Smart Embed interface
-   Resize softphone
-   Contact search
-   Click-to-call
-   Receive a call
-   Screen popup
-   Inbound and outbound call notifications
-   Support to add a custom notes page to a softphone
-   Call recording
-   Wrap-up done
-   Get the value from global custom variables

Once you've initialized Smart Embed, your app is ready to start sending and receiving messages. The Contact Center Smart Embed provides some events based on the `postMessage` API.

```javascript
window.addEventListener("message", (e) => {
    const data = e.data;
    if (data) {
        switch (data.type) {
            case "zcc-contact-search-event": // listen to all the event types that you need
                console.log(data.data);
                break;
        }
    }
});
```

## Events

Contact Center Smart Embed provides these events.

-   [`zcc-init-config-request`](#zcc-init-config-request)
-   [`zcc-init-config-response`](#zcc-init-config-response)
-   [`zcc-resize`](#zcc-resize)
-   [`zcc-contact-search-event`](#zcc-contact-search-event)
-   [`zcc-contact-search-response`](#zcc-contact-search-response)
-   [`zcc-call-ringing`](#zcc-call-ringing)
-   [`zcc-incomingPhone-request`](#zcc-incomingphone-request)
-   [`zcc-incomingPhone-response`](#zcc-incomingphone-response)
-   [`zcc-screen-pop`](#zcc-screen-pop)
-   [`zcc-call-connected`](#zcc-call-connected)
-   [`zcc-call-ended`](#zcc-call-ended)
-   [`zcc-end-post-engagement` (Deprecated)](#zcc-end-post-engagement-deprecated)
-   [`zcc-phone-call-log`](#zcc-phone-call-log)
-   [`zcc-call-recording`](#zcc-call-recording)
-   [Click to dial from a third-party app](#click-to-dial-from-a-third-party-app)
-   [`zcc-incomingEmail-request`](#zcc-incomingemail-request)
-   [`zcc-incomingEmail-response`](#zcc-incomingemail-response)
-   [`zcc-chat-ringing`](#zcc-chat-ringing)
-   [`zcc-chat-started`](#zcc-chat-started)
-   [`zcc-chat-ended`](#zcc-chat-ended)
-   [`zcc-video-ringing`](#zcc-video-ringing)
-   [`zcc-video-started`](#zcc-video-started)
-   [`zcc-video-ended`](#zcc-video-ended)
-   [`zcc-add-note`](#zcc-add-note)
-   [`zcc-sms-ringing`](#zcc-sms-ringing)
-   [`zcc-sms-started`](#zcc-sms-started)
-   [`zcc-sms-ended`](#zcc-sms-ended)
-   [`zcc-outbound-call-started`](#zcc-outbound-call-started)
-   [`zcc-inbound-not-connected`](#zcc-inbound-not-connected)
-   [`zcc-outbound-not-connected`](#zcc-outbound-not-connected)
-   [`zcc-reject-engagement`](#zcc-reject-engagement)
-   [`zcc-accept-engagement`](#zcc-accept-engagement)
-   [`zcc-terminate-engagement`](#zcc-terminate-engagement)
-   [`zcc-set-engagement-disposition`](#zcc-set-engagement-disposition)
-   [`zcc-close-engagement-wrapup`](#zcc-close-engagement-wrapup)
-   [`zcc-engagement-status-request`](#zcc-engagement-status-request)
-   [`zcc-engagement-status-response`](#zcc-engagement-status-response)
-   [`zcc-engagement-log-url`](#zcc-engagement-log-url)
-   [`zcc-set-mute`](#zcc-set-mute)
-   [`zcc-set-hold`](#zcc-set-hold)
-   [`zcc-send-dtmf`](#zcc-send-dtmf)
-   [`zcc-set-recording`](#zcc-set-recording)
-   [`zcc-transfer-engagement`](#zcc-transfer-engagement)
-   [`zcc-add-call`](#zcc-add-call)
-   [`zcc-cancel-consult`](#zcc-cancel-consult)
-   [`zcc-complete-transfer`](#zcc-complete-transfer)
-   [`zcc-merge-consult`](#zcc-merge-consult)
-   [`zcc-upgrade-to-video`](#zcc-upgrade-to-video)
-   [`zcc-get-disposition-codes`](#zcc-get-disposition-codes)

### zcc-init-config-request

This event fires when an agent loads a webpage with Smart Embed.

```javascript
{
    type: "zcc-init-config-request",
}
```

In response to the `zcc-init-config-request` event, your application will need to respond to Smart Embed using the `zcc-init-config-response` message.

### zcc-init-config-response

When your application receives a `zcc-init-config-request`, your application responds back via `postMessage` with the `zcc-init-config-response` object, which contains your configuration's necessary implementation.

```javascript
{
    type: "zcc-init-config-response",
    data: {
        phone: {
            screenPopEvent: "RINGING",
        },
    },
}
```

### zcc-resize

This event fires when a user toggles the size buttons in Smart Embed. Use this to resize your web application.

```javascript
{
    type: "zcc-resize",
    data: {
        widthInPixels,
        heightInPixels,
    },
};
```

### zcc-contact-search-event

The `zcc-contact-search-event` fires when Smart Embed needs to resolve phone numbers or email addresses against your web application. This can happen when the agent types in the Smart Embed dialpad's `Phone` or `User` field. This can also happen when Smart Embed loads and there are existing engagements that Smart Embed needs to link to your web application. This event allows Smart Embed to resolve or populate phone numbers and email addresses against user, contact, lead, or similar objects in your application.

```javascript
{
    type: "zcc-contact-search-event",
    data: {
        query: "DATA_TO_SEARCH", // could be a phone number, first name, last name, email, etc.
    },
}
```

In response to the `zcc-contact-search-event` event, your application should search for a matching user, contact, lead, or similar object based on the query field. Your application should respond to Smart Embed using the `zcc-contact-search-response` message. This information will be used by Smart Embed to display data to the agent within the Contact Center Smart Embed UI.

### zcc-contact-search-response

This is an example of the message that your application should send in response to receiving the `zcc-contact-search-event` event. This response allows Smart Embed to resolve or display your web application's user, contact, lead, or similar object within the Smart Embed UI.

```javascript
{
    type: "zcc-contact-search-response",
    data: {
        id: "THIRD_PARTY_ID",   // This is displayed visually to the Contact Center agent in the Smart Embed UI
        name: "NAME",           // This is displayed visually to the Contact Center agent in the Smart Embed UI
        phone: "PHONE_NUMBER",  // Phone number for the user, contact, lead, etc
        email: "YOUR_STRING",   // Email address for the user, contact, lead, etc
        entity: "YOUR_STRING",  // The type of entity used by your application, for example contact/lead/user/etc. Smart Embed uses this to display to the Contact Center agent, but does not use this for any other purpose.
    },
}
```

### zcc-call-ringing

This event fires when an agent receives a call. Replace the YOUR_STRING segments with your data.

```javascript
{
    type: "zcc-call-ringing",
    data: {
        channel: <create ts number>,
        createTs: <create ts number>,
        engagementId: YOUR_CALL_ENGAGEMENT_ID,
        from: YOUR_CALLER_PHONE_NUMBER,
        queueName: YOUR_QUEUE_NAME,
        to: YOUR_CALLEE_PHONE_NUMBER,
        isConference: <true | false if conference>,
        isTransfer: <true | false if transfer>,
    },
}
```

### zcc-incomingPhone-request

This event fires when an agent gets an incoming call. It supports the voice channel, and the SMS channel.

```javascript
{
    type: "zcc-incomingPhone-request",
    data: {
        incomingPhoneNumber: YOUR_CALLER_PHONE_NUMBER,
        engagementId: YOUR_CALL_ENGAGEMENT_ID,
        channel: "voice",  // Possible values: 'voice', 'sms'
    },
}
```

To process that message from Smart Embed, search for matching contact records in your application. After processing, your web application should send a response back to Smart Embed using the `zcc-incomingPhone-response` event. If there is no matching record in your application, respond using the `zcc-incomingPhone-response` event with an empty array.

### zcc-incomingPhone-response

This event allows Smart Embed to display matching contact information within the Smart Embed iframe. If there are multiple objects in the array, they will be displayed to the Contact Center agent for them to select the appropriate match.

```javascript
{
    type: "zcc-incomingPhone-response",
    data: [
        {
            id: YOUR_ID,
            name: YOUR_NAME,
            phone: YOUR_PHONE_NUMBER,
            email: YOUR_EMAIL_ID,
            entity: YOUR_ENTITY, // the type of entity used by your application, such as contact, lead, user, etc.
        },
    ],
}
```

The data included in the above event is displayed to the agent within the Contact Center Smart Embed UI. Additionally, this data is included in the final `zcc-phone-call-log` event so that you can log the call data against the contact within your CRM. The `entity` field can be used to identify the type of contact within your application. For example, some web applications have the concept of "contacts" or "leads". There is no change in the Smart Embed functionality based on the entity field, however it is included in the phone call log event which you can use for logging purposes.

### zcc-screen-pop

The `zcc-screen-pop` event fires in the multiple match scenario. This happens when an incoming call comes into the agent, and the `zcc-incomingPhone-response` includes multiple contact, lead, or user objects in the array. When this happens, the Smart Embed UI presents the objects to the agent. When the agent identifies and selects the appropriate object, this event is then fired back to your application so that you can screen pop to the correct object.

```javascript
{
    type: "zcc-screen-pop",
    data: {
        id: ID_NUMBER,
    },
}
```

When your web application receives this event, search your web application for a matching record and perform a screen pop as needed.

### zcc-call-connected

This event fires when a call is accepted.

```javascript
{
    type: "zcc-call-connected",
    data: {
        acceptTs: ACCEPT_TS_NUMBER,
        direction: <inbound | outbound>,
        engagementId: ENGAGEMENT_ID,
        from: CALLER_PHONE_NUMBER,
        queueId: THE_QUEUE_ID,
        queueName: THE_QUEUE_NAME,
        to: CALLEES_PHONE_NUMBER,
    },
}
```

### zcc-call-ended

This event fires when a call ends.

```javascript
{
    type: "zcc-call-ended",
    data: {
        completeTs: COMPLETE_TS_NUMBER,
        engagementId: ENGAGEMENT_ID,
    },
}
```

### zcc-end-post-engagement (Deprecated)

```javascript
{
    type: "zcc-end-post-engagement",
    data: {
        name: YOUR_DISPOSITION,
        engagementId: ENGAGEMENT_ID,
    },
}
```

### zcc-phone-call-log

This event triggers when an agent completes an engagement. Use this event to create logs for all engagement types within your application.

```javascript
{
    type: "zcc-phone-call-log",
    data: {
        objectRecord: {
            callType: <inbound | outbound>,
            from: <caller number>,
            to: <callee number>,
            callDuration: <call duration time>,
            callStartTime: <call start time>,
            callEndTime: <call end time>,
            callQueue: <call queue>,
            agentExtension: <agent extension>,
            agentName: <name of agent>,
            wrapUpTimeDuration: <time taken while doing wrapup>,
            notes: [ <array of notes in HTML format, entered by agent> ],
            dispositionCode: <disposition code selected by agent>,
            dispositionId: <id of the disposition code>,
            type: <phone | chat>,
        },
        engagementId: ENGAGEMENT_ID,
        relateTo: <>,
        smartNotes: [ <array of notes in HTML format, generated by Zoom AI Expert Assist> ],
        channelUpgradeInfo: <Information regarding any channel upgrades that occurred during the engagement>,
        user: {
            id: <consumer's ID, data comes from info received from event zcc-incomingPhone-response>,
            name: <consumer's name, from event zcc-incomingPhone-response>,
            phone: <consumer's phone number, from event zcc-incomingPhone-response>,
            email: <consumer's email, from event zcc-incomingPhone-response>,
            entity: <consumer's entity type, from event zcc-incomingPhone-response>,
        },
    },
}
```

### zcc-call-recording

This event fires when an agent completes an engagement. Store this URL in your application for agents to be able to play back the recordings. Accessing these URLs requires the user to be signed into Smart Embed and to have access permissions to playback the recording from the Contact Center admin portal.

```javascript
{
    type: "zcc-call-recording",
    data: {
        engagementId: ENGAGEMENT_ID,
        recordingUrl: RECORDING_URL,
    },
}
```

### Click to dial from a third-party app

To make a call when a user selects a phone number in your web application, send this event.

```javascript
{
    type: "onclicktoact",
    data: {
        id: USERS_THIRD_PARTY_ID,
        name: USER_NAME,
        phone: USER_PHONE_NUMBER,       // required field for outbound voice channel calls
        email: EMAIL_OPTIONAL_FIELD,
        userEntity: USERS_ENTITY_TYPE,  // such as user or contact
    },
}
```

A Javascript example for a basic outbound call using only the required field.

```javascript
window.frames["zoom-embeddable-phone-iframe"].contentWindow.postMessage(
    {
        type: "onclicktoact",
        data: {
            phone: "+16505551234",
        },
    },
    "*",
);
```

### zcc-incomingEmail-request

This event fires when an agent gets an incoming chat or video message. It supports the video and chat channels.

```javascript
{
    type: "zcc-incomingEmail-request",
    data: {
        email: CONSUMERS_EMAIL,
        engagementId: ENGAGEMENT_ID,
        channel: "chat",  // Possible values: 'chat', 'video'
    },
}
```

Process that message from Smart Embed by searching for matching contact records in your application. Your web application should respond back to Smart Embed using the `zcc-incomingEmail-response` response. If there is no matching record in your application, respond using the `zcc-incomingEmail-response` event with an empty data array.

### zcc-incomingEmail-response

This event allows Smart Embed to display matching contact information within the Smart Embed iframe. If there are multiple objects in the array, they will be displayed to the Contact Center agent for them to select the appropriate match.

```javascript
{
    type: "zcc-incomingEmail-response",
    data: [
        {
            id: ID,
            name: NAME,
            phone: PHONE_NUMBER,
            email: EMAIL_ID,
            entity: ENTITY,
        },
    ],
}
```

### zcc-chat-ringing

This event fires when an agent receives an inbound web chat engagement.

```javascript
{
    type: "zcc-chat-ringing",
    data: {
        queueId: QUEUE_ID,
        queueName: QUEUE_NAME,
        engagementId:ENGAGEMENT_ID,
        customerName: CUSTOMER_NAME,
        customerEmail: CUSTOMER_EMAIL,
    },
}
```

### zcc-chat-started

This event fires when an agent accepts a chat and the app loads the chat window.

```javascript
{
    type: "zcc-chat-started",
    data: {
        engagementId: ENGAGEMENT_ID,
        createTs: CHAT_START_DATE_AND_TIME,
    },
}
```

### zcc-chat-ended

This event fires when an agent or consumer ends a chat.

```javascript
{
    type: "zcc-chat-ended",
    data: {
        engagementId: ENGAGEMENT_ID,
        completeTs: CHAT_END_DATE_AND_TIME,
    },
}
```

### zcc-video-ringing

This event fires when an agent receives an inbound video engagement.

```javascript
{
    type: "zcc-video-ringing",
    data: {
        queueId: QUEUE_ID,
        queueName: QUEUE_NAME,
        engagementId: ENGAGEMENT_ID,
    }
}
```

### zcc-video-started

This event fires when an agent accepts an inbound or outbound video engagement.

```javascript
{
    type: "zcc-video-started",
    data: {
        engagementId: ENGAGEMENT_ID,
        createTs: VIDEO_START_DATE_AND_TIME,
    },
}
```

### zcc-video-ended

This event fires when an agent ends an inbound or outbound video engagement.

```javascript
{
    type: "zcc-video-ended",
    data: {
        engagementId: ENGAGEMENT_ID,
        completeTs: VIDEO_END_DATE_AND_TIME,
    },
}
```

### zcc-add-note

A new event is emitted when an agent adds a note in the Smart Embed, or when logging miscellaneous information like webchat or SMS transcripts.

```javascript
{
    type: "zcc-add-note",
    data: {
        comment: "<Note contents>",
    },
}
```

### zcc-sms-ringing

This event fires when an agent receives an inbound SMS chat engagement.

```javascript
{
    type: "zcc-sms-ringing",
    data: {
        queueId: QUEUE_ID,
        queueName: QUEUE_NAME,
        engagementId:ENGAGEMENT_ID,
        customerName: CUSTOMER_NAME,
        customerEmail: CUSTOMER_EMAIL,
        incomingPhoneNumber: CUSTOMER_PHONE,
    },
}
```

### zcc-sms-started

This event fires when an agent accepts an SMS engagement and the chat window is loaded.

```javascript
{
    type: "zcc-sms-started",
    data: {
        engagementId: ENGAGEMENT_ID,
        createTs: SMS_START_DATE_AND_TIME,
    },
}
```

### zcc-sms-ended

This event fires when an agent or consumer ends an SMS engagement.

```javascript
{
    type: "zcc-sms-ended",
    data: {
        engagementId: ENGAGEMENT_ID,
        completeTs: SMS_END_DATE_AND_TIME,
    },
}
```

### zcc-outbound-call-started

This event is triggered when an outbound voice call, made by an agent to a consumer, begins. Its returned payload includes

-   the phone number of the consumer being called
-   the `engagementId` for the started voice engagement
-   the engagement start time
-   the queue name the engagement will belong to

```javascript
{
    type: "zcc-outbound-call-started",
    data: {
        "engagementId": ENGAGEMENT_ID,
        "from": CALLER_PHONE_NUMBER,
        "to": CALLEES_PHONE_NUMBER,
        "queueName": QUEUE_NAME,
        "startTs": OB_START_TIMESTAMP
    },
};
```

### zcc-inbound-not-connected

This event fires when an **inbound** call is missed, rejected, or declined by an agent. Its payload includes the reason the call did not connect and the `engagementId`.

```javascript
{
    type: "zcc-inbound-not-connected",
    data: {
        engagementId: ENGAGEMENT_ID,
        reasonCode: REASON_CODE,
        message: REASON_MESSAGE,
    },
};
```

### zcc-outbound-not-connected

This event fires when an **outbound** call is unsuccessful.

**Note** This event is for outbound calls only and does not fire when a call is sent to voicemail, but instead when a call cannot be placed due to an unserviced phone number. Its payload includes the reason the call did not connect and the `engagementId`.

```javascript
{
    type: "zcc-outbound-not-connected",
    data: {
        engagementId: ENGAGEMENT_ID,
        reasonCode: REASON_CODE,
        message: REASON_MESSAGE,
    },
};
```

### zcc-reject-engagement

Send this event as a PostMessage to reject an inbound engagement. When sending, the payload must include

-   `engagementId`
-   `channelType`
-   `requestId`

The `engagementId` must reference a valid engagement, and the `channelType` must be `voice`, `video`, `chat`, or `sms`. The `requestId` must be a unique, 128-bit UUID for tracking, such as `9b7f2c1a-3e4d-4f8a-9b2c-5d6e7f8a9b0c`.

```javascript
{
    type: "zcc-reject-engagement",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: CHANNEL_TYPE,
        requestId: UNIQUE_REQUEST_ID,
    },
};
```

### zcc-accept-engagement

Send this event as a `PostMessage` to accept an incoming engagement. The payload must include

-   `engagementId`
-   `channelType`
-   `requestId`

The `engagementId` must reference a valid engagement, the `channelType` must be `voice`, `video`, `chat`, or `sms`, and the `requestId` must be a unique, 128-bit UUID for tracking.

```javascript
{
    type: "zcc-accept-engagement",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: CHANNEL_TYPE,
        requestId: UNIQUE_REQUEST_ID,
    },
};
```

### zcc-terminate-engagement

Send this event as a `PostMessage` to terminate an active engagement. The payload must include

-   `engagementId`
-   `channelType`
-   `requestId`

The `engagementId` must reference a valid engagement, and the `channelType` must be `voice`, `video`, `chat`, or `sms`. The `requestId` must be a unique, 128-bit UUID for tracking. Additionally, the `engagementId` referenced should be for an active engagement.

```javascript
{
    type: "zcc-terminate-engagement",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: CHANNEL_TYPE,
        requestId: UNIQUE_REQUEST_ID,
    },
};
```

### zcc-set-engagement-disposition

Send this event as a `PostMessage` to select an engagement's `wrap-up` disposition. The payload must include

-   `engagementId`
-   `channelType`
-   `dispositionId`
-   `requestId`

The `engagementId` must reference a valid engagement, and the `channelType` must be `voice`, `video`, `chat`, or `sms`. The `dispositionId` should be the unique ID of a valid, pre-configured Contact Center disposition code. The `requestId` must be a unique, 128-bit UUID for tracking. Additionally, the `engagementId` referenced should be in `post engagement` or `wrap-up` state.

```javascript
{
    type: "zcc-set-engagement-disposition",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: CHANNEL_TYPE,
        requestId: UNIQUE_REQUEST_ID,
        dispositionId:  DISPOSITION_ID,
    },
};
```

### zcc-close-engagement-wrapup

Complete an engagement or end engagement `wrap-up`. The payload must include

-   `engagementId`
-   `channelType`
-   `requestId`

The `engagementId` must reference a valid engagement, the `channelType` must be one of `voice`, `video`, `chat`, or `sms`, and the `requestId` must be a unique, 128-bit UUID for tracking. Additionally, the `engagementId` referenced should be in `post engagement` or `wrap-up` state.

```javascript
{
    type: "zcc-close-engagement-wrapup",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: CHANNEL_TYPE,
        requestId: UNIQUE_REQUEST_ID,
        note: string, // maximum 2000
    },
};
```

### zcc-engagement-status-request

Udr your application to leverage this event to retrieve engagement details. The payload must include the `channelType` and the `requestId`.

The `channelType` must be `voice`, `video`, `chat`, or `sms`, and the `requestId` must be a unique, 128-bit UUID for tracking. An `engagementId` is optional. If used, it must reference a valid engagement.

On a successful post, the Smart Embed responds with a [`zcc-engagement-status-response`](#zcc-engagement-status-response) event containing the specified engagement details.

```javascript
{
    type: "zcc-engagement-status-request",
    data: {
        engagementId: ENGAGEMENT_ID,
        requestId: UNIQUE_REQUEST_ID,
    },
};
```

### zcc-engagement-status-response

This event is fired in response to the [`zcc-engagement-status-request`](#zcc-engagement-status-request) event. With no provided engagementId in the `zcc-engagement-status-request`, the event returns an object containing information about all available engagements - both in `active` and `wrap-up` state. When an `engagementId` is provided in the event payload request, the returned object only includes data specific to the referenced engagement. The included fields in the returned object are dependent on the engagement channel and data availability.

```javascript
{
    type: "zcc-engagement-status-response",
    data: {
         requestId: UNIQUE_REQUEST_ID,
         active: [
              {
                engagementId: ENGAGEMENT_ID
                channel: ENGAGEMENT_CHANNEL
                engagementDirection: ENGAGEMENT_DIRECTION
                state: ENGAGEMENT_STATE // 'active'
                queueId: THE_QUEUE_ID
                queueName: THE_QUEUE_ID
                customerNumber: CUSTOMER_PHONE_NUMBER
                customerName: CUSTOMER_NAME
                customerEmail: CUSTOMER_EMAIL
                from: CALLER_PHONE_NUMBER,
                to: CALLEES_PHONE_NUMBER,
              }
            ],
         wrapup: [
              {
                engagementId: ENGAGEMENT_ID
                channel: ENGAGEMENT_CHANNEL
                engagementDirection: ENGAGEMENT_DIRECTION
                state: ENGAGEMENT_STATE // 'wrapup'
                queueId: THE_QUEUE_ID
                queueName: THE_QUEUE_ID
                customerNumber: CUSTOMER_PHONE_NUMBER
                customerName: CUSTOMER_NAME
                customerEmail: CUSTOMER_EMAIL
                from: CALLER_PHONE_NUMBER,
                to: CALLEES_PHONE_NUMBER,
            }
         ],
    },
};
```

### zcc-engagement-log-url

When the **Event Logging** feature for a channel is set to **Automatic save of comprehensive engagement log URL**, this event triggers when a wrap-up is saved. The event contains the engagementId and a URL to a page that provides engagement information such as recordings, transcripts, and QM recordings, whenever and if they're accessible.

```javascript
{
    type: "zcc-close-engagement-wrapup",
    data: {
        engagementId: ENGAGEMENT_ID,
        recordingUrl: PAGE_URL,
    },
};
```

### zcc-agent-status-notification

This event fires when there's an update in the agent status.

```javascript
{
    type: "zcc-agent-status-notification",
    data: {
        "statusCode": STATUS_CODE,
        "status": STATUS,
        "parentStatusCode": PARENT_STATUS_CODE [If applicable]
        "subReason": SUB_REASON [If applicable]
    },
};
```

`STATUS_CODE`: The unique identifier associated with the newly assigned agent status.

0 - Offline
1 - Ready
2 - Not Ready
3 - Occupied

When the new status refers to a subreason, the `STATUS_CODE` indicates that subreason's status code.

-   `STATUS` - The status name. Possible values include `Offline`, `Occupied`, `Not Ready`, and `Ready`.
-   `PARENT_STATUS_CODE` [If applicable] - The status code of the parent status. For example, if a new status is a subreason under `Not Ready`, then the `PARENT_STATUS_CODE` would be 2, `Not Ready`.
-   `SUB_REASON` [If applicable] - The subreason's name.

### zcc-agent-status-get-request

Retrieve the agent's current status from the Smart Embed on demand. When your app sends this event, the Smart Embed fires zcc-agent-status-notification in response, providing your app with the agent's current status.

```javascript
{
    type: "zcc-agent-status-get-request",
};
```

### zcc-agent-status-set-request

Set the agent's status, where the status code in the payload must be a valid predefined or preconfigured Contact Center status code. After your app sends this event, the Smart Embed synchronizes and updates the agent status.

```javascript
{
    type: "zcc-agent-status-set-request",
    data: {
         id: STATUS_CODE,
    },
};
```

### zcc-error

This event is fired when Smart Embed encounters any type of error or receives an invalid request.

```javascript
{
    type: "zcc-error",
    data: {
        code: ERROR_CODE,
        message: ERROR_MESSAGE
    },
};
```

### zcc-set-mute

Send this message from your host application to Smart Embed to mute or unmute the agent's microphone on an active voice engagement. Requires `engagementId`, `channelType` (voice), `requestId`, and boolean mute. Validation failures, such as code `invalid-input`, are returned on `zcc-error`.

```javascript
{
    type: "zcc-set-mute",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        mute: true, // or false
    },
}
```

### zcc-set-hold

Send this message to place the voice call on hold or resume it. Same required fields as `mute`, with boolean hold. Failures `invalid-input` for bad input.

```javascript
{
    type: "zcc-set-hold",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        hold: true, // or false
    },
}
```

### zcc-send-dtmf

Send a single DTMF digit into the active voice call. `digit` must be one character from among 0–9, \*, or #.

```javascript
{
    type: "zcc-send-dtmf",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        digit: "1",
    },
}
```

### zcc-set-recording

Control in-call recording on voice. `action` must be `pause`, `resume`, or `stop`. Case-insensitive in the client.

```javascript
{
    type: "zcc-set-recording",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        action: "pause", // "resume" | "stop"
    },
}
```

### zcc-transfer-engagement

Start a voice transfer. `transferType` is `direct r warm`. `destination` is required.

```javascript
{
    type: "zcc-transfer-engagement",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        transferType: "warm", // or "direct"
        destination: DESTINATION_PHONE,
    },
}
```

### zcc-add-call

Add a second leg - such as consult or conference style flow - on voice. `destination` is required. `transferType` defaults to `warm` if omitted.

```javascript
{
    type: "zcc-add-call",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        transferType: "warm", // optional; "direct" | "warm"
        destination: DESTINATION_PHONE,
    },
}
```

### zcc-cancel-consult

Cancel an in-progress consult or warm-transfer leg on voice. You may supply the optional `consultParticipantId` and `reason`.

```javascript
{
    type: "zcc-cancel-consult",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        consultParticipantId: PARTICIPANT_ID, // optional
        reason: REASON, // optional
    },
}
```

### zcc-complete-transfer

Complete a warm transfer, such as an agent leaving after a consult. Voice only. Optional `consultParticipantId`.

```javascript
{
    type: "zcc-complete-transfer",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        consultParticipantId: PARTICIPANT_ID, // optional
    },
}
```

### zcc-merge-consult

Merge consult legs into a conference. Voice only. Optional `consultParticipantId`.

```javascript
{
    type: "zcc-merge-consult",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        consultParticipantId: PARTICIPANT_ID, // optional
    },
}
```

### zcc-upgrade-to-video

Upgrade the active voice engagement to video. `method` must be sms, email, or manual, and is case-insensitive. `destination` is required by validation, such as email for email flow. SMS flow may resolve the number from the current call.

```javascript
{
    type: "zcc-upgrade-to-video",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        requestId: REQUEST_ID,
        method: "email", // "sms" | "email"
        destination: PHONE_OR_EMAIL,
    },
}
```

### zcc-get-disposition-codes

Request wrap-up or disposition codes for an engagement, queue. `requestId` is required. At least one of either `engagementId` or `queueId` must be present. Optional `channelType` is validated against supported channel types. Smart Embed answers with `zcc-get-disposition-codes-response`.

```javascript
{
    type: "zcc-get-disposition-codes",
    data: {
        requestId: REQUEST_ID,
        engagementId: ENGAGEMENT_ID,
        channelType: "voice", // optional
        queueId: QUEUE_ID, // optional
    },
}
```

### zcc-get-disposition-codes-response

Smart Embed sends this to the host after a `zcc-get-disposition-codes` request. `codes` is a list - possibly nested - of disposition objects like `id`, `name`, `description`, `dispositionType`, or the optional `subDispositionList`.

```javascript
{
    type: "zcc-get-disposition-codes-response",
    data: {
        requestId: REQUEST_ID,
        codes: [ /* disposition tree */ ],
    },
}
```

### zcc-send-chat-message

Host-initiated chat message send. `channelType` must be `chat`. `messagePayload` must include at least one `textBody`. Optional `conversationId`, `communicationId`, and `participantId` may be passed through.

```javascript
{
    type: "zcc-send-chat-message",
    data: {
        engagementId: ENGAGEMENT_ID,
        channelType: "chat",
        requestId: REQUEST_ID,
        messagePayload: {
            textBody: "Hello"
        },
        conversationId: CONVERSATION_ID, // optional
        communicationId: COMMUNICATION_ID, // optional
        participantId: PARTICIPANT_ID, // optional
    },
}
```

### zcc-send-chat-message-response

Result of `zcc-send-chat-message`. `status` is boolean. On failure, `errorCode` and `errorMessage` are set.

```javascript
{
    type: "zcc-send-chat-message-response",
    data: {
        requestId: REQUEST_ID,
        status: true,
        timestamp: TIMESTAMP_MS, // optional, success
    },
}
```

## Global custom variable support

For your application to receive custom variable data from Contact Center, send a request for variables.

```javascript
{
    type: "zcc-get-variables",
    data: {
        engagementId: ENGAGEMENT_ID,
    },
}
```

After receiving the above event, the Smart Embed responds with a list of custom variables.

**Note** Smart Embed will only return custom global variables that are configured to display in the desktop client.

```javascript
{
    type: "zcc-get-variables-response",
    data: {
        engagementId: "GrHVH9d9fdlfjlfs8fHrg",
        variables: [
            {
                globalVariableId: VARIABLE_ID,
                globalVariableName: VARIABLE_NAME,
                globalVariableDisplayName: VARIABLE_DISPLAY_NAME,
                globalVariableType: "Global_Variable",
                dataType: DATA_TYPE,
                value: VARIABLE_VALUE,
                screen: "Engagement",
            },
        ],
    },
}
```

<RecentBlogs
    title="From the developer blog"
    categoryId="contact-center"
    tag="smart-embed"
/>

---