Smart Embed Error Handling

Zoom Contact Center Smart Embed uses different error handling patterns depending on the type of event.

Client-side validation errors

The zcc-error event fires for client-side validation failures before a request reaches the Smart Embed backend.

{
    type: "zcc-error",
    data: {
        code: ERROR_CODE, // e.g., "invalid-input"
        message: ERROR_MESSAGE
    },
};

For transfer and conference events, errors are returned on the operation-specific response event, such as zcc-transfer-engagement-response, with status: false instead of using this generic error event.

Transfer and conference error handling

Transfer and conference events use a unified error handling pattern. These events include zcc-transfer-engagement, zcc-add-call, zcc-complete-transfer, zcc-merge-consult, and zcc-cancel-consult.

Unlike client-side validation failures that trigger the generic zcc-error event, these events return both success and failure results on the same response event, for example zcc-transfer-engagement-response.

Response pattern

Every transfer and conference response event includes a status field.

Success - status is true with operation-specific fields like consultState, destinationSummary, holdState
Failure- status is false with additional errorCode, error, and message fields

Common response fields

All transfer and conference response events share base fields.

Field	Type	Details
`status`	boolean	`true` on success, `false` on failure
`requestId`	string	Echoes the request's `requestId`
`engagementId`	string	Active voice engagement ID
`channelType`	string	Always `"voice"`
`taskSid`	string	Internal task ID of the active call
`conferenceId`	string	Conference ID when the call is in a conference
`transferType`	string	`"direct"` or `"warm"` (when applicable)
`timestamp`	number	Epoch milliseconds when the response was built
`holdState`	boolean	Current hold state of the active leg
`consultState`	string	One of: `initiated`, `ringing`, `answered`, `bridged`, `completed`, `cancelled`, `merged`
`destinationSummary`	object	Normalized target with `kind` (`user`, `queue`, `flow`, `pstn`, `unknown`), `id`, `name`, `queueId`, `queueName`, `value`
`transferId`	string	Transfer identifier (when provided by backend)
`inviter_leg_channel_id`	string	Channel identifier (when provided by backend)
`errorCode`	string	Failure only. Indicates the specific error type
`error`	string	Failure only. Human-readable error message
`message`	string	Failure only. Same as `error` field

Common error codes

Transfer and conference events may return error codes.

engagement-mismatch - Provided engagement ID does not match the active engagement
no-active-call - No active voice call found for the engagement
unsupported-destination - The destination format or type is not supported
transfer-failed - Transfer operation failed
add-call-failed - Adding consult or conference leg failed
add-call-panel-missing - Required UI panel is not available
no-active-warm-transfer - No warm transfer in progress to complete
complete-transfer-failed - Completing the warm transfer failed
no-active-conference-consult - No conference consult leg to merge
merge-consult-failed - Merging the conference failed
no-active-consult - No active consult leg to cancel
cancel-consult-target-missing - Consult target information is missing
cancel-consult-failed - Canceling the consult failed

Error response example

This example shows the unsupported-destination error.

{
    type: "zcc-transfer-engagement-response",
    data: {
        status: false,
        requestId: REQUEST_ID,
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        taskSid: TASK_SID,
        conferenceId: CONFERENCE_ID,
        transferType: "warm",
        timestamp: TIMESTAMP_MS,
        holdState: false,
        consultState: "initiated",
        errorCode: "unsupported-destination",
        error: "The specified destination is not supported",
        message: "The specified destination is not supported",
    },
}