Chat

This module provides a very simple chatting mechanism for players to communicate in the game. The message text is limited to predefined length (TODO: Add actual value of the length).

There are 3 levels at which the players can communicate:

  • P2P

    • peer-to-peer direct chat

  • Session

    • all players within a particular session can communicate with each other.

  • Broadcast

    • All players within the game universe can communicate with each other.

Using P2P chat, the players can collaborate amongst themselves within a session - the messages are directed towards a specific user that the player can select. These messages are not visible to any other player.

Session-level chat can be useful to discuss anything within the context of the session; whereas, a broadcast message reaches everybody who is part of the game universe.

Attention

Both session level and broadcast chats are implemented as fixed-length queues having capacity of 1000 messages respectively. That means that at any given time, these queues will hold only the latest 1000 messages and as new messages are posted, the older ones are removed from the queue.

API: Retrieve all chat messages for given user

Retrieve all chat messages for given user API

URL: {BASE_URL}/app/<APP_ID>/chat/user/<MODE>/<USER_ID>

Request Method: HTTP GET

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes String The user ID retrieving the chat messages.
since No Numeric The UNIX timestamp when the last update was fetched - if passed. More details on how this works are outlined below.
limit No Numeric No. of results to return in the output
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok along with the actual lists of messages.

Instead, if the requesting user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE

The output contains 3 segments:

  • p2p
  • sess
  • broadcast

corresponding to the three message levels outlined in the introduction above. Each segment contains two attributes: “count” and “msgs” - where count is the no. of entries in the “msgs” dictionary.

The actual message entry has following fields:

  • timestamp - the UNIX timestamp when the message was sent

  • msg - the actual message text (FIXME: Unicode support?)

  • sender - the sender of the message containing following fields
    • mode - the mode from which the user was logged in (same interpretation as MODE)
    • id - the user ID (same interpretation as USER_ID in the API calls)
    • first_name - the first name of the sender
    • last_name - the last name of the sender
    • picture_url - the picture/thumbnail/avatar URL of the sender

In case of p2p and broadcast segments in the output, the “msgs” list contains the actual messages where each message entry is as outlined above.

However, the sess segment contains a list of session ids which are still active and in which the user/caller is a participant.

Each entry in the sess segment has following fields:

  • sessid - the session id
  • count - the no. of messages in the session chat room (possibly, 0)
  • msgs - the actual list of message - each entry having the same format as outlined before.

Note

The raw/uncompressed output of this API call can be really huge. Therefore, this API supports output compression using the GZip algorithm for clients that can handle compressed output. It is triggered by using the Accept-Encoding: gzip HTTP header in the request.

The server also indicates the output encoding in the Content-Encoding HTTP response header - so, clients should use that to verify if the output is indeed in compressed form.

The large size of the output affects the clients as well - especially, on the network I/O side; so, whenever possible, use the compressed output.

Attention

To make sure you receive only updated messages, please keep track of the last timestamp from the combined message list (i.e. from all 3 segments).

This timestamp is what you need to pass in the since parameter in the API call.

Do not pass timestamp from your local/device time as it may be out of sync with the server.

Example

1. Successful request (output uncompressed for readability):

URL Call:

curl "http://api.playblazer.com/v1/app/1/chat/user/fb/kunalg?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
    "status": "ok",
    "broadcast": {
        "count": 1,
        "msgs": [
            {
                "msg": "This is a broadcast message",
                "timestamp": 1391160777,
                "sender": {
                    "last_name": "User 1",
                    "first_name": "Test",
                    "picture_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn2/273291_581655860_598512541_q.jpg",
                    "mode": "fbid",
                    "id": "abcd"
                }
            }
        ]
    },
    "sess": {
        "count": 2,
        "msgs": [
            {
                "count": 1,
                "sessid": "28d364f42cd743978ffdbd6a5e107840",
                "msgs": [
                    {
                        "msg": "This is a session message",
                        "timestamp": 1391154125,
                        "sender": {
                            "last_name": "User 1",
                            "first_name": "Test",
                            "picture_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn2/273291_581655860_598512541_q.jpg",
                            "mode": "fbid",
                            "id": "abcd"
                        }
                    }
                ]
            },
            {
                "count": 1,
                "sessid": "01d411d8c6b943e5b27482cc307c0162",
                "msgs": [
                    {
                        "msg": "This is another session message",
                        "timestamp": 1391161215,
                        "sender": {
                            "last_name": "User 2",
                            "first_name": "Test",
                            "picture_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn2/273291_581655860_599916541_q.jpg",
                            "mode": "fbid",
                            "id": "pqrs"
                        }
                    }
                ]
            }
        ]
    },
    "p2p": {
        "count": 1,
        "msgs": [
            {
                "msg": "This is a test message",
                "timestamp": 1391161190,
                "sender": {
                    "last_name": "User 1",
                    "first_name": "Test",
                    "picture_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn2/273291_581655860_598512541_q.jpg",
                    "mode": "fbid",
                    "id": "abcd"
                }
            }
        ]
    }
}

