Active Meeting Management API

The active meeting management API enables real-time management of meetings that are currently in progress. In contrast, the scheduling API enables you to schedule and modify future meetings.

With the active meeting management API, you can develop client applications for monitoring and controlling active meetings, typically by concierge or service desk personnel.

Topics in this section include:

•Obtaining the WSDL File

•API Methods

•Error Handling

Obtaining the WSDL File

You can access the WSDL file for the active meeting management API at
http://administration-server-hostname-or-IP-address:8080/ctxapi/api/v1_1/amm?wsdl

The WSDL file provides a complete and accurate definition of the API that is supported by your Cisco TelePresence Exchange System. In the event of any discrepancies between the WSDL file and this document, you should follow the WSDL file definition.

API Methods

All active meeting management API methods are described in alphabetical order in the following sections:

•dropParticipant

•echo

•getActiveMeetings

•getCurrentMeetingStatus

•getVersion

•lockMeeting

•modifyActiveMeeting

•muteAllExcept

•muteParticipant

•redialParticipant

•sendEndpointText

•sendEndpointTextToParticipant

•unlockMeeting

•unMuteAll

•unMuteParticipant

dropParticipant

This method removes a specified participant from an active meeting and hangs up on the endpoint of the participant.

Table 3-1 describes the input parameters for the Drop Participant service request.

Table 3-1 Drop Participant Request Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting. You can obtain the meeting key via the getMeeting method in the scheduling API.

participant

String

E.164 number or URI of the endpoint.


The Drop Participant service returns a success or fault message. There is no response data returned.

echo

The Echo service allows the system to confirm that the CDR API service is active. For additional details about this service, see the "echo" section.

getActiveMeetings

This method provides information about all active meetings. You can filter results by including values for the optional parameters in the request.

Table 3-2 describes the fields in the Get Active Meetings request.

Table 3-2 Get Active Meetings Request Parameters 

Parameter
Type
Description

meetingId

String

(Optional) Meeting identifier that the meeting participant enters to join the meeting after dialing the access number.

accessNumber

String

(Optional) Dial-in number that meeting participants call to join the meeting.

scheduler

String

(Optional) Email address of the meeting scheduler.

startingTimeWindowFrom

String

(Optional) Earliest start time of meetings that you want the system to return in the response.

startingTimeWindowTo

String

(Optional) Latest start time of meetings that you want the system to return in the response.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


The service response returns a Get Active Meetings Result, which includes a list of activeMeeting elements. Table 3-3 describes the activeMeeting element.

Table 3-3 activeMeeting Element 

Parameter
Type
Description

bridgeResource

String

Provisioned name of the media resource that is providing the meeting bridge and media bridge resources for a meeting.

bridgeResourceType

Enumeration

Media bridge resource type. One of the following values:

•CTMS—Cisco TelePresence Multipoint Switch

•TPS—Cisco TelePresence Server MSE 8710

•TPS_8510—Cisco TelePresence MCU MSE 8510

endTime

Date/time string

Scheduled end time of the meeting.

meetingId

String

Meeting identifier that the meeting participant enters to join the meeting after dialing the access number.

meetingKey

Integer

Unique key that the system uses to identify the meeting. You can obtain the meeting key via the getMeeting method in the scheduling API.

numberOfParticipants

Integer

The number of participants that are currently attending the meeting.

schedulerOrganizationKey

Integer

Unique key that the system assigned to the organization of the meeting scheduler.

startTime

String

Start time of the meeting. For a Rendezvous meeting, this is the start time of the current meeting instance.

subject

String

Text subject of the meeting.


getCurrentMeetingStatus

This method obtains status information about the specified active meeting.

Table 3-4 describes the fields in the Get Current Meetings request.

Table 3-4 Get Current Meetings Request Parameters 

Parameter
Type
Description

meetingKey

String

Enter the unique key that the system uses to identify the meeting.


The service returns a GetCurrentMeetingStatusResult in the service response, which includes a list of apiMeetingStatus elements. Table 3-5 describes the apiMeetingStatus element.

Table 3-5 apiMeetingStatus Element 

Parameter
Type
Description

activeParticipants

Complex

Contains one or more participantsInCurrentMeeting elements. This element is described in Table 3-6.

bridgeResourceName

String

Provisioned name of the media resource that is providing the meeting bridge and media bridge resources for a meeting.

bridgeResourceType

Enumeration

Media bridge resource type. One of the following values:

•CTMS—Cisco TelePresence Multipoint Switch

•TPS—Cisco TelePresence Server MSE 8710

•TPS_8510—Cisco TelePresence MCU MSE 8510

