This API makes it possible for developers to create portlets (also known as plugins for other web sites or dash-boards) that integrate GatherPlace/OmniView capabilities. This allows users to get the benefits of application sharing and "Audio via Computer" from the favorite web site or application.

This API is made available for free and is different from the other GatherPlace APIs as it lets a third party create a generic plugin for a web site (such as MyYahoo!) or application (such as Skype) and let any GatherPlace/OmniView customer use that. This can be done without an OEM agreement and allows a user to use the plugin without ever providing their username or password to a third party.

GatherWorks Proprietary

This document contains information that is proprietary to GatherWorks. You may not use this information for any other reason than described. This document and the API are covered by the GatherPlace Terms of Service and EULA.

Overview

This document assumes an understanding of server-side web development and XML.

Server-side APIs are based on HTTP GET with XML responses on port 80. This makes it firewall friendly and easy to implement from any web server.

All requests start with http://www.gatherplace.net/Control?command= and will get an immediate response.

Here is an example request:
http://www.gatherplace.net/Control?command=myip

with this response:
<gatherworks>
<command>myip</command>
<ip>63.19.9.1</ip>
</gatherworks>

All parameter values must be encoded using standard HTTP GET/POST rules for URL encoding. All responses will be wrapped in a root node named gatherworks. The root node will contain the additional nodes with the responses. The command will always be echoed.

IMPORTANT: All the parameters, URLs and responses are case sensitive.

Error Codes

When an error occurred, the XML response will contain an error node. If no error occurred then the XML response will not contain an error node.

When executing a non-existing command, you will get a response as follows:
<gatherworks>
<command>XXX</command>
<error>com.gatherworks.api.XmlApi.XXX(com.gatherworks.api.RequestWrapper, com.gatherworks.common.xml.XmlResponse, com.gatherworks.authentication.Authenticate)</error>
</gatherworks>

When a required parameter is missing, you will get a response like this:
<gatherworks>
<command>oem.createNewUser</command>
<error>accountid</error>
<errorType>MissingRequiredParameter</errorType>
</gatherworks>

Security

These calls allow you to access data from either your server or from the client side. For security reasons the user must obtain a TOKEN that provides access to his account. This token is requested and does not encode the username or password and can be revoked at any time.

To get your token, open a browser to http://www.gatherplace.net/gp/edit_account.jsp (Account Settings under My Account) and copy the Portlet Token. The user has the option to invalidate the token later.

API Details

These calls allow you to access data from either your server or from the client side. For security reasons the user must obtain a TOKEN that provides access to his account. This token is requested and does not encode the username or password and can be revoked at any time.

portlet.getMySessions

“portlet.getMySessions” allows you to get possible sessions for the user that owns the provided token.
http://www.gatherplace.net/Control?command=portlet.getMySessions&token=TOKEN&rss=RSS
Where:

TOKEN	User assigned token
RSS	Optional: 1=RSS feed instead of XML response

Example use:
http://www.gatherplace.net/Control?command=portlet.getMySessions&token=51101449827610194525
Assumes token value is: 51101449827610194525

An example response record:
<r>
<i>69201</i>
<n>Meeting 2222222</n>
<p>2222222</p>
<pn>0</pn>
<v>0</v>
<l>1</l>
<pr>1</pr>
<pu>1</pu>
<s>1</s>
<o>0</o>
<d>2005-08-12 13:51:14.0</d>
</r>

Where:

i	Is the session ID used to uniquely identify this session.
n	Is the descriptive name for this session.
p	Is the Access Code used to join this session.
pn	1 = Personal Telephone number used to receive incoming calls on. 0 = No personal number listed for the session.
v	1 = Avdanced Teleconferencing IS enabled for the session. 0 = Avdanced Teleconferencing is NOT enabled for the session.
l	1 = Guests WILL see a participant list. 0 = Guests will NOT see a participant list.
pr	1 = Guests ARE allowed to private chat to other guests. 0 = Guests CANNOT private chat to other guests.
pu	1 = Guests ARE allowed to send public chat. 0 = Guests are NOT allowed to send public chat.
s	Optimized for: 0 = Dialup modem speeds. 1 = DSL. 2 = High speed connections.
o	OTP (One Time Password) is required to join this session.
d	Date session was created.