2. Receiver profile not found:

URL Call:

curl "http://api.playblazer.com/v1/app/1/chat/user/fb/nonexistent?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
    "status": "error",
    "error": {
        "message": "User profile with 'fbid' = 'nonexistent' not found",
        "code": -10003,
        "code_str": "E_NO_PROFILE"
    }
}

API: Post peer-to-peer chat message to given user

Post peer-to-peer chat message to given user API

URL: {BASE_URL}/app/<APP_ID>/chat/user/<MODE>/<USER_ID>/post

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID of the receiving user
sender:mode Yes String The mode for user ID interpretation of sender
sender:id Yes Alpha-numeric The user ID of the sending user
msg Yes String The actual message text. Should be URL-encoded. (TODO: Unicode support?)
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok.

Instead, if the sending or receiving user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=abcd"  \
    -F "msg=This%20is%20a%20test%20message"
    "http://api.playblazer.com/v1/app/1/chat/user/fb/kunalg/post"

Output:

{
    "status": "ok"
}

2. Receiver profile not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=abcd"  \
    -F "msg=This%20is%20a%20test%20message"
    "http://api.playblazer.com/v1/app/1/chat/user/fb/nonexistent/post"

Output:

{
    "status": "error",
    "error": {
        "message": "User profile with 'fbid' = 'nonexistent' not found",
        "code": -10003,
        "code_str": "E_NO_PROFILE"
    }
}

3. Sender profile not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=invalid_sender_id"  \
    -F "msg=This%20is%20a%20test%20message"
    "http://api.playblazer.com/v1/app/1/chat/user/fb/kunalg/post"

Output:

{
    "status": "error",
    "error": {
        "message": "User profile with 'fbid' = 'invalid_sender_id' not found",
        "code": -10003,
        "code_str": "E_NO_PROFILE"
    }
}

API: Post session chat message to given session

Post session chat message to given session API

URL: {BASE_URL}/app/<APP_ID>/chat/session/<SESSION_ID>/post

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
SESSION_ID Yes Alpha-numeric The session ID of the target session
sender:mode Yes String The mode for user ID interpretation of sender
sender:id Yes Alpha-numeric The user ID of the sending user
msg Yes String The actual message text. Should be URL-encoded. (TODO: Unicode support?)
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok.

Instead, if the sending user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=abcd"  \
    -F "msg=This%20is%20a%20session%20message"
    "http://api.playblazer.com/v1/app/1/chat/session/28d364f42cd743978ffdbd6a5e107840/post"

Output:

{
    "status": "ok"
}

2. Sender profile not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=invalid_sender_id"  \
    -F "msg=This%20is%20a%20session%20message"
    "http://api.playblazer.com/v1/app/1/chat/session/28d364f42cd743978ffdbd6a5e107840/post"

Output:

{
    "status": "error",
    "error": {
        "message": "User profile with 'fbid' = 'invalid_sender_id' not found",
        "code": -10003,
        "code_str": "E_NO_PROFILE"
    }
}

API: Post broadcast chat message

Post broadcast chat message API

URL: {BASE_URL}/app/<APP_ID>/chat/broadcast/post

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
sender:mode Yes String The mode for user ID interpretation of sender
sender:id Yes Alpha-numeric The user ID of the sending user
msg Yes String The actual message text. Should be URL-encoded. (TODO: Unicode support?)
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok.

Instead, if the sending user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=abcd"  \
    -F "msg=This%20is%20a%20broadcast%20message"
    "http://api.playblazer.com/v1/app/1/chat/broadcast/post"

Output:

{
    "status": "ok"
}

2. Sender profile not found:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "sender:mode=fb"  \
    -F "sender:id=invalid_sender_id"  \
    -F "msg=This%20is%20a%20broadcast%20message"
    "http://api.playblazer.com/v1/app/1/chat/broadcast/post"

Output:

{
    "status": "error",
    "error": {
        "message": "User profile with 'fbid' = 'invalid_sender_id' not found",
        "code": -10003,
        "code_str": "E_NO_PROFILE"
    }
}