zEvents

Most zEvent Notifications correspond to zStatus (read only) or zConfiguration (read-write) changes, and return data structures that are identical to the data structures returned by zStatus and zConfiguration.

However, pure zEvents are events that return structures with a schema that doesn’t correspond to the zStatus or zConfiguration reply structures.

zEvent Pipe OtherControllerLogin

Currently, it is not possible to have both the ZR-CSAPI, and the iPad Zoom Room Controller controlling the Zoom Room. When an iPad Zoom Room Controller logs in, it takes over control of the Zoom room from the ZR-CSAPI. This zEvent is issued, and the ZR-CSAPI loses the pipe connection to the ZR. In order to regain control, isse any ZR-CSAPI command; this action causes the ZR-CSAPI to reconnect, but not execute the command you entered. Then, you can re-enter the command you wish to run.

Schema:

*e Pipe OtherControllerLogin
** end

Example:

*e Pipe OtherControllerLogin
** end

zEvent Pipe Reconnecting

If the ZR-CSAPI loses the pipe connection to the ZR, then when any command is issued, the command will not be executed; instead, this zEvent will be issued, and the ZR-CSAPI will re-establish the pipe connection to the ZR. The desired command must be issued again.

Schema:

*e Pipe Reconnecting
** end

Example:

*e Pipe Reconnecting
** end

zEvent IncomingCallIndication

Issued when an incoming call arrives at the ZR. Typically, another Zoom client will call the Zoom Room by selecting the Zoom Room from the Contact list.

Schema

*e IncomingCallIndication callerJID: <string> // Join ID of the caller. Use this value to Accept the caller using zCommand Call Accept, if the Zoom Room is set to not automatically accept incoming calls.
*e IncomingCallIndication calleeJID: <string> // Typically empty. Join ID of the host of the meeting being called
*e IncomingCallIndication meetingID: <string> // An internal meeting Id used for setting up recording.
*e IncomingCallIndication password: <string> // The password entered by the participant who intends to join.
*e IncomingCallIndication meetingOption: <string> // DEPRECATED
*e IncomingCallIndication meetingNumber: <int> // Meeting number for this meeting
*e IncomingCallIndication callerName: <string> // The name of the caller
*e IncomingCallIndication avatarURL: <string> // Avatar image of the person joining
*e IncomingCallIndication lifeTime: <int> // Scheduled duration of the meeting
** end

Example

*e IncomingCallIndication callerJID: thqrasdqs4wzdnch8kcbiw@xmpp.zoom.us
*e IncomingCallIndication calleeJID: 
*e IncomingCallIndication meetingID: E
*e IncomingCallIndication password: 
*e IncomingCallIndication meetingOption: 6
*e IncomingCallIndication meetingNumber: 766315077
*e IncomingCallIndication callerName: Scott Firestone Testing ZR
*e IncomingCallIndication avatarURL: 
*e IncomingCallIndication lifeTime: 60
** end

zEvent TreatedIncomingCallIndication

When another user directly calls the Zoom Room, and the Zoom Room has been set to not automatically accept incoming calls, the Zoom Room will get an IncomingCallIndication. However, it is possible for the call to end before the Zoom Room accepts or rejects the call via the ZR-CSAPI. In particular:

  • The caller might end the meeting before the Zoom Room accepts or rejects the call.
  • If you hook up a RevoLabs UV 500 speakerphone to the ZR, users can accept/reject incoming calls by pressing buttons on the RevoLabs Speakerphone, rather than through the ZR-CSAPI.

When the call is connected or disconnected before the ZR-CSAPI accepts or rejects the call, you get notification that the call has been accepted or rejected:

Schema:

*e TreatedIncomingCallIndication callerJID: <string>
*e TreatedIncomingCallIndication calleeJID: <string>
*e TreatedIncomingCallIndication meetingID: <string>
*e TreatedIncomingCallIndication password: <string>
*e TreatedIncomingCallIndication meetingOption: <int>
*e TreatedIncomingCallIndication meetingNumber: <int>
*e TreatedIncomingCallIndication callerName: <string>
*e TreatedIncomingCallIndication avatarURL: <string>
*e TreatedIncomingCallIndication lifeTime: <int>
*e TreatedIncomingCallIndication accepted: <on/off>
** end

