|
|
RoomChat
Room
Chat
room.enter
Enter a chatroom.
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
- 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/gcnZ3vAcZDA/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/duWDM2k3Eho/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
- 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/0/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/0/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
- 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>ok</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
- 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
- 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/0/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
- 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>