Askabt creates chat rooms where users can connect from the Askabt widget (embedded on your site or app), as well as from their Gmail chat, when they're not using your site or app. This document describes how you can build applications that use Askabt to create chat communities within your app.
Suppose you're building a massively multiplayer game in which players team up and coordinate their attacks. It is useful to have an in-game chat to allow teams to strategize. You can use Askabt for this.
Askabt goes one step further. Suppose your players have decided to do a massive raid at 16:00 but at the 15:55 they find that the only player with healing powers hasn't yet joined the game - maybe she forgot the time. If your game uses Askabt, other players can reach her outside the game and gently remind her of her obligations to the alliance. Of course, they only see her character name, not her actual Gtalk ID.
This is just an example of how you can use Askabt. I'm sure you can think of more creative ones.
Askabt is under heavy development, and these APIs are subject to change which will break your apps. If you're using our APIs in an app that goes anywhere near a public release, please email aravind@askabt.com.
Your development platform must support:
- Making HTTP GET/POST requests
- Parsing JSON
- Embedding web pages ([UI]WebView, <iframe>)
Askabt has users, topics, discussions and messages. Everyone knows what a user is (hopefully).
A 'topic' is Askabt's term for a named community or group. Users 'subscribe' and 'unsubscribe' from topics. (The relationship is called a subscription.) Topics have friendly string ID's and can be accessed through the URL
http://askabt.com/<topic_id>
If the topic does not exist, it will be created automatically when you request this URL.
Users can also start 'discussions' in topics. When a discussion is started, the opening message goes to all the subscribers of that topic.
Discussions are exactly what they sound like. Users 'join' and 'leave' discussions (the relationship between user and discussion is called a 'participation'). Users also send 'Messages' to each discussion, and they get forwarded to all the participants of that discussion. (See a pattern here?)
Because Askabt is still under development, this document only covers the APIs for reading information. For creating topics, open the topic's URL in an iframe or embedded Future versions of the API will allow you to create discussions, users and post messages through the REST API.
In the detailed schema of each class below, the first column shows the name of the property and the second columns shows the data type. Some properties contain objects of other classes - this will be returned to you as a nested JSON object.
A type name enclosed in [brackets] indicates that it will be an array - for example, [String] indicates that the property contains an array of Strings.
The list of properties below each object will be broken into two - mandatory properties (which you will always get), and optional properties (which you must request explicitly, otherwise they are omitted).
The APIs lets you to access these information from askabt and use it on your apps. The key objects in the system are as follows. Objects:
id String
name String
subscriberCount: Integer
availableCount: Integer
subscribers: [Subscription]
discussions: [Discussion]
{
"id": "sandbox",
"name": "Askabt Sandbox",
"subscriberCount": 35,
"availableCount": 21,
"subscribers": [{ ... }, { ... }, ... ], // Subscription objects, see below
"discussions": [{ ... }, { ... }, ... ], // Discussion objects, see below
}
id Integer
topicId String
startedBy String
startedAt Timestamp
title String
starter User
participants [Participation],
participantCount Integer
messages [Message],
messageCount Integer
{
"id": 89765,
"topicId": "sandbox",
"startedBy": "alice",
"startedAt: "2013-03-12T12:54:33.000Z"
"title": "Let's discuss something different",
"starter": {
"id": "alice",
"name": "Alice",
"picture": "http://askabt.com/img/userf128.png"
},
"participants": [{ ... }, { ... }, ... ], // Participation objects, see below
"participantCount": 8,
"messages": [{ ... }, { ... }, ... ], // Message objects, see below
"messageCount": 25
}
id String
name String
picture String
{
id: "eve",
name: "Eve",
picture: "https://graph.facebook.com/facebookid/picture?width=128&height=128"
}
id Integer
topicId String
userId String
status String
statusTime Timestamp
type String
user User
{
id: 126,
topicId: "sandbox",
userId: "bob",
status: "subscribed",
statusTime: "2013-05-09T10:34:52.000Z",
user: {
id: "bob",
name: "Bob",
picture: "https://graph.facebook.com/facebookid/picture?width=128&height=128"
}
}
id Integer
discussionId Integer
userId String
joinedAt Timestamp
partedAt Timestamp
user User
{
id: 1,
discussionId: 1,
userId: "charlie",
joinedAt: "2013-05-14T17:18:12.000Z",
partedAt: null,
user: {
id: "charlie",
name: "Charlie",
picture: "https://graph.facebook.com/facebookid/picture?width=128&height=128"
}
}
id Integer
participationId Integer
discussionId Integer
userId String
topicId String
text Text
time Timestamp
user User
{
id: 6,
discussionId: 3,
userId: "david",
time: "2013-05-14T06:09:53.000Z",
text: "Askabt is so easy to use. :-)",
deletedOn: null,
user: {
id: "david",
name: "David",
picture: "https://graph.facebook.com/example/picture?width=128&height=128"
}
}
You can do GET requests to
http://askabt.com/api1/<resource>[/<id>[/<relation>]][?parameters]
to read data from Askabt. resource can be topics or discussions.
An optional parameter supported by some of the queries, fields can be used to retrieve optional fields of the requested object. For example:
GET /topics/sandbox?fields=subscriberCount,availableCount,subscribers
can be used to include the subscriberCount, availableCount and subscribers in the returned topic object.
GET topics/\<id\>- Retrieve a single topic. Supports the fields parameter.GET topics/search?term=\<keyword\>- Returns an array of topics.GET topics/\<id\>/subscribers- Retrieves an array of current subscribers of this topic.GET topics/\<id\>/discussions- Retrieves an array of discussions in this topic.
GET /discussions/\<id\>- Retriewve a single discussion. Supports the fields parameter.GET /discussions/\<id\>/participants- Retrieves an array of current participants of this discussion.GET /discussions/\<id\>/messages- Retrieves an array of messages in this discussion.
As mentioned earlier, actions that involve updating data on the server are currently possible only through the Askabt user interface. You can create a topic by creating a UIWebView, WebView or Iframe in your app which opens this URL:
http://www.askabt.com/<topic_id>
This will create a new topic for you (if the ID doesn't already exist), and your user will get an interface where he or she can register/log in, create discussions and send or receive messages.
We use Askabt to provide support for developers using the API (duh). Come on over to askabt.com/askabtapi and ask your question, one of us will respond. If you need to go away before you get a reply, make sure you've subscribed to the Askabt API topic and are watching the discussion you started.