endTime

Date/time string

Scheduled end time of the meeting.

meetingId

String

Meeting identifier that the meeting participant enters to join the meeting after dialing the access number.

organizationKey

Integer

Unique key that the system uses to identify the organization.

scheduledProvisionedEndpoints

Complex

Contains one or more apiProvisionedEndpoint elements. This element is described in Table 3-7.

unscheduledProvisionedEndpoints

Complex

Contains one or more apiUnprovisionedEndpoint elements. This element is described in Table 3-8.

startTime

String

Start time of the meeting. For a Rendezvous meeting, this is the start time of the current meeting instance.

subject

String

Text subject of the meeting.


Table 3-6 describes the participantsInCurrentMeeting element.

Table 3-6 participantsInCurrentMeeting Element

Parameter
Type
Description

numScreens

Int

Number of media bridge resource segments that are reserved for a scheduled participant or that are allocated for an active participant. Each segment represents one screen of video transmission or one 30-fps data channel.

number

String

E.164 number or URI of the endpoint.

videoBandwidth

Int

Video bandwidth used by the participant. This parameter is relevant only for Meet-Me meeting calls.

For a SIP endpoint, the value is determined based on the last maximum negotiated bandwidth from the SIP messages exchanged between the client and MCU.

For an H323 or ISDN endpoints, the value is reported from the MCU.

isMuted

Boolean

Set to TRUE if the active participant is currently muted.

Note Mute status is not available for participants on the Cisco TelePresence Multipoint Switch (CTMS).

isHost

Boolean

Set to TRUE if the participant joined the meeting as the host.

joinTime

String

Time that the meeting participant joined the meeting. The time is in ISO8601 format.

Note The Cisco TelePresence Exchange System does not consider the participant as having joined the meeting until after any interaction with the IVR prompts is complete.

isDialout

Boolean

Set to TRUE if the Cisco TelePresence Exchange System dialed out to reach the endpoint.


Table 3-7 describes the apiProvisionedEndpoint element.

Table 3-7 apiProvisionedEndpoint Element

Parameter
Type
Description

endpointName

String

Endpoint name.

mediaProfileKey

String

Unique key of the media profile associated with this endpoint.

number

String

E.164 number or URI of the endpoint.


Table 3-8 describes the apiUnprovisionedEndpoint element.

Table 3-8 apiUnprovisionedEndpoint Element

Parameter
Type
Description

dialOut

Boolean

Set to TRUE if the system dialed out to the participant.

mediaProfileKey

String

Unique key of the media profile associated with this endpoint.

number

String

E.164 number or URI of the endpoint.

organizationKey

String

Unique key of the organization associated with this endpoint.

ports

Int

Number of ports of bandwidth to allocate for the endpoint.


getVersion

The Get Version service returns the product software version. For additional details about this service, see the "getVersion" section.

lockMeeting

This method blocks any more users from dialing into a specified meeting. Dial-out endpoints are not affected by whether a meeting is locked or unlocked.

Table 3-9 describes the input parameters for the Lock Meeting service request.

Table 3-9 Lock Meeting Request Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.


The Lock Meeting service returns a success or fault message. There is no response data returned.

modifyActiveMeeting

This method modifies a specified meeting that is currently in progress. Table 3-10 describes the input parameters for the Modify Active Meeting service request. Except where otherwise specifically noted in the table, null parameter values are set for fields that you do not want to change.

Note The Modify Active Meeting service request must include the meeting key of the meeting that you want to modify.

Note When modifying a meeting, any endpoint lists that were previously defined for the meeting must be specified completely, even if there are no changes. A null value cannot be used to indicate that there are no changes to the endpoint lists.

Table 3-10 modifyActiveMeeting Element 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

newDuration

String

(Optional) New duration of meeting, in minutes.

newProvisionedEndpoints

Complex

Contains one or more apiProvisionedEndpoint elements. This element is described in Table 3-7.

Note The list must include all of the provisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

newUnprovisionedEndpoints

Complex

Contains one or more apiUnprovisionedEndpoint elements. This element is described in Table 3-8.

Note The list must include all of the unprovisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

newRemoteEndpointList

Complex

Contains one or more endpoints from a remote system.

Note The list must include all of the remote endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

newAdditionalCapacity

Integer

(Optional) Number of additional segments of media bridge capacity to allocate for the meeting.

Use this parameter to reserve media bridge resources for endpoints that you do not add to the meeting but that you expect to join the meeting. To determine how many segments to add for each endpoint, use the following guidelines, depending on which media resource provides the meeting bridge:

•Cisco TelePresence Multipoint Switch—Add 4 segments for each three-screen endpoint and 2 segments for each single-screen endpoint.

•Cisco TelePresence MCU MSE 8510—Add 1 segment for each endpoint. Only single-screen endpoints are supported.

•Cisco TelePresence Server MSE 8710—Add 3 segments for each three-screen endpoint and 1 segment for each single-screen endpoint.

newLayoutID

Integer

(Optional) Enter a default value for the screen layout.

This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

For details on the layout values, see the "Custom Layouts" section.

newIsHostRoleEnabled

Boolean

(Optional) Element set to TRUE if the host role is enabled.

newHostPin

String

(Optional) Enter a numerical host PIN for the meeting. By default, the system will create a random PIN.

Note Only set a host PIN if the host role is enabled.

newMeetingExtensionEnabledType

Complex

(Optional) Whether meeting extensions are enabled for the meeting. One of the following values:

•DISABLE—Disables meeting extensions for the meeting.

•ENABLE—Enables meeting extensions for the meeting.

•INHERIT—Inherits the setting (either DISABLE or ENABLE) from the organization of the meeting scheduler.

newMeetingExtensionPeriod

Integer

(Optional) Number of minutes to extend the meeting if participants are still in the meeting when it is scheduled to end.

newMaxMeetingExtensionsAllowed

Integer

(Optional) Maximum number of times that the meeting can be extended.

newSchedulerOrgKey

String

(Optional) Organization key of the scheduler.


The service returns a Modify Active Meeting Result. Table 3-11 describes the Modify Active Meeting Result.

Table 3-11 Modify Active Meeting Result Parameters 

Parameter
Type
Description

capacityAllocated

Integer

Number of segments of media bridge capacity that is allocated to the meeting.


muteAllExcept

This method mutes all participants in a meeting except a list of specified participants.

Table 3-12 describes the input parameters for the Mute All Except service request.

Table 3-12 Mute All Except Request Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

participant

String

E.164 number (such as "14085551234") or URI of the endpoint.

Note you can specify multiple participants.


The Mute All Except service returns a success or fault message. There is no response data returned.

muteParticipant

This method mutes a list of specified participants.

Table 3-13 describes the input parameters for the Mute Participant service request.

Table 3-13 Mute Participant Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

participant

String

E.164 number (such as "14085551234") or URI of the endpoint.

Note you can specify multiple participants.


The Mute Participant service returns a success or fault message. There is no response data returned.

redialParticipant

This method initiates a dial-out call to a specified participant.

Table 3-14 describes the input parameters for the Redial Participant service request.

Table 3-14 Redial Participant Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

participant

String

E.164 number (such as "14085551234") or URI of the endpoint.

Note you can specify multiple participants.


The Redial Participant service returns a success or fault message. There is no response data returned.

sendEndpointText

This method sends text to display on all endpoints that are in the meeting.

Note The endpoint text display feature is not supported for meetings that are hosted on a Cisco TelePresence Multipoint Switch.

Table 3-15 describes the input parameters for the Send Endpoint Text service request.

Table 3-15 Send Endpoint Text Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

endpointMessage

String

Text message that you want to display in the meeting.


The Send Endpoint Text service returns a success or fault message. There is no response data returned.

sendEndpointTextToParticipant

This method sends text to display on one or more specified endpoints.

Note The endpoint text display feature is not supported for meetings that are hosted on a Cisco TelePresence Multipoint Switch.

Table 3-16 describes the input parameters for the Send Endpoint Text To Participant service request.

Table 3-16 Send Endpoint Text To Participant Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

participant

String

E.164 number (such as "14085551234") or URI of the endpoint.

Note you can specify multiple participants.

endpointMessage

String

Text message that you want to display in the meeting.


The Send Endpoint Text To Participant service returns a success or fault message. There is no response data returned.

unlockMeeting

This method enables new participants to dial into a previously locked meeting. Dial-out endpoints are not affected by whether a meeting is locked or unlocked.

Table 3-17 describes the input parameters for the Unlock Meeting service request.

Table 3-17 Unlock Meeting Request Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.


The Unlock Meeting service returns a success or fault message. There is no response data returned.

unMuteAll

This method unmutes all participants in a meeting.

Table 3-18 describes the input parameters for the Unmute All service request.

Table 3-18 Unmute All Request Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.


The Unmute All service returns a success or fault message. There is no response data returned.

unMuteParticipant

This method unmutes one or more specified participants in a meeting.

Table 3-19 describes the input parameters for the Unmute Participant service request.

Table 3-19 Unmute Participant Parameters 

Parameter
Type
Description

meetingKey

String

Unique key that the system uses to identify the meeting.

