Updated Oct 28, 2008 by dburkes

RoomChat

Room

room.enter

If authentication has occurred inside the given session, the room is entered on behalf of the authenticated user. Otherwise, the room is entered on behalf of an anonymous user.

HTTP Method:

POST

URL:

http://www.lingr.com/api/room/enter

Parameters:

session `*`	The session id returned from session.create
id `*`	The id of the chatroom to enter
password	The password for the chatroom, if any
nickname	The nickname under which to appear in the roster. If this is not provided, you appear as an anonymous observer.
idempotent	If true, and you have previously entered this room within the same session, the existing occupant and ticket information is returned, and no additional occupant is added to the room. Otherwise, a new ticket is generated, and an additional occupant is added to the room. If not provided, the default is `false`.

(*) Required

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <occupant_id>3h418YGlLtB</occupant_id>
  <ticket>a-r-gcnZ3vAcZDA-1HSTpgDjgWu</ticket>
  <max_observe_time>80</max_observe_time>
  <room>
    <id>gcnZ3vAcZDA</id>
    <name>Bay Area Jazz</name>
    <description>Jazz events in and around San Francisco</description>
    <url>http://www.lingr.com/room/gcnZ3vAcZDA</url>
    <icon_url>http://images.lingr.com/room/gc/nZ/3v/Ac/ZDA/16x16.gif</icon_url>
    <counter>234</counter>
    <max_user_message_id>230</max_user_message_id>
    <tags/>
  </room>
  <occupants>
    <occupant>
      <id>cfQ54YtTggh</id>
      <user_id>duWDM2k3Eho</user_id>
      <nickname>TheDude</nickname>
      <description>I blog at http://blog.thedude.test</description>
      <icon_url>http://images.lingr.com/user/du/WD/M2/k3/Eho/42x42.gif</icon_url>
      <source>browser</source>
      <client_type>human</client_type>
    </occupant>
    <occupant>
      <id>3h418YGlLtB</id>
      <nickname></nickname>
      <description></description>
      <icon_url></icon_url>
      <source>api</source>
      <client_type>automaton</client_type>
    </occupant>
  </occupants>
</response>

A successful response contains the following data items:

occupant_id

Your occupant id for this room. You can use this id to identify your own utterances in responses from subsequent calls to room.observe or room.getMessages

ticket

A room observation ticket to be used in subsequent calls to room.observe or room.getMessages

max_observe_time

The maximum number of seconds which a call to room.observe will wait for changes before returning. You must ensure that the timeout value for any socket you use for room.observe on this ticket is set to this value or higher.

room

Descriptive information for the room. This information has elements described here

occupants

An array describing the current occupants of the room. Each occupant in this array has the elements described here

room.getMessages

Poll a chatroom for new messages. This method is only for the case you can’t use threads in your environment. Other than that, you should always use room.observe instead.

Important: Once you enter a room with room.enter, you must call either this method or room.observe at least once every two minutes, until you exit the room with room.exit. However, do not poll this method more than once per minute per ticket.

HTTP Method:

GET

URL:

http://www.lingr.com/api/room/get_messages

Parameters:

session `*`	The session id returned from session.create
ticket `*`	The room ticket returned from room.enter
counter `*`	The event counter returned from room.enter or the most recent call to room.observe or room.getMessages, if any. If a negative value is passed, the most recent abs(counter) events are returned. For example, a value of minus 5 means “the most recent 5 events”.
user_messages_only	if true, only user messages are returned- system messages are not returned. Otherwise, both user and system messages are returned. If not provided, the default value is false

(*) Required

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <counter>235</counter>
  <messages>
    <message>
      <id>235</id>
      <type>user</type>
      <occupant_id>3tUud4Upiev</occupant_id>
      <nickname>safari</nickname>
      <source>browser</source>
      <client_type>human</client_type>
      <icon_url>http://images.lingr.com/user/00/00/00/00/000/26x26.gif</icon_url>
      <timestamp>2007-01-11T07:17:04-08:00</timestamp>
      <text>hello</text>
    </message>
  </messages>
  <occupants>
    <occupant>
      <id>3tUud4Upiev</id>
      <nickname>safari</nickname>
      <description>I really like Lingr!</description>
      <icon_url>http://images.lingr.com/user/00/00/00/00/000/26x26.gif</icon_url>
      <source>browser</source>
      <client_type>human</client_type>
    </occupant>
    <occupant>
      <id>47WRTE5MYtc</id>
      <nickname></nickname>
      <description></description>
      <icon_url></icon_url>
      <source>api</source>
      <client_type>automaton</client_type>
    </occupant>
  </occupants>
</response>

A successful response contains the following data items:

counter

The event counter for the room, for use in subsequent calls to room.observe or room.getMessages

messages

An array describing new messages in the room, if any have occurred since the counter value you passed. If present, each message in this array has the elements described here

occupants

An array describing the current occupants of the room, if the occupant list has changed since the counter value you passed. For negative values of counter, this element is always present. If present, each occupant in this array has the elements described here

room.observe

Get notified when events occur in a chatroom.

Important: Once you enter a room with room.enter, you must call either this method or room.getMessages at least once every two minutes, until you exit the room with room.exit.

NOTE: whenever you call room.observe, you must not do so in an HTTP session that is kept-alive from a prior call to some other API method. You may call room.observe in an HTTP session that is kept-alive from a prior call to room.observe.

HTTP Method:

GET

URL:

http://www.lingr.com/api/room/observe

Parameters:

session `*`	The session id returned from session.create
ticket `*`	The room ticket returned from room.enter
counter `*`	The event counter returned from room.enter or the most recent call to room.observe or room.getMessages, if any.

(*) Required

Example Response:

A successful response has the same format and details as the response from room.getMessages, if any event occurs. If no event occurs, a successful response has no details, only the

<status>

</status>

element.

Note that the messages element in the response may contain some messages with ids less than the counter you passed. Your client should ignore such messages.

room.setNickname

Set your nickname in a chatroom.

HTTP Method:

POST

URL:

http://www.lingr.com/api/room/set_nickname

Parameters:

session `*`	The session id returned from session.create
ticket `*`	The room ticket returned from room.enter
nickname `*`	The nickname to set

(*) Required

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
</response>

room.say

Speak in a chatroom.

HTTP Method:

POST

URL:

http://www.lingr.com/api/room/say

Parameters:

session `*`	The session id returned from session.create
ticket `*`	The room ticket returned from room.enter
message `*`	The message to speak
occupant_id	If provided, a private message is sent to the indicated room occupant. If omitted, a public message is sent to all room occupants. If provided, and occupant_id represents a logged-in user, the resulting private message is sent to all occupants of the room that represent the same logged-in user.

(*) Required

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  <message>
    <id>236</id>
    <type>user</type>
    <occupant_id>3tUud4Upiev</occupant_id>
    <nickname>safari</nickname>
    <source>api</source>
    <client_type>human</client_type>
    <icon_url>http://images.lingr.com/user/00/00/00/00/000/26x26.gif</icon_url>
    <timestamp>2007-01-11T07:17:04-08:00</timestamp>
    <text>hello</text>
  </message>
  <counter>236</counter>
</response>

A successful response contains the following data items:

message

Descriptive information about the new message. This information has the elements described here

counter

The event counter for the room, for use in subsequent calls to room.observe or room.getMessages

room.exit

Leave a chatroom.

HTTP Method:

POST

URL:

http://www.lingr.com/api/room/exit

Parameters:

session `*`	The session id returned from session.create
ticket `*`	The room ticket returned from room.enter

(*) Required

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
</response>