Example:

*e TreatedIncomingCallIndication callerJID: thqrasdqs4wzdnch8kcbiw@xmpp.zoom.us
*e TreatedIncomingCallIndication calleeJID: 
*e TreatedIncomingCallIndication meetingID: ?
*e TreatedIncomingCallIndication password: 
*e TreatedIncomingCallIndication meetingOption: 6
*e TreatedIncomingCallIndication meetingNumber: 284756735
*e TreatedIncomingCallIndication callerName: Scott Firestone Testing ZR
*e TreatedIncomingCallIndication avatarURL: 
*e TreatedIncomingCallIndication lifeTime: 45
*e TreatedIncomingCallIndication accepted: off
** end

The entries are the same as for the IncomingCallIndication notification, with the addition of the accepted parameter: it is off if the call was rejected, and on if the call was accepted.

zEvent CallDisconnect

Notification that the room exited the meeting

Schema

*e CallDisconnect success : <on/off>
** end

Example

*e CallDisconnect success : on
** end

zEvent CallConnectError

The Zoom Room has encountered an error when connecting

Schema

*e CallConnectError error_code: <int> // An integer error code; It will be 0 if there is no error.
*e CallConnectError error_message: <on/off> // A plain text error message
** end

Example

*e CallConnectError error_code: 0
*e CallConnectError error_message: This meeting has been ended by host. 
** end

ZAAPIconnectFail

An internal error in the ZR-CSAPI

Schema

*e ZAAPIconnectFail
** end

Example

*e ZAAPIconnectFail
** end
ERROR

zEvent Bookings Updated

There has been a change to the list of scheduled meetings. Download the list to see the difference.

Schema

*e Bookings Updated
** end

Example

*e Bookings Updated
** end

zEvent Connection rejected

This limitation will be removed in the January release

Encryption for the link between the ZR and ZRC can be turned on via the web portal, under Account settings -> Zoom Rooms -> Secure connection channel. In this case, the ZR-CSAPI must use encryption for the connection to the ZR; but the ZR-CSAPI has not been upgraded to support encryption. You get the following event notification:

*e Connection rejected
** end

zEvent VideoUnMuteReqeust

This scenario happens if a Zoom Room connects to a meeting, and it is not the host of that meeting, then the meeting host asks the Zoom Room to unmute the ZR video. In this case, the Zoom Room will not automatically unmute its video; instead, the Zoom Room will issue a notification on the CLI that the meeting host has requested the ZR to unmute video:

*e VideoUnMuteRequest ID: 16778241
*e VideoUnMuteRequest isHost: on
*e VideoUnMuteRequest isCoHost: off
** end

The automation controller can react by asking the user if the request for video unmute is granted. After the user grants the unmute video request, the automation controller can unmute the Zoom Room’s video by invoking zConfiguration Call Camera Mute: off

zEvent MeetingNeedsPassword

If you do not enter a password for a meeting that needs it, you get this message after attempting to join:

*e MeetingNeedsPassword needsPassword: true
*e MeetingNeedsPassword wrongAndRetry: false
** end

If you enter the wrong password for a meeting that needs a password, you get this notification:

*e MeetingNeedsPassword needsPassword: true
*e MeetingNeedsPassword wrongAndRetry: true
** end

In some cases, if a meeting does not need a password, you get this notification:

*e MeetingNeedsPassword needsPassword: false
*e MeetingNeedsPassword wrongAndRetry: false
** end

If a password is required, you must re-issue the join command, and specify a password. See the zCommand Dial Join command for details.

zEvent SharingState

If someone starts a sharing session, you get the following notification:

*e SharingState state: <None | Connecting | Sending | Receiving | Send_Receiving>
*e SharingState paused: <on/off>
** end

You also get this notification if someone is running the Zoom Room on a Windows Touch device, and running the white board, and the person launches a sharing meeting from the whiteboard.

zEvent : device change

If someone plugs in, or unplugs, a camera, speaker, or microphone, you get a notification, with a complete list of the current devices. This notification is related to three status commands:

zStatus Audio Input Line
zStatus Audio Output Line
zStatus Video Camera Line