participant

String

E.164 number (such as "14085551234") or URI of the endpoint.

Note you can specify multiple participants.


The Unmute Participant service returns a success or fault message. There is no response data returned.

Error Handling

The Cisco TelePresence Exchange System API communicates an error condition to the client by returning a SOAP fault message. The fault message contains an API Active Meetings Management Exception, which is described in Table 3-20.

Table 3-20 API ActiveMeetingsManagement Exception 

Parameter
Type
Description

cause code

String

(Optional) Provides more detailed information about an exception return code.

The cause codes are listed in the "Cause Codes" section.

erc

String

Exception return code.

Note For information on API Active Meetings Management Exception values, see the "Exception Values" section.

message

String

English text message that provides additional information about the exception code. The content of the message varies depending on the exception code.

Note This message is not localized. Therefore, Cisco recommends that the message string not be displayed to the end user directly, due to the possibility that the portal may cater to multiple languages.

value map

String

(Optional) A name/value map in which each element is a pair of strings (a key and a value). The key identifies the type of entity, and the value identifies the specific instance that caused the exception.

Possible key values are as follows:

MEETING_KEY
ENDPOINT_KEY
ORGANIZATION_KEY
SERVICE_PROVIDER_KEY
REGION_KEY
MEETING_ENDPOINT_KEY
SERVICE_NUMBER_KEY
RESERVATION_TYPE_KEY
MEDIA_PROFILE_KEY
SUBSCRIPTION_KEY


Exception Values

Table 3-21 describes the exception values.

Table 3-21 API Active Meeting Management Exception Values 

Exception Value
Description or Cause Code

ERC_EXCEPTION

General exception. See the message string for more information about the exception.

ERC_MISSING_PARAMETER

One or more of the required parameters are missing.

ERC_INVALID_VALUE

Generic exception for a bad parameter value from the client.

ERC_INVALID_DATE_TIME

The date and time in the request are invalid.

ERC_LICENSE_ERROR

The Cisco TelePresence Exchange System requires a valid meeting service license.

ERC_SERVICE_PROVIDER_NOT_FOUND

The service provider in the request does not match a provisioned service provider in the system.

ERC_ORGANIZATION_NOT_FOUND

The organization in the request does not match a provisioned service provider in the system.

ERC_RESTORE_IN_PROGRESS

A database restore is in progress; therefore, no requests can be handled. When the restore is complete, requests can be handled. A database restore may take several minutes.

ERC_STRING_TOO_LONG

The parameter string is too long.

ERC_NOT_FOUND

The provided key does not resolve to a valid item.

ERC_BRIDGE_COMMUNICATION_ERROR

An error occurred while calling an API method on the bridge resource. For example, if your bridge is an unsupported version, then it may return an error when the Cisco TelePresence Exchange System tries to call a particular method.

ERC_INTERNAL_ACTIVE_MEETINGS_MANAGEMENT_EXCEPTION

General exception; see the message text for more information.

ERC_MODIFICATION_EXCEPTION

General exception; see the message text for more information.

ERC_MISMATCHED_SERVICE_PROVIDER

The service provider in the request does not match the provisioned service provider that is associated with the specified resource (endpoint or region).

ERC_CALL_CONTROL_EXCEPTION

Internal exception related to the call-control part of Cisco TelePresence Exchange System. See the message text for more information.

ERC_CANNOT_ACCESS_OR_CONTROL_ACTIVE_MEETING

Unable to retrieve active meeting status necessary for controlling participants in an active meeting.


Cause Codes

The list of possible cause codes includes the following:

CANNOT_ADD_UNSUPPORTED_ENDPOINT
CANNOT_CHANGE_DROP_PARTICIPANTS_ON_HOST_EXIT
CANNOT_CHANGE_MEETING_EXTENSION_SETTING
CANNOT_DECREASE_ADDITIONAL_CAPACITY
CANNOT_DECREASE_BANDWIDTH
CANNOT_DECREASE_CAPACITY
CANNOT_REMOVE_EXISTING_ENDPOINT
INVALID_ACTIVE_MEETING
LICENSE_NOT_VALID
LICENSE_SERVER_NOT_ACCESSIBLE
MUTE_FAILED
MUTE_ALL_EXCEPT_FAILED
UNMUTE_FAILED
UNMUTE_ALL_FAILED
DROP_PARTICIPANT_FAILED
REDIAL_PARTICIPANT_FAILED
SEND_ENDPOINT_TEXT_FAILED
LICENSING_EXCEPTION
BRIDGE_TYPE_NOT_VALID
MEETING_NOT_ACTIVE