API Advanced Tutorial

1. Real-time notification with room.observe

Now we might want to start getting notified when events occur in the room. An event can be someone speaking, or someone entering or leaving the chatroom, etc.

We observe for events in the chatroom by calling the room.observe method, like so:

This call blocks until some event occurs in the chatroom, or until the maximum observation wait time passes.

Because this call blocks, we probably want to spin off a separate thread to do our observation, but the details are up to you.

Also, because the call might block as long as the maximum observation wait time, it’s important to set your socket timeouts accordingly, so that your client doesn’t close the socket prematurely.

The return value contains several data items that we need to store:

• a room ticket
• an event counter
• my occupant id
• the maximum observation wait time, in seconds

Note that, when we speak, the room observation thread that we started here gets notified, because our speaking constituted an event in the room.

Right after the HTTP connection is responded and closed, we reissue the room.observe method again.

Basically the observing loop described here is the key implementation of Lingr API.

And it might be of help to know that at the time of the room.observe method is called, your connection status is confirmed as alive at the backend. If you don’t call either room.observe or room.getMessages more than 2 minutes, your ticket will get expired and your presence in the room will be swept out from the chatters list. That’s the reason why the maximum observation wait time is set to less than 120 seconds.

2. Sample chat client for Ruby

You need to download 2 script files from here to go through this tutorial.

• api_client.rb
• sample_chat_client.rb

Put those files in the same directory. For later reference, let’s say the directory is home.

$ cd [home]
$ ls
sample_chat_client.rb   api_client.rb

From the terminal, you type commands as follows:

$ ruby sample_chat_client.rb 0123456789abcdef0123456789abcdef

Please make sure that the value 0123456789abcdef0123456789abcdef must be your own API key.

If you have received a response and the prompt “>” as follows, the request succeeded.

$ ruby sample_chat_client.rb 0123456789abcdef0123456789abcdef
enter <room_id> [nickname]
set_nickname <nickname>
say <message>
get_messages
exit
get_room_info <room_id> [<counter>]
verbose
quiet
quit
>

Now, let’s enter our favorite chatroom.

From here on, to see how it goes, you might want to open the room URL with a browser.

This room’s URL when accessed from a browser would be like http://www.lingr.com/room/MyFavoriteRoom, so we just extract the room id and use it here.

> enter MyFavoriteRoom
Starting observe loop for room MyFavoriteRoom

Room Occupants
==============
2 anonymous observer
>

Keep in mind that one of the anonymous observers is this api client, and the other one is the browser.

Then, let’s set your nickname and start conversation.

> set_nickname api-dude
SYSTEM: api-dude has joined the conversation

Room Occupants
==============
api-dude
And 1 anonymous observer
>

Then, let’s say “hello world!”

> say hello world!

Then, let’s enter the room with the browser. You will be immediately notified on the enter event as follows.

SYSTEM: browser-guy has joined the conversation

Room Occupants
==============
browser-guy
api-dude
>

Say something from the browser. Say “hi there”, and again, you’ll be immediately notified with the message.

browser-guy says: hi there
>

Okay, now you understand how the API interacts with the Lingr site.

To leave the chat, you type commands as follows:

> exit
>

And then, type as follows to quit this program.

> quit
$