For instance, if someone plugs in a Logitech HD Pro Webcam C920, that adds a new camera and a new microphone, you get an updated list of cameras and microphones:

*s Video Camera Line 1 id: CDC85FD0-E73A-4FC2-B3A8-EA237D6990E0
*s Video Camera Line 1 Name: CamTwist
*s Video Camera Line 1 Alias: usb:7D69:90E0
*s Video Camera Line 2 id: 0x14200000046d082d
*s Video Camera Line 2 Name: HD Pro Webcam C920
*s Video Camera Line 2 Alias: usb:046D:082D
*s Video Camera Line 3 id: CDC85FD0-E73A-4FC2-B3A8-EA237D6990E1
*s Video Camera Line 3 Name: CamTwist (2VUY)
*s Video Camera Line 3 Alias: usb:7D69:90E1
** end

*s Audio Input Line 1 id: Sennheiser SC70 USB CTRL
*s Audio Input Line 1 Name: Sennheiser SC70 USB CTRL
*s Audio Input Line 1 Alias: 
*s Audio Input Line 2 id: HD Pro Webcam C920
*s Audio Input Line 2 Name: HD Pro Webcam C920
*s Audio Input Line 2 Alias: 
*s Audio Input Line 3 id: Built-in Input
*s Audio Input Line 3 Name: Built-in Input (Line In)
*s Audio Input Line 3 Alias: 
*s Audio Input Line 4 id: Soundflower (2ch)
*s Audio Input Line 4 Name: Soundflower (2ch)
*s Audio Input Line 4 Alias: 
*s Audio Input Line 5 id: Soundflower (64ch)
*s Audio Input Line 5 Name: Soundflower (64ch)
*s Audio Input Line 5 Alias: 
** end

zEvent NeedWaitForHost

when you join a pre-scheduled meeting by invoking zCommand Dial Join MeetingNumber: You will immediately get a notification to indicate whether you need to wait for the host to join the meeting.

Schema:

*e NeedWaitForHost Wait: <bool>
** end

If the host has not enabled JBH (join before host) for the meeting, then you must wait. In the case that you need to wait, you get:

*e NeedWaitForHost Wait: on
** end

Followed by another notification, once the host joins:

*e NeedWaitForHost Wait: off
** end

Or, if you join a meeting that allows JBH, then you get a notification immediately, indicating that you don’t have to wait:

*e NeedWaitForHost Wait: off
** end

zEvent OpenVideoFailForHostStop

When in a meeting, the host is able to turn off the video coming from any participant, including Zoom Rooms. If the host turns off the video coming from a Zoom Room, then the Zoom Room will not be able to turn the video back on, until the host allows it. If the video from the Zoom Room is currently disabled, and the Zoom Room tries to unmute its camera, you will first get an error for the unmute operation, then you will get an event indicating that the host has disabled video from the Zoom Room:

Schema:

*e Message Event: <Unknown | OpenVideoFailForHostStop>
** end

Example:

zConfiguration Call Camera Mute: off
*r Configuration (status=Error):
** end
ERROR
*e Message Event: OpenVideoFailForHostStop
** end

The host can ask the Zoom Room to re-enable its camera video by sending a request to unmute. The ZR-CSAPI will provide a notification when this request happens:

*e VideoUnMuteRequest ID: 16779265
*e VideoUnMuteRequest isHost: on
*e VideoUnMuteRequest isCoHost: off
** end

Then, the Zoom room can successfully unmute its video:

zConfiguration Call Camera Mute: off
** end
OK

zEvent AddedContact

Notification when a new contact is added to the Zoom Room’s phonebook.

Schema:

