6. Web Services Guest API
This chapter describes the Web Services Guest API.
VidyoPortal Guest Service URL:
http://VIDYOPORTAL/services/VidyoPortalGuestService?wsdl
LogInAsGuest
Login request to the VidyoPortal for guest users. Guest is identified in the guestName parameter. Http authentication header is not needed for this request.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestName | String | Name of the guest | Yes |
| roomKey | String |
Unique Room identifier.
or
The room Url has the roomkey. You should parse this key. Room URL example: http://dev20.vidyo.com/flex.html?roomdirect.html&key=t9EPujHlpYAR |
Yes |
| returnEndpoint Behavior | Boolean | Flag to return the endpoint behavior if configured | No |
Response parameter(s)
| Name | Type | Description | Required |
| guestID | String | Guest Id | Yes |
| isLocked | Boolean | true or false | No |
| hasPin | Boolean | true or false | No |
| vmaddress | String | VidyoManager address | No |
| proxyaddress | String | VidyoProxy address | No |
| loctag | String | Location Tag (to be used for cascading scenarios) | No |
| un | String | Temporary guest username | Yes |
| pak | String | The Portal Access Key | Yes |
| portal | String | Portal address | No |
| portalVersion | String | Portal Version | No |
Fault(s)
| Name | Description |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| GeneralFault |
An unspecified error occurred |
| ResourceNotAvailableFault |
Resources are not available for the requested operation |
| RoomIsFullFault |
Room is full |
LinkEndpointToGuest
Retrieves the VidyoPortal guest entity from the VidyoPortal. Http authentication header is not needed for this request.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestID | EntityID | This is an ID for addressing the room object in the VidyoPortal where the conference is started | Yes |
| EID | String | Endpoint ID – User associated with the Vidyo endpoint identifier | Yes |
| vrIP | String | VidyoRouter IP address | No |
| clientType | String |
Represent client type:
|
No |
Response parameter(s)
| Name | Type | Description | Required |
| Entity | EntityID | If the user’s authentication is successful, the Member entity is returned | Yes |
Fault(s)
| Name | Description |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| GeneralFault |
An unspecified error occurred |
| AccessRestrictedFault |
Resources are not available for the requested operation |
createTestcallRoom
Creates a test call room, which gets forwarded to the WebRTC test call server.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| CreateTestcallRoom Request | Create Testcall Room Request | Creates a test call room | Yes |
Response parameter(s)
| Name | Type | Description | Required |
| extension | String | Extension number of the room | Yes |
| roomURL | URI | URL to access the room | Yes |
| roomKey | String | Unique room access key | Yes |
Fault(s)
| Name | Description |
| GeneralFault | An unspecified error occurred |
| TestcallRoomCreationFault | An unspecified error occurred while creating the test call room |
GuestJoinConference
A VidyoPortal member’s request to join a meeting room. Request by a guest to join a meeting room identified by hash string.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestID | EntityID | This is an ID for addressing the room object in the VidyoPortal where the conference is started | Yes |
| pin | String | PIN is an optional string in case the room has a PIN | No |
Response parameter(s)
| Name | Type | Description | Required |
| OK | String | String representation of successful operation | Yes |
Fault(s)
| Name | Description |
| GeneralFault | An unspecified error occurred |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| ResourceNotAvailableFault | Resources are not available for the requested operation |
| WrongPinFault | PIN provided to joinConference is wrong |
| ConferenceLockedFault | Conference provided by EntityID is unable to be joining, due to the fact that it is locked |
| RoomIsFullFault | Resources are not available - Room is full |
| AllLinesInUseFault | Resources are not available - All Lines in use |
joinIPCConference
A VidyoPortal member’s request to join a meeting room on a different portal using IPC (Inter-Portal Communication).
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| local-part | String | This is an address of room (username for private room, room name for public room or extension) | Yes |
| domain | String | FQDN or IP address of remote VidyoPortal | Yes |
| pin | String | (optional) required if remote room is pinned | No |
Response parameter(s)
| Name | Type | Description | Required |
| OK | String | String representation of successful operation | Yes |
Fault(s)
| Name | Description |
| GeneralFault | An unspecified error occurred |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| NotLicensedFault | API is not licensed |
| WrongPinFault | PIN provided to joinConference is wrong |
| ConferenceLockedFault | Conference provided by EntityID is unable to be joining, due to the fact that it is locked |
| SeatLicenseExpiredFault | Seat license has expired and needs to be renewed |
getClientVersion
Returns the version of the active client endpoint uploaded for a Tenant, which may be a CDN URL or VidyoPortal URL. There can be multiple versions uploaded but only one version can be active for a given client type. If there is no active client, the response parameters come back empty.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| ClientType | String |
Specifies the type of client being requested:
|
Yes |
Response parameter(s)
| Name | Type | Description | Required |
| CurrentTag | String | Specifies the tag of the endpoint version | Yes |
| InstallerURL | String | Specifies the CDN or VidyoPortal URL where the endpoint can be downloaded from | Yes |
Fault(s)
| Name | Description |
| InvalidArgumentFault | Invalid Argument Fault or in case that the conferenceID or entityID doesn't exist |
| GeneralFault | An unspecified error occurred |
setEndpointDetails
Enables endpoints to report their capabilities to the VidyoPortal during the authentication process. The endpoints must report their capabilities in order to be given permission for some of the system level features such as Presenter Mode. Vidyo endpoints gain new capabilities as features are added to newer versions.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestID | Integer | Guest ID | Yes |
| EID | String | The endpoint ID | Yes |
| EndpointFeature | EndpointFeature | The list of features supported by the endpoint and whether those are enabled or not | Optional |
| applicationName | String | The Vidyo application name (for example, VidyoDesktop, VidyoMobile, etc.) | Optional |
| applicationVersion | String | The application version (for example, VidyoDesktop, VidyoMobile, etc.) | Optional |
| applicationOs | String | The OS on which the Vidyo application is running (for example, Windows) | Optional |
| deviceModel | String | The device model on which the application is running (for example, iPhone 5S) | Optional |
Response parameter(s)
| Name | Type | Description | Required |
| OK | String | String representation of successful operation | Yes |
Fault(s)
| Name | Description |
| EndpointNotBoundFault | Endpoint Not Bound Fault |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| GeneralFault | An unspecified error occurred |
WhatIsMyIPAddress
Requests the VidyoPortal to send the endpoint public IP address. This information is also reflected in the CDR table.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| (Always Empty) | N/A | Use only the HTTP Authentication header | N/A |
Response parameter(s)
| Name | Type | Description | Required |
| endpointExternalIPAddress | String | Returns the EP's external IP address or Unknown if the IP address in unknown | N/A |
Fault(s)
| Name | Description |
| GeneralFault | An unspecified error occurred |
RaiseHand
Signals the VidyoPortal about a raise hand request made during Presenter mode (a.k.a., Lecture mode) from a participant.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestID | Integer | Guest ID | Yes |
| Username | String | Username | Yes |
Response parameter(s)
| Name | Type | Description | Required |
| OK | String | Acknowledges that the request has been received successfully | Yes |
Fault(s)
| Name | Description |
| GeneralFault | An unspecified error occurred |
UnraiseHand
Signals the VidyoPortal about an unraise hand request made during Presenter mode (a.k.a., Lecture mode) from a participant who had previously raised their hand.
This method can use the following parameters:
Request parameter(s)
| Name | Type | Description | Required |
| guestID | Integer | Guest ID | Yes |
| Username | String | Username | Yes |
Response parameter(s)
| Name | Type | Description | Required |
| OK | String | Acknowledges that the request has been received successfully | Yes |
Fault(s)
| Name | Description |
| InvalidArgumentFault | The arguments that were passed into services were wrong |
| GeneralFault | An unspecified error occurred |
