REST API Documentation


Introduction

Welcome to the Chatterous API. This is the API you will use to interact with your group in a programmatic fashion. This API is in BETA right now, which means that there are many features and functions that have not yet been exposed. Please let us know if you have any use cases that these API's do not address, and we will try to get them into our next release. Now, onto the goodness!

Concepts

Authentication

All the Chatterous API calls require authentication. A call is authenticated by passing in your username (username), group short name (group_short_name) and your api key (api_key) as either query string parameters (for a GET) or parameters in a POST body.

REST Interface

You can interact with the Chatterous API's through a REST interface, using either a GET or a POST. The URL for the rest interface is as follows:

http://api.chatterous.com/<method name>/?username=<your username>&group_short_name=<the group short name>&api_key=<your api key>&<other params>

The body of the response to your REST request will be a JSON structure, and the return code will indicate success or failure. A list of methods along with return codes are listed below.

Return Codes

The Chatterous API attempts to return appropriate HTTP status codes for every request. Here are a list of various status codes along with their meaning:

  • 200 OK: Request succeeded
  • 400 Bad Request: Your request was invalid and we'll return an error message telling you why.
  • 401 Not Authorized: You did not provide the right credentials.
  • 503 Service Unavailable: You cannot make this request at this time. We will return a message telling you why (you may have hit a rate limit)

Error Messages

When the Chatterous API returns an error, it will return you an exception element.

Rate Limiting

Clients are allowed to make up to 60 requests per minute (about 1 request per second). If you pass this limit you will get responses with status code 503.

External Integration

If you already have a user base and would like to integrate it into a Chatterous group, you can do so by using the external contact type and external message sending API's. This will allow you to add your own users to groups as well as send messages to the group on behalf of your users.

Add users using the add_members API and send users on behalf of your users by using the send_message_external API.

Callbacks

You can define a callback for each group that you have an API key for. The callback you specify must be a valid HTTP URL. This URL will get called (HTTP POST) every certain actions are taken.

The actions that can trigger callbacks are:
  • message: A message is posted to a group (You will not receive callbacks for messages sent to the group using your username and api key.)

Callbacks are posted with parameters that vary depending on the action that triggered the callback. Every callback will have a type parameter that defines the triggering action.

message

This callback is triggered when a message is posted to a group. It is called with the type 'message'.
  • type: message
  • user_id: id of the user who sent the message
  • message: the message the user sent
  • username: the username of the user who sent the message
  • user_display_name: the display name of the user who sent the message
  • timestamp: the time the message was sent in epoch

Request Methods and Parameters

The following is a listing of all methods that the Chatterous REST API currently supports. If you require richer API's, please contact us via the feedback form with what you would like to see along with your use case and your contact information.

NOTE: All API's require authentication parameters (username, group_short_name and api_key).


send_message

Sends a message to the group.

URL: http://api.chatterous.com/send_message/
Parameters:
  • message. Required. The message you are sending.
Returns: True


send_message_external

Sends a message to the group on behalf of an external user.

URL: http://api.chatterous.com/send_message_external/
Parameters:
  • message. Required. The message you are sending.
  • external_user. Required. The user identifier of the external user (<identifier>@<yourdomain>).
Returns: True


delete_message

Delete a message from a group

URL: http://api.chatterous.com/delete_message/
Parameters:
  • message_id. Required. The message you want to delete.
Returns: True


get_members

Get members of a group. Note that this API call is cached and the member list may not be completely up to date. If you receive a message via a callback from a user that is not in the member list, you should use the display data given by the callback.

URL: http://api.chatterous.com/get_members/
Parameters: None
Returns: JSON list of user elements.


add_member

Add member to a group

URL: http://api.chatterous.com/add_member/
Parameters:
  • channel_id. Required. The type of user you are adding. 1 = Chatterous Username, 2 = Email Address, 3 = Jabber/GTalk, 5 = SMS, 11 = External (your own identifier, given as <identifier>@<yourdomain>
  • details. Required. The details of the member you are adding. For example, a username, email address, jabber/gtalk id or phone number.
Returns: A user element of the user added.


remove_member

Remove member from a group

URL: http://api.chatterous.com/remove_member/
Parameters:
  • user_id. Required. The id of the user you are removing.
Returns: True


get_group_info

Get group info

URL: http://api.chatterous.com/get_group_info/
Parameters: None
Returns: A group element.


update_group_info

Get group info

URL: http://api.chatterous.com/update_group_info/
Parameters:
  • name. Required. The new name of the group.
  • description. Required. The new description of the group.
Returns: A group element.


get_recent_messages

Get recent messages for a group

URL: http://api.chatterous.com/get_recent_messages/
Parameters:
  • limit. Optional. Limit the number of messages returned. Default is 100, max is 100.
Returns: A JSON list of message elements.

Return Elements

All API calls return well-formed elements of data. The element or list of elements are comprised of return values.

user element

A user element is a JSON hash containing:
{"user_id":"<user id>", "username":"<username>", "user_display_name":"<user display name>"}

group element

A group element is a JSON hash containing:
{"group_short_name":"<group short name>", "name":"<group name>", "description":"<group description>", "owner":"<user element of owner>", "public":"<True/False>", "passcode":"<group passcode>"}

Note that passcode will only be populated if the group is private and you have invite permissions.

message element

A message element is a JSON hash containing:
{"message_id":"<The message identifier (used for delete)>", "user":"<user element of user that sent the message>", "message":"<message contents>", "timestamp":"<time message was sent in epoch>"}

exception element

An exception element is a JSON hash containing:
{"exception": "<explanation>"}

Return Values

The following is a list of known input and output parameters and their description.

user_id

A user identifier used to reference a chatterous user

username

The username for a chatterous user (can possibly be empty if the user does not have a username)

user_display_name

The display name for a chatterous user.

group_short_name

The short name for a group

group_name

The full name for a group

group_description

The description for a group

api_key

An api key for a user.

channel_id

The available channels that a user can be added on (Web = 1, Email = 2, Jabber/GTalk = 3, SMS = 5, 11 = External (your own identifier, given as <identifier>@<yourdomain>)

timestamp

An epoch timestamp in seconds.

external_user

An external user identifier in the form <identifier>@<yourdomain>