*e Phonebook Added Contact n jid: <string> / the Join Id of the contact.
Use this ID to invite a person to a meeting.
*e Phonebook Added Contact n screenName: <string> // the Zoom IM ScreenName of the contact
*e Phonebook Added Contact n firstName: <string>
*e Phonebook Added Contact n lastName: <string>
*e Phonebook Added Contact n phoneNumber: <string> // the phone number of the contact
*e Phonebook Added Contact n email: <string> // the email of the contact
*e Phonebook Added Contact n avatarURL: <string> / a URL pointing to the avatar of the contact, if available
*e Phonebook Added Contact n presence: <PRESENCE_OFFLINE, PRESENCE_ONLINE, PRESENCE_AWAY, PRESENCE_BUSY, PRESENCE_DND> 
*e Phonebook Added Contact n onDesktop: <on/off> // Set to on if the user is currently using a desktop client. Only valid if the presence status is PRESENCE_ONLINE.
*e Phonebook Added Contact n onMobile: <on/off> // Set to on if the user is currently using a mobile Zoom client. Only valid if the presence status is PRESENCE_ONLINE.
*e Phonebook Added Contact n isZoomRoom: <on/off> / Set to on if the user is a zoom room.
*e Phonebook Added Contact n isLegacy: <on/off> / Set to on if the user is currently using a legacy platform (Ex. SIP/H323).
*e Phonebook Added Contact n presence_status: <int>
*e Phonebook Added Contact n sip_phone_number: <string> // sip_phone_number if applicable
*e Phonebook Added Contact n cloud_pbx_info isValid: <on/off> // Whether cloud_pbx is on/off
*e PhoneBook Added Contact n cloud_pbx_info extension: <string> //Only if cloud_pbx_info isValid is on
*e PhoneBook Added Contact n cloud_pbx_info company_number: <string> //Only if cloud_pbx_info isValid is on
*e PhoneBook Added Contact n cloud_pbx_info direct_number_list: m direct_number: <string> //Only if cloud_pbx_info isValid is on
** end

Example:

*e Phonebook Added Contact 22 jid: H323_SIP_00000005
*e Phonebook Added Contact 22 screenName: testcontact
*e Phonebook Added Contact 22 firstName: 
*e Phonebook Added Contact 22 lastName: 
*e Phonebook Added Contact 22 phoneNumber: 
*e Phonebook Added Contact 22 email: 
*e Phonebook Added Contact 22 avatarURL: 
*e Phonebook Added Contact 22 presence: PRESENCE_OFFLINE
*e Phonebook Added Contact 22 onDesktop: off
*e Phonebook Added Contact 22 onMobile: off
*e Phonebook Added Contact 22 isZoomRoom: off
*e Phonebook Added Contact 22 isLegacy: on
*e Phonebook Added Contact 22 presence_status: 0
*e Phonebook Added Contact 22 sip_phone_number: 
*e Phonebook Added Contact 22 cloud_pbx_info isValid: off
** end

zEvent UpdatedContact

Notification when a contact in the Zoom Room’s phonebook is updated.

Schema:

*e Phonebook Updated Contact n jid: <string> / the Join Id of the contact.
Use this ID to invite a person to a meeting.
*e Phonebook Updated Contact n screenName: <string> // the Zoom IM ScreenName of the contact
*e Phonebook Updated Contact n firstName: <string>
*e Phonebook Updated Contact n lastName: <string>
*e Phonebook Updated Contact n phoneNumber: <string> // the phone number of the contact
*e Phonebook Updated Contact n email: <string> // the email of the contact
*e Phonebook Updated Contact n avatarURL: <string> / a URL pointing to the avatar of the contact, if available
*e Phonebook Updated Contact n presence: <PRESENCE_OFFLINE, PRESENCE_ONLINE, PRESENCE_AWAY, PRESENCE_BUSY, PRESENCE_DND> 
*e Phonebook Updated Contact n onDesktop: <on/off> // Set to on if the user is currently using a desktop client. Only valid if the presence status is PRESENCE_ONLINE.
*e Phonebook Updated Contact n onMobile: <on/off> // Set to on if the user is currently using a mobile Zoom client. Only valid if the presence status is PRESENCE_ONLINE.
*e Phonebook Updated Contact n isZoomRoom: <on/off> // Set to on if the user is a zoom room.
*e Phonebook Updated Contact n isLegacy: <on/off> / Set to on if the user is currently using a legacy platform (Ex. SIP/H323).
*e Phonebook Updated Contact n presence_status: <int>
*e Phonebook Updated Contact n sip_phone_number: <string> // sip_phone_number if applicable
*e Phonebook Updated Contact n cloud_pbx_info isValid: <on/off> // Whether cloud_pbx is on/off
*e PhoneBook Updated Contact n cloud_pbx_info extension: <string> //Only if cloud_pbx_info isValid is on
*e PhoneBook Updated Contact n cloud_pbx_info company_number: <string> //Only if cloud_pbx_info Updated is on
*e PhoneBook Updated Contact n cloud_pbx_info direct_number_list: m direct_number: <string> //Only if cloud_pbx_info isValid is on
** end

