This section provides an overview of the TSP (teleconferencing service provider) implementation details.
For more information about the TSP calls referenced in this chapter, refer to Telephony API Reference for TSP Implementation.
Performance and Network / System Requirements
- TSP API adapter performance supports at least 30 conferences per minute with a maximum of a 20-second delay per conference.
- After a telephony conference is initiated between the adapter and TSP server, individual attendees do not experience more than a 10 second delay from the teleconference pop-up dialog box when joining a Web meeting.
- Bandwidth requirements and usage between the TSP server and the adapter are specified as follows to enable the performance stated above:
- A 256K connection is considered minimum bandwidth, T1 is recommended.
HTTP Request Target Machine
All XML messages are sent through HTTP requests. The following messaging considerations apply:
- For messages initiated from the WebEx Meetings side, the target machine should be the adapter whose URL for posting XML messages is given in the WebEx Meetings telephony domain.
- For adapter response messages to WebEx Meetings requests, the adapter should use the URL passed with the original request to find the target machine.
- Messages initiated from the adapter side (always associated with a conference) should be sent to the TSP server whose URL (for posting XML messages) is associated with the conference (i.e., passed from WebEx Meetings when sent a W2A_CreateConference request).
Logically Asynchronized Message Exchanges
Communication between the WebEx Meetings server and your adapter occurs through XML
messaging defined as follows:
- One side sends a predefined XML message to the other side to request action or data using the HTTP post method.
- The receiving side checks the message to make sure the request is understood, and returns an OK confirmation.
However, the actual result of the action or data is returned in a separate message sent asynchronously to the requesting side.
Note If the original messages are predefined and known to the receiving side, the receiving side ensures all API parameters are given before an OK confirmation is sent. If an unknown message is found, an OK confirmation is still sent. But, an Unrecognized new XML message received error code -12 is returned separately as the result of that API message.
Thus, we are using asynchronized calls.
Note Each side should always use HTTP post to send a request message.
Here is an example of the call flow for creating a conference:
- WebEx Meetings sends the message W2A_CreateConference to an adapter using the HTTP post method, and waits for a response.
- The adapter receives the message and checks the format of the message against the predefined XML document definitions. If no error is found, it sends error code 0 (OK) in the response immediately. Otherwise, it sends a corresponding error code.
- Meanwhile, the adapter starts to call the Bridge API to create a conference, and waits for the conference creation confirmation from the bridge.
- After an interval of 2 seconds, the adapter receives a confirmation that the conference has been created in the bridge. It sends the message A2W_RspCreateConference to the WebEx Meetings server (the URL should have been part of the conference information stored in the adapter) by HTTP post, then waits for a response.
- WebEx Meetings receives the message, checks the message format, and sends the error code 0 (OK) back in response.
HTTP Transaction and API Messages
When using the HTTP post method, an HTTP transaction begins when the requesting side sends a request. It ends when a confirmation is received from the other end.
To obtain better performance in logical asynchronized calls, WebEx Meetings allows an HTTP request / transaction to send simultaneous, multiple TSP API messages.
Note Therefore, the receiving side should check the formats of individual XML messages. Only when all of them meet requirements, is the error code 0 (OK) sent as a confirmation. Otherwise, a corresponding error code is returned.
The following is an example of an HTTP request (an XML document) that contains more then one TSP API call:
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>121</TransID> <W2A_Callout MsgID="321" WbxHostName="tsp1.webex.com:80" ExtConfID="1234567" ExtCallID="123" Privilege="0" MaxWaitingTime="30"> <PhoneNum> <CountryCode>1</CountryCode> <AreaCode>408</AreaCode> <LocalNumber>4357000</LocalNumber> <Extension>4508</Extension> </PhoneNum> </W2A_Callout> <W2A_CreateConference MsgID="322" WbxHostName="tsp1.webex.com:80" ExtConfID="1234568" ConfKey="987654321" MaxNumAttendee="50"> </W2A_CreateConference> </WbxTSPSchema>
When the adapter receives this document, it discovers two API calls:
The format of both elements is verified, and a Confirmation element is returned to WebEx Meetings if the format is acceptable. The two APIs then begin separately processing, and sending results to WebEx Meetings using other API calls.
Transaction ID, Resending, and API Message ID
Each HTTP transaction / request is given a Transaction ID (or a sequence number) that is always unique, except when the same request is issued more than once under time-out error conditions.
Similarly, each XML message is given a Message ID. The ID is used in each result message so the original requestor knows how to recognize the resulting request.
An important use of the Transaction ID is in message resending. Because WebEx Meetings communications use the Internet (where response times are not guaranteed), after sending an HTTP request, a WebEx Meetings sender may experience a time-out before a confirmation is received. In this case, the sender may retry an additional two times. Under these circumstances, the receiving side may receive the same call more than once.
Important Receivers should always check the Transaction ID of each request to detect duplicate requests. When duplicates are received, no further action should be taken except to return a confirmation. Normally, actions required by duplicate requests (i.e., duplicate IDs) should only be executed once by the receiver.
Transaction IDs are only reused when a previous request receives a time-out. Otherwise, a new ID should be used for each unique transaction request.
If a time-out occurs even after three attempts, rewrite the code to increase flexibility. Even if no TSP servers or adapters can be connected, the telephony conference and Web conference will continue to run assuming the conference was created. In other words, the other commands may time-out, but the conference will continue to run.
Typical TSP Request and Response
TSP Request Messages
The TSP Server sends the Adapter a single transaction, containing three separate messages. The Transaction ID is generated by the TSP Server.
The Adapter's HTTP response indicates that the transaction was received. This response contains the same Transaction ID as the request.
The Adapter's response to each message is sent within a single transaction, containing a newly generated Transaction ID. Each Message ID, from the first transaction, is included here.
The TSP server's “confirmation response” is returned containing the same Transaction ID.
Note Adapters should not send Close Conference commands in response to HTTP disconnects.
Maximum Number of Messages in A Single Transaction
A transaction can contain more than one message. To make handling the transactions easier, both the WebEx Meetings and the adapter limit the maximum number of messages in a single transaction to 50. This means the XML document for a transaction can contain up to 51 elements under the root (50 messages and a TranID element).
Transaction ID And Message ID Generations
Transaction ID and Message ID are defined as an 11 digit, unique number sequence. WebEx Meetings recommends that TSP Adapters set the first five digits as the Julian Date of the day, and the right six digits from a sequence.
Note For details about Julian date, please refer to the relevant information at http://webexhibits.org/calendars/calendar-christian.html or http://www.maa.mhn.de/Scholar/times.html.
- The Julian date of 8/05/2002 is: 2452491.
- If the next value of the Message ID sequence is 123, the next Message ID will be 52491000123.
- Similarly, if the next value of the Transaction ID sequence is 1201, the next Transaction ID will be 52491001201.
- TSP unique ID (2 digits)
- Tick of the day in seconds from 00:00:00 (5 digits)
- Sequence number: 0-9999 (4 digits)
Note The WebEx Meetings TSP server uses a different algorithm to generate the Transaction/Message IDs.
Adapter Backward Compatibility
Existing APIs could be modified or extended in the future to support new features on the TSP server. To provide backward compatibility, adapters should ignore unknown attributes. When an adapter receives a new or unknown message, it should return "unknown msg received" using A2W_RspMessageError.
TSP Server Failover
In the event a TSP server fails, all meetings currently in progress are moved to another TSP server in the same pool.
The WebEx Meetings meeting server regularly sends keep-alive messages to the TSP server to check its status. Should a meeting server receive errors or no response, it will attempt to create a TSP conference on another server.
The TSP Adapter will notice a failover scenario by the ConfKey (WebEx Meetings Meeting Number) that is passed in the W2A_CreateConference command sent by the secondary server; it will need to be able to recognize that the ConfKey passed is associated with a conference already in progress.
The following scenario describes how a typical failover will occur:
- The WebEx Meetings Meeting server notices that TSP Server 1 is not responding, it initiates a connection with TSP Server 2 and requests a new conference to be created, but with the same WebEx Meetings Meeting Number.
- TSP Server 2 sends the Partner Adapter a W2A_CreateConference command containing a new ExtConfID (teleconference unique identifier) and the same ConfKey.
- The adapter notices that the ConfKey sent is associated with a teleconference that is already in progress; using a different ExtConfID.
- The adapter replaces the existing ExtConfID with the new one provided. All subsequent commands relating to this conference / meeting will now use the new ExtConfID.
- The adapter replaces the existing WbxHostName with the new TSP server host name provided.
- The adapter responds with A2W_RspCreateConference, indicating that the conference was created successfully.
- The adapter sends its normal A2W_NotifyConferenceChange to begin the teleconference.
- The adapter sends all call-leg information to the TSP server by sending a transaction containing an A2W_NotifyUserEnter message for each participant.
- The TSP Server responds to each message by sending W2A_RspNotifyUserEnter messages.
Conference Features Affected During Failover
- If any of the call-legs were muted, the adapter will send A2W_NotifyUserChange messages to the TSP server in order to maintain state with the Meeting Manager.
- If the teleconference/meeting was locked prior to failover the adapter will need to make sure to maintain state when switching ExtConfIDs. The meeting manager will maintain its own lock-state separately.
- If additional participants joined during the TSP failover, then after the TSP server takes over the teleconference, the adapter must use A2W_NotifyUserEnter to notify the TSP server of all the new callers
- If participants left the teleconference during a TSP failover, then after the redundant TSP server takes over the teleconference, the adapter must use A2W_NotifyUserChange to notify the TSP server which participants left using the "status" code 2 (User Leave).
- If the teleconference closed during a TSP failover, the adapter must remember which conference closed. If the TSP server attempts
to open a conference with the same ConfKey, the adapter must respond with error code “11” indicating a closed conference.
- If the host has initiated a private talk session, via the Invite by Phone feature, the adapter will need to ensure that it moves
the invitee back into the main teleconference in a failover situation. This will be
done by sending the A2W_NotifyUserEnter message for the invitee.
- In the event that a sub-conference is in progress, the Adapter will need to ensure that it notifies the WebEx Meetings TSP Server of the
sub-conference. This is done by sending the A2W_NotifySubConferenceChange message with a Status code of “2”.
Identify Active Speaker
- 8 is a notice to turn on the active speaker feature.
- 9 is a notice to turn off the active speaker notification feature.
The adapter must send the A2W_NotifySpeakingStatus message to the TSP server for the active speaker. The message must contain the ConfID and CallerID of the currently speaking participant. Because this command may send the speaking status of multiple meeting participants, a TSP server response is not expected for this command.
The following example demonstrates the Identify Active Speaker feature when both caller 1 and caller 2 start talking:
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>121</TransID> <A2W_NotifySpeakingStatus MsgID="321" ExtCallIDs="1%2" SpeakingFlags="Y%Y" ExtConfID=â€xxxâ€> </A2W_NotifySpeakingStatus> </WbxTSPSchema>
When caller 1 stops talking.
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>121</TransID> <A2W_NotifySpeakingStatus> MsgID="321" ExtCallIDs="1" SpeakingFlags="N" ExtConfID=â€xxxâ€> </A2W_NotifySpeakingStatus> </WbxTSPSchema>
This section covers:
- Webex SubConference behaviors
- Webex SubConference CallFlow
These abbreviatonms are used throughout this section:
- Webex Training Center
- Webex Event Center
- Breakout Session, one feature of TC
- Practice Session, one feature of EC
WebEx Meetings Sub-conference Behaviors
- Create SubConference
- TSP sends W2A_CreateSubConference to create a new sub conference on partner’s bridge.
- Add one call into SubConference
- TSP sends W2A_AddToSubConference to move a call from main conference to sub conference.
- Remove one call from SubConference
- TSP sends W2A_RemoveFromSubConference to move a call from sub conference to main conference.
- Close SubConference
- TSP sends W2A_CloseSubConference to close a specified sub conference and all the calls in the sub conference need be moved to main conference.
Create a new sub conference
- WebEx TC and EC support sub conferences. If the host starts a new BO in TC or a PS in EC, TSP sends a W2A_CreateSubConference request to the partner's adaptor.
- Adaptor creates the sub conference and send A2W_RspCreateSubConference to TSP to notify the result.
- Adapter sends A2W_NotifySubConferenceChange with a status of 0.
Add a call into sub conference
- Webex TSP sends W2A_AddToSubConference to add a specified call into a running sub conference.
- Adaptor sends response to TSP.
- Adaptor send A2W_NotifySubConfCallChange with ActionFlag=1 after adding the call successfully.
Remove a call from sub conference
- TSP sends W2A_RemoveFromSubConference to Adaptor to move a specified call from sub conference.
- Adaptor sends A2W_RspRemoveFromSubConference to TSP.
- Adaptor sends A2W_NotifyUserChange to TSP to notify the call privilege in the main conference if moving the call to main conference successfully.
- Adaptor sends A2W_NotifySubConfCallChange with ActionFlag=2 to notify TSP that the call is moved to main conference successfully
Note TSP expects that Adaptor sends the call privilege in main conference to TSP before A2W_NotifySubConfCallChange. Otherwise, it may cause bugs.
Close a sub conference
- TSP sends W2A_CloseSubConference to the adaptor if host closes the sub conference.
- The adaptor needs to move all the calls in the sub conference to main conference.
- If one call is moved to the main conference successfully. The adaptor sends A2W_NotifyUserChange with the call privilege in the main conference to TSP.
- If all the calls are moved and the sub conference is closed, the adaptor needs to send A2W_RspCloseSubConference to TSP to notify the result.
Note TSP expects that adaptor to send the call privilege in the main conference to TSP before A2W_RspCloseSubConference. Otherwise, the process may cause errors.
- If one TSP failover, another TSP sends W2A_CreateConference< with same ConfKey and a different ExtConfID to the adaptor to take over the conference.
- The adaptor needs to send A2W_RspCreateConference and to change the related parameters for this conference to enable the TSP to take over the conference.
- The adaptor needs to send a A2W_NotifyUserEnter message for all the calls in the conference to rejoin them to TSP.
- The adaptor needs to send A2W_NotifyUserChange for all the calls in the conference to let TSP know each call's real privilege.
- The adaptor needs to send A2W_NotifySubConferenceChange with status=2 to notify TSP that there is one sub conference in this conference.
- The adaptor needs to send A2W_NotifyJoinSubConference to notify TSP that the call is in one sub conference.
WebEx Sales Center allows Sales Managers to silently monitor sales sessions without the host or attendees being aware of their presence. With Silent Join, the Sales Manager's name is not displayed, and the audio portion suppresses the join-tone typically heard when joining a teleconference. Sales Managers can monitor both call-out and call-in teleconferencing using this feature.
When a user enters his phone number into a Sales Center Client, he will receive a call back. The TSP server's W2A_Callout message is used to do this. This message contains the ParticipantType attribute containing a value of “6” (silent monitoring attendee). To support Silent Join, the Adapter / Bridge must suppress the join-tone and mute the caller when the ParticipantType attribute of “6” is received.
The following is XML syntax using Silent Join in call-out teleconferencing:
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>121</TransID> <W2A_Callout MsgID="321" WbxHostName="tsp1.webex.com:80" ExtConfID="1234567" ExtCallID="123" Privilege="1" MaxWaitingTime="30" ParticipantType="6" JoinMode="1";> <PhoneNum> <CountryCode>1</CountryCode> <AreaCode>408</AreaCode> <LocalNumber>4357000</LocalNumber> <Extension>4508</Extension> </PhoneNum> <Result>0</Result> </W2A_Callout> </WbxTSPSchema>
Note For Silent Join to work in a call-out teleconference, a Sales Representative and his prospects must be in a WebEx Sales Session. Moreover, the session must use TSP integrated audio and all of the session attendees must be dialed into it.
When a Sales Session is started, the TSP server will send a W2A_CreateConference command, much like it does with any session; however, this command will contain a new attribute called AnonymousID. The Adapter needs to store this ID for later use, in the event that a Silent Monitoring is used.
When the Sales Manager joins his Sales Session he receives dialing instructions. The last line of the instructions prompts him to enter an Attendee ID number. For silent monitoring, the Attendee ID he enters via the phone will need to match the AnonymousID that was passed in the W2A_CreateConference message. The Adapter will now be able to ensure the bridge's join tone is suppressed and to mute call-leg.
The following is XML syntax for Silent Join to a call-in teleconferencing:
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>122</TransID> <A2W_NotifyUserEnter MsgID="322" WbxHostName="tsp1.webex.com:80" ExtConfID="1234567" ExtCallID="null" AttendeeID="444" ActionResult="0" ParticipantType="6"> </A2W_NotifyUserEnter > </WbxTSPSchema>
Note For Silent Monitoring to work with call-in teleconferencing, the bridge has to be able to prompt for an Attendee ID. Example: a voice saying, “Please enter your attendee ID number”. Silent Join for call-in teleconferencing is not supported when using the Call-in User Merge feature, using DTMF codes to pass the attendee ID will occur after the sales manager is already in the conference.
Call-in User Merge
During the final stage of dialing into a WebEx Meetings teleconferencing bridge, users are prompted to enter an attendee ID. The ID is passed from the bridge to the WebEx Meetings client. This places a phone icon next to the user's name and links the call leg to the WebEx Meetings attendee. Most Telco Partners are not willing to prompt their users to enter an Attendee ID, as a third stage of dialing, which results in a duplicate entry in the participant panel, called "Call-in User X". Additionally, no phone icon appears next to the user's name in the participant panel. This renders the Call-in Teleconferencing option virtually useless to Telco Partners.
The Call-in User Merge feature solves this problem. Call-in User Merge allows Telco Partners to pass the attendee ID via DTMF code, rather than prompting the user via the audio. The WebEx Meeting Manager prompts the user to enter the DTMF code, followed by the attendee ID.
Instead of requiring the bridge to say, "Please enter your attendee ID", the WebEx Meetings client's "Join Teleconference" box prompts the user to perform step three.
Call-in User Merge, Network Based Recording Support
NBR in WBS26 has the ability to dial out to the TSP integrated bridge and connect to the teleconference automatically. It does this by using the TSP account information selected when the meeting was scheduled. NBR dials into the teleconference bridge just as a participant would. This creates a scenario where a "Call-in User x" entry is added to the participant list and can cause confusion. Some teleconferencing providers are not concerned by this additional entry, but a method has been designed to allow its removal.
The Call-in User Merge feature is instrumental in removing the "Call-in User x" entry from the participant panel. The NBR dialer enters the DTMF code, followed by the Attendee ID, just as a participant would. This results in the Adapter passing the Attendee ID to the WebEx Meetings TSP server. The TSP server passes the merge instruction to the meeting server, which essentially removes the entry from the participant list and places a telephone icon next to the participant's name.
The Conference Keep-Alive feature introduced in TSP 3.4 allows a teleconference session to be extended beyond the initial duration of a meeting.
- Existing audio integrations require an adapter code change to take advantage of this feature.
- The feature is only supported on Meeting Center.
When an audio integrated meeting ends, the WebEx Meetings TSP Server sends the Partner Adapter the W2A_CloseConference command. In TSP 3.4, this command adds the new attribute, KeepAlive to the API function. The KeepAlive attribute is a boolean function with the following value definitions:
- 0 - Terminate the teleconference.
- 1 - Keep the teleconference alive.
The KeepAlive attribute is not required and will not be present in the XML if the Conference Keep-Alive feature is disabled, or not elected at meeting end-time. Users upgrading to or developing TSP 3.4 may opt-out of this feature, as the KeepAlive attribute is only included in the XML if KeepAlive = 1.
WebEx Meetings Configuration
When a meeting ends, a pop up window appears asking if the user wants to end the meeting for all attendees.
This feature can be enabled or disabled within the Site Admin interface. When the feature is disabled, the adaptor will not receive the KeepAlive attribute included in the W2A_CloseConference message. The default check box status of the pop up is configurable as a sub-item.
Global Number Support
WebEx Meetings partners are able to display an unlimited number of global phone numbers to end-users by hosting a web service/page that displays the numbers. WebEx Meetings embeds the link to those numbers within the client, email invites, and various other pre-meeting locations.
The URL takes the end-user to the phone number page stored within the WebEx Meetings Telephony domain, controlled internally by WebEx Meetings. The provisioning of this URL must be coordinated with the WebEx Meetings Account Manager.
In order to provide customized content to the end-user, the telephony partner likely requires certain arguments to be passed to their web service from WebEx Meetings. The configured URL is dynamically created to pass any piece of the teleconference account information associated with the meeting. This is performed by utilizing variables within the URL string.
- Example of a URL at the time of configuration:
- Example of the URL at scheduling time:
The optional variables that can be used in a URL are shown in the table below.
|%ParticipantCode%||The participant code for the TSP account in use.|
|%SubscriberCode%||The subscriber code for the TSP account in use.|
|%TollFreeNum%||Toll-free number from the TSP account in use.|
|%TollFreeNumCC%||The country code for the toll-free number.|
|%TollNum%||Toll number from the TSP account in use.|
|%TollNumCC%||The country code for the toll number.|
TSP Invite by Phone
The invite by phone flow has these parts:
- Invite attendee via Invite by phone
- Add the invitee into main conference
Invite attendee via Invite by phone
- Host clicks "Call" button in the panel, Webex Meetings TSP server sends W2A_Callout with JoinMode=0 to adaptor.
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>121</TransID> <W2A_Callout MsgID="321" WbxHostName="tspl.webex.com:80" ExtConfID="12345678" ExtCallID="123"
Privilege="0" MaxWaitingTime="60" ParticipantType="2" JoinMode="0"> <PhoneNum> <CountryCode>xxx</CountryCode> <AreaCode>xxx</AreaCode> <LocalNumber>xxx</LocalNumber> <Extension>xxx</Extension> </PhoneNum> </W2A_Callout> </WbxTSPSchema>
- The adaptor calls back the phone number and sends the A2W_RspCallout to the WebEx TSP server after the invitee picks up the phone.
<WbxTSPSchema Name="WTSPDOM Response" Version="1.0"> <TransID>123</TransID> <A2W_RspCallout MsgID="321" Result="0"> </A2W_RspCallout> </WbxTSPSchema>
- The adaptor sends A2W_NotifyUserEnter with ActionCode=2 for the invitee to the WebEx Meeting TSP server after moving the host and invitee into the private talk.
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>123</TransID> <A2W_NotifyUserEnter MsgID="321" ExtConfID="12345678" ExtCallID="123" AttendeeID="1234567"
ParticipantType="2" DID="1234567890" ActionCode="2" ActionResult="0"> </A2W_NotifyUserEnter> </WbxTSPSchema>
- The WebEx Meeting Manager displays the private talk status and activates the "Add to Meeting Call" button in the panel.
Add the invitee into main conference
- Host clicks "Add to Meetign Call" button in the panel.
- WebEx Meeting TSP server sends W2A_UpdateConference with ActionCode=6 to adaptor.
- Partners adaptor sends A2W_NotifyUserChange with ActionCode=3 for the invitee after moving host and participant into the main conference on the bridge.
- Client adds the invitee into the participant list.
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>123</TransID> <W2A_UpdateConference MsgID="321" WbxHostName="tspl.webex.com:80" ExtConfID="12345678"
ActionCode="6" ExtCallID="123"> </W2A_UpdateConference> </WbxTSPSchema>
<WbxTSPSchema Name="WTSPDOM" Version="1.0"> <TransID>123</TransID> <A2W_NotifyUserChange MsgID="321" ExtConfID="12345678" ExtCallID ="123" Status="0"
ParticipantType="2" DID="1234567890" ActionCode="3" ActionResult="0"> </A2W_NotifyUserChange> </WbxTSPSchema>