IMPORTANT: Additional fields may be added in future and the order of these fields may change.

portlet.createSession

“portlet.createSession” allows you to create a new possible sessions for the user that owns the provided token.
http://www.gatherplace.net/Control?command=portlet.createSession&token=TOKEN&n=NAME&v=VOICE &l=LISTPARTICIPANTS&pr=GUESTPRIVECHAT&pu=GUESTPUBLICCHAT&s=SPEED

Where:

TOKEN	User assigned token
VOICE	1 = Avdanced Teleconferencing IS enabled for the session. 0 = Avdanced Teleconferencing is NOT enabled for the session.
LISTPARTICIPANTS	1 = Guests WILL see a participant list. 0 = Guests will NOT see a participant list.
GUESTPRIVECHAT	1 = Guests ARE allowed to private chat to other guests. 0 = Guests are NOT allowed to private chat to other guests.
GUESTPUBLICCHAT	1 = Guests ARE allowed to send public chat. 0 = Guests are NOT allowed to send public chat.
SPEED	Optimize for: 0 = Dialup modem speeds. 1 = DSL. 2 = High speed connections.

Response:
p Access Code or PIN that is used to join the session.

portlet.updateSession

“portlet.updateSession” allows you to update an existing session for the user that owns the provided token.
http://www.gatherplace.net/Control?command=portlet.updateSession&p=ACCESSCODE &token=TOKEN&ac=n=NAME&v=VOICE&l=LISTPARTICIPANTS&pr=GUESTPRIVECHAT&pu=GUESTPUBLICCHAT&s=SPEED

Where:

TOKEN	User assigned token.
ACCESSCODE	Access Code (returned as p xml node when session was created).
VOICE	1 = Avdanced Teleconferencing IS enabled for the session. 0 = Avdanced Teleconferencing is NOT enabled for the session.
LISTPARTICIPANTS	1 = Guests WILL see a participant list. 0 = Guests will NOT see a participant list.
GUESTPRIVECHAT	1 = Guests ARE allowed to private chat to other guests. 0 = Guests are NOT allowed to private chat to other guests.
GUESTPUBLICCHAT	1 = Guests ARE allowed to send public chat. 0 = Guests are NOT allowed to send public chat.
SPEED	Optimize for: 0 = Dialup modem speeds. 1 = DSL. 2 = High speed connections.

portlet.deleteSession

“portlet.deleteSession” allows you to delete an existing session for the user that owns the provided token.
http://www.gatherplace.net/Control?command=portlet.deleteSession&p=ACCESSCODE

Where:

TOKEN	User assigned token.
ACCESSCODE	Access Code (returned as p xml node when session was created).

portlet.getStatus

“portlet.getStatus” allows you detect whether someone is logged in with GP4* or not, but not whether they are in a call.
http://www.gatherplace.net/Control?command=portlet.getStatus&token=TOKEN&email=EMAIL
Where:

TOKEN	User assigned token.
EMAIL	Optional: Email address of person who’s status you are requesting. Will provide your own status if no email address is provided.

*Note: This only works if the user of the providede token is logged in using a GP4 client.
It will return 'offline' if they are logged in and using GP3 or Java to host a session.

Launching Into a Call

GP4 allows client-side access by opening this link in your favorite browser:

omniview:ARG

Where:

ARG Value Result

open Open the GP4 application or bring it to the front if already running.

1234567 Calls session number 1234567 and joins the meeting/session.

Examples:

omniview:open Opens the GP4 application or brings it to the front if it is already running.

omniview:1234567 Will call Access Code 1234567 and join the session.

Please see Integration Details Page for more ways that guests can join a session.