Example:

*e Phonebook Updated Contact 22 jid: H323_SIP_00000005
*e Phonebook Updated Contact 22 screenName: testcontact
*e Phonebook Updated Contact 22 firstName: 
*e Phonebook Updated Contact 22 lastName: 
*e Phonebook Updated Contact 22 phoneNumber: 
*e Phonebook Updated Contact 22 email: 
*e Phonebook Updated Contact 22 avatarURL: 
*e Phonebook Updated Contact 22 presence: PRESENCE_OFFLINE
*e Phonebook Updated Contact 22 onDesktop: off
*e Phonebook Updated Contact 22 onMobile: off
*e Phonebook Updated Contact 22 isZoomRoom: off
*e Phonebook Updated Contact 22 isLegacy: on
*e Phonebook Updated Contact 22 presence_status: 0
*e Phonebook Updated Contact 22 sip_phone_number: 
*e Phonebook Updated Contact 22 cloud_pbx_info isValid: off
** end

zEvent UpdatedCallRecordInfo

Notification when the recording status of the Zoom Room changes.

Schema:

*e UpdateCallRecordInfo canRecord: <true/false> // Can Zoom Room record
*e UpdateCallRecordInfo emailRequired: <true/false> // Is email required? Or email already stored in meeting?
*e UpdateCallRecordInfo amIRecording: <true/false> // Is Zoom Room currently recording
*e UpdateCallRecordInfo meetingIsBeingRecorded: <true/false> //Is the meeting currently being recorded by anyone, NOTE: This is not completely reliable yet
** end

Example:

*e UpdateCallRecordInfo canRecord: true
*e UpdateCallRecordInfo emailRequired: true
*e UpdateCallRecordInfo amIRecording: false
*e UpdateCallRecordInfo meetingIsBeingRecorded: false
** end

zFeedback

Use the zFeedback mechanism to subscribe or unsubscribe from zEvent notifications, so that you receive a subset of notifications from the ZR-CSAPI.

You determine which events you receive by adding filters to two different filter sets:

  • an inclusion filter set
  • an exclusion filter set Each filter consists of a path node in the command hierarchy. A zEvent matches a filter if the zEvent is at or below the path node. The filtering is a 2-phase process: First, an incoming zEvent is compared to the filters in the incluion set. If the zEvent does not match any filter, the ZR-CSAPI drops the zEvent. Otherwise, the ZR-CSAPI compares the zEvent to the filters in the exclusion set. If the zEvent matches any filter, it will be dropped; otherwise, it will become a notification from the ZR-CSAPI.

The idea is to add a few filters to the inclusion set to establish the broad categories of zEvents that you wish to receive; you typically specify a few path nodes that are higher up in the hierarchy. Then, add filters to the exclusion set that specify path nodes further down in the hierarchy, to carve out small subsets of zEvents near the leaves of the hierarchy that you don’t want to receive.

The top of the hierarchy consists of three path nodes: /Status /Configuration /Events

You can get a list of filters in both sets using this command:

zFeedback List

By default, the ZR-CSAPI launches with these settings:

Inclusion set:

  • /Status
  • /Configuration
  • /Event

Exclusion set: empty.

For example, it can be annoying to receive the very large callin_country_list when you get the zEvent InfoResult notification message:

Example:

zcommand call info                    
OK
*r InfoResult (status=OK):
*r InfoResult Info real_meeting_id: euBIzGp3S5i7qjrifE87vQ==
*r InfoResult Info meeting_id: 5526136251
*r InfoResult Info participant_id: 34
*r InfoResult Info my_userid: 16778240
*r InfoResult Info am_i_original_host: on
*r InfoResult Info is_webinar: off
*r InfoResult Info is_view_only: off
*r InfoResult Info meeting_type: NORMAL
*r InfoResult Info meeting_password: 
*r InfoResult Info dialIn: +1 669 900 6833;+1 646 558 8656
*r InfoResult Info toll_free_number: 
*r InfoResult Info international_url: /zoomconference
*r InfoResult Info is_toll_free_callin_list_available: on
*r InfoResult Info is_callin_country_list_available: on
*r InfoResult Info is_calling_room_system_enabled: on
*r InfoResult Info support_callout_type: NONE
*r InfoResult Info user_type: PRO
*r InfoResult Info callin_country_list 1 id: AR
*r InfoResult Info callin_country_list 1 name: Argentina
*r InfoResult Info callin_country_list 1 code: 54
*r InfoResult Info callin_country_list 1 number: 54 3415122188
*r InfoResult Info callin_country_list 1 display_number: +54 341 512 2188
*r InfoResult Info callin_country_list 2 id: AR
*r InfoResult Info callin_country_list 2 name: Argentina
*r InfoResult Info callin_country_list 2 code: 54
*r InfoResult Info callin_country_list 2 number: 54 3434145986
*r InfoResult Info callin_country_list 2 display_number: +54 343 414 5968
*r InfoResult Info callin_country_list 3 id: AU
*r InfoResult Info callin_country_list 3 name: Australia
*r InfoResult Info callin_country_list 3 code: 61
*r InfoResult Info callin_country_list 3 number: 61 280152088
*r InfoResult Info callin_country_list 3 display_number: +61 (0) 2 8015 2088
*r InfoResult Info callin_country_list 4 id: AU
...

The path node of the hierarchy for the callin_country_list section of the notification is:

/Events/InfoResult/info/callin_country_list

In order to avoid receiving this list, while still receiving the other fields in the InfoResult notification, use the zFeedback Register command, with the Operation set to ex, to add this path node to the exclusion set:

zFeedback Register Op: ex Path: /Event/InfoResult/info/callin_country_list

The path is case-insensitive.

Currently, the zFeeback mechanim applies only to /Event/InfoResult/info/callin_country_list, and only for the CLI responses, not the JSON reponses. The idea is to make the CLI more usable. The zFeedback mechanism will be extended later to other notifications, and to both the CLI and JSON responses.

zFeedback Register

Add a filter to either the inclusion or exclusion filter set

Schema

zFeedback Register Op: <in | ex> Path: <string>
** end
OK

Example

zFeedback Register Op: ex Path: /Event/InfoResult/info/callin_country_list
** end
OK

Op: The operation: either add the filter to the inclusion list, or the exclusion list.

Path: The path node in the hierarchy. a zEvent will match the filter if it it located at the same level, or below, this path node.

zFeedback Deregister

Schema

zFeedback Deregister Path: <string>
** end
OK

Example

zFeedback Deregister Path: /Event/InfoResult/info/callin_country_list
** end
OK

Path: The path node in the hierarchy to remove from both the inclusion set and the exclusion set.

zFeedback List

List all filters in the inclusion set and the exclusion set.

Schema

zFeedback list
*f in: <string>
...
*f ex: <string>
** end
OK

Example

zFeedback list
*f in: /Configuration
*f in: /Event
*f in: /Status
** end
OK

zFeedback Deregisterall

Remove all filters from all sets

Schema

zFeedback Deregisterall
** end
OK

Example

zFeedback Deregisterall
** end
OK

zEvent PhonebookBasicInfoChange

Notification when the number of contacts in the phonebook changes.

Schema:

*e PhonebookBasicInfoChange status: <notInMeeting, inMeeting>  
*e PhonebookBasicInfoChange numberOfZoomRoom: <int>  // the number of Zoom Room contacts
*e PhonebookBasicInfoChange numberOfLegacyRoom: <int>   // the number of Legacy(H323) Room contacts
*e PhonebookBasicInfoChange numberOfNormalContact: <int>  // the number of normal contacts
*e PhonebookBasicInfoChange total: <int>  // The sum of the above
** end

Example:

*e PhonebookBasicInfoChange status: notInMeeting
*e PhonebookBasicInfoChange numberOfZoomRoom: 924
*e PhonebookBasicInfoChange numberOfLegacyRoom: 13
*e PhonebookBasicInfoChange numberOfNormalContact: 2412
*e PhonebookBasicInfoChange total: 3349
** end