Twalkin Developer API

Are you interested in utilizing the Twalkin platform to extend your existing product or service? Below is our API documentation to get you started!

Introduction

The Twalkin API is built using RESTful principles (as much as possible) and uses JSON as its data transport. With our API, you can perform almost every action available through our website or iPhone app.

Rate Limiting

Twalkin implements rate limiting by only allowing a user so many requests per hour. Our hourly limits have been set generously for now, but may change as demand increases.

In every response, we include the "X-RateLimit-Limit" and "X-RateLimit-Remaining" headers so you can know how many remaining requests you have for a particular request type. If a rate limit has been met, the request will return HTTP status code 403.

Also, we limit the number of new twalks that can be created in an hour on an application level (whether from the website, iPhone app, or API). If a create twalk limitation has been hit, HTTP status code 400 and an appropriate status description will be returned.

Below is a breakdown of limitations:

  • Reads (GET) - 1000 per hour
  • Writes (POST, PUT, DELETE) - 1000 per hour
  • New Twalks - 20 per hour (doesn't count against write limit)
Authentication

The Twalkin API currently only accepts Basic Authentication. The credentials provided should be the user’s Twitter username and password. As of now, every method requires credentials.

Methods

The base URL for all of the methods listed below is https://api.twalk.in

Although HTTPS isn’t currently a requirement, we highly recommend it. We may drop support for unsecure access to the API in the future. If this should happen, we will post sufficient notice on the Twalkin API Twitter Account.

All write methods will return HTTP status code 400 with a corresponding status description by default on failure.

Verify Account Credentials & Retrieve Account Info

GET /account/verify

Response is a JSON serialized AccountInfo object on success.

This method authenticates a user against Twitter and updates Twitter info on Twalkin if successful. It returns the user’s Twalkin information.

This method should be used at the beginning of your application’s user session to verify that the user’s credentials match up with Twitter. All other methods in the Twalkin API authenticate against directly against Twalkin’s stored credentials to prevent having to make a trip to Twitter for every method call. For example, this method is useful in situations where a user may have changed their password on Twitter, but Twalkin still has the old password.

Add Phone Number

POST /account/phonenumbers

Request contains a JSON serialized String, which is the phone number being added.

Response is HTTP status code 201 on success.

This method adds a phone number to the user’s Twalkin account. This phone number should be one that the user will be calling from to attend twalks.

Remove Phone Number

DELETE /account/phonenumbers/{phoneNumber}

{phoneNumber} is the phone number to be removed.

Response is HTTP status code 200 on success.

This method removes a phone number from the user’s Twalkin account.

Create Twalk

POST /twalks/mine

Request contains a JSON serialized Twalk object.

Response is HTTP status code 201 and a JSON serialized Twalk object (with creation data) on success.

This method creates a new Twalk.

Update Twalk

PUT /twalks/mine

Request contains a JSON serialized Twalk object.

Response is HTTP status code 200 on success.

This method updates an existing Twalk.

Delete Twalk

DELETE /twalks/mine/{twalkId}

{twalkId} is Id of the Twalk to be deleted.

Response is HTTP status code 200 on success.

This method deletes an existing Twalk.

Get Twalk Details

GET /twalks/details/{twalkId}

{twalkId} is Id of the Twalk to get.

Response is a JSON serialized Twalk object on success.

This method gets details for the specified Twalk.

Get Twalk Details By Short Code

GET /twalks/details/{twalkShortCode}/shortcode

{twalkShortCode} is Short Code of the Twalk to get. For example, http://twalk.in/t/hQ, where hQ is the Short Code.

Response is a JSON serialized Twalk object on success.

This method gets details for the specified Twalk.

Get My Twalks

GET /twalks/mine

Response is a JSON serialized Array of Twalk objects on success.

This method gets a list of Twalks the user has created or has been invited to attend.

Get Featured Twalks

GET /twalks/featured

Response is a JSON serialized Array of Twalk objects on success.

This method gets a list of all Featured Twalks.

Get Popular Twalks

GET /twalks/popular

Response is a JSON serialized Array of Twalk objects on success.

This method gets a list of 50 Popular Twalks.

Get Fresh Twalks

GET /twalks/fresh

Response is a JSON serialized Array of Twalk objects on success.

This method gets a list of 50 Fresh (most recently created) Twalks.

Get Twalkers on Twalk

GET /twalks/manage/{twalkId}

{twalkId} is the Id of the Twalk for which to retrieve Twalkers.

Response is a JSON serialized Array of Twalker objects on success.

This method lists the current Twalkers on a Twalk.

Perform Action on Specified Twalkers

PUT /twalks/manage/{twalkId}/{manageAction}

{twalkId} is the Id of the Twalk for which to perform the management action.

{manageAction} the action to perform on the specified Twalkers. Valid options are: mute, unmute, boot

Request contains a JSON seralized Array of Twalker objects.

Response is HTTP status code 200 on success.

This method performs a Twalk management function on specified Twalkers.

Add Twalk to Saved Twalks

POST /twalks/saved/{twalkId}

{twalkId} is the Id of the Twalk to save.

Response is HTTP status code 201 on success.

This method saves a Twalk to the user’s saved Twalk list.

Remove Twalk from Saved Twalks

DELETE /twalks/saved/{twalkId}

{twalkId} is the Id of the Twalk to unsave.

Response is HTTP status code 200 on success.

This method unsaves a Twalk from the user’s saved Twalk list.

Get Saved Twalks

GET /twalks/saved

Response contains a JSON serialized Array of Twalk objects on success.

This method lists Twalks in the user’s saved Twalk list.

API Objects

The following objects should be JSON serialized for all methods. All dates should be expressed as UTC timestamps as a number (not string).

AccountInfo

  • username : string
    Twitter username
  • name : string
    Display name
  • phoneNumbers : Array of string
    A list of phone numbers that the user will be calling from to attend Twalks
  • phoneNumbersFormatted : Array of string
    A formatted list of phone numbers that the user will be calling from to attend Twalks

Twalk

  • id : int
    Id of the Twalk (not specified for create)
  • title : string
    Name of the Twalk
  • description : string
    Description of the Twalk
  • createdBy : string
    Username of the Twalk creator
  • twalkURL : string
    Short URL of the Twalk
  • twalkPhoneNumber : string
    Phone number to call to attend Twalk
  • twalkPhoneNumberFormatted : string
    Formatted phone number to call to attend Twalk
  • twalkPin : string
    PIN number for the Twalk (only for public Twalks)
  • isPrivate : boolean
    Indicates if Twalk is Private or Public
  • startsOn : long
    Date the Twalk starts (in UTC)
  • expiresOn : long
    Date the Twalk expires (in UTC)
  • maxTwalkers : int
    Maximum number of Twalkers allowed on Twalk
  • twalkMode : int
    Specifies who’s allowed to speak. Acceptable values: 1 (Everyone), 2 (Certain People), 3 (Only Me)
  • allowedToSpeak : Array of string
    A list of usernames who are allowed to speak (only works when Twalk Mode = 2)
  • allowedToAttend : Array of string
    A list of usernames allowed to attend (only works when Twalk is Private)

Twalker

  • id : int
    Id of the Twalker
  • username : string
    Twitter username of the Twalker
  • displayName : string
    Display name of the Twalker
  • imageURL : string
    Profile Image URL for the Twalker
  • canTalk : boolean
    Indicates if the Twalker is able to speak
Support

Feel free to contact us at api@twalk.in or on our Twalkin API Twitter account if you have any questions regarding the API.