Skip to content

DeskSMS API

Jump to bottom Edit New page
koush edited this page Dec 3, 2012 · 30 revisions

#Getting Started The DeskSMS API is JSON REST API. The API can let you read and modify your SMS history. It also lets you send text messages from your phone. To use the API, you must first authorize/log into it with the usual array of Google Login options detailed in the next section.

#Authorization To use the API, all your requests must be come with a form of authorization for your Google Account.
There are two ways you can authorize: ClientLogin/Cookies or OAuth.

OAuth is the preferred method of authorization, as it does not require that the user enter their username and password in your application of website. It's a bit of a pain to get going though (ugh).

##OAuth Here is a Python script that will retrieve the user's inbox using OAuth as an authorization mechanism.
Note that the OAuth Authorization Header must be used. OAuth in the query string or post parameters is not supported.

##ClientLogin/Cookies

Google's ClientLogin is super easy to use, but is not preferable as it requires that you collect a username and password from the user. Here's how to initiate do ClientLogin and use the resultant Cookie to make a request against the API. Note that this entire example is done with the Unix curl in a console shell session. Easy!

USERNAME=your_email@gmail.com
PASSWORD=swordfish
# First, let's get an auth token
curl -d "accountType=HOSTED_OR_GOOGLE&Email=$USERNAME&Passwd=$PASSWORD&service=ah&source=desksms" https://www.google.com/accounts/ClientLogin

This will print the following credentials:

SID=DQAAALoAAAB...........................................................................
LSID=DQAAALwAAADfRf9M...........................................................................
Auth=DQAAAL0AAADfRf9MqXN9aV...........................................................................

You are interesed in the Auth portion. Let's grab that entire line and conveniently set it as an environment variable.

Auth=DQAAAL0AAADfRf9MqXN9aV...........................................................................

Let's get a Cookie for this Auth token. The cookie will be in the header of the response, so we can just pipe the response body (which is unncessary) to /dev/null:

curl -v "https://desksms.appspot.com/_ah/login?auth=$Auth" > /dev/null

There should be a lot of spew due to the verbose curl output, but in there, you should see:

< Set-Cookie: SACSID=AJKiYcEj................................................................; expires=Sun, 24-Jul-2011 23:57:

The bit that you want to save for your application is simply everything before the semicolon, ";":

SACSID=AJKiYcEj................................................................

So, if you wanted to retrieve your SMS history using curl:

# set the cookie as a convenient environment variable
SACSID=AJKiYcEj................................................................
curl -H "Cookie: SACSID=$SACSID" https://desksms.appspot.com/api/v1/user/$USERNAME/sms

Or, for example, using Java:

HttpClient client = new DefaultHttpClient();
HttpGet get = new HttpGet("https://desksms.appspot.com/api/v1/user/your_email@gmail.com/sms");
String ascidCookie = settings.getString("Cookie");
get.setHeader("Cookie", ascidCookie);
get.setHeader("X-Same-Domain", "1"); // XSRF
HttpResponse response = client.execute(get);

#Web Service Endpoints Woot! You are successfully authorizing against the web service endpoints! All your SMS/call data can be retrieved, added, and deleted by GET, POST, and DELETE requests against their corresponding web service endpoints. Ie,

  • A POST request against your /outbox, for example, would make your phone send out a tex.t
  • A GET request against your /sms would retrieve your SMS history.

The resultant data will then be returned as JSON (or JSONP if you are using ajax). Note JSONP and ClientLogin is not supported at the moment and currently only works when there is no HTTP referer. Ie, FireFox or Chrome Extensions will work, but a hosted website will not.

All requests come with the following prefix/format:

https://desksms.appspot.com/api/v1/your_email@gmail.com/<bucket>

The two primary buckets are /sms and /outbox. Generally, you read from the SMS folder to view your SMS history, and you write to the outbox to send a text message to a contact from your phone number.

##Reading Text Messages (Reading Data) All of the URLs detailed in the following section can be quite easily tested in a browser. First, go to the (DeskSMS Website)[https://desksms.appspot.com] and log in. Then, just paste the URLs into your browser, replacing the sample email with your login email. This is actually how I debug DeskSMS myself.

###SMS Bucket (messages you have sent and received):

https://desksms.appspot.com/api/v1/your_email@gmail.com/sms

Results in:

{
    "data": [{
        "name": "Koushik Dutta",
        "number": "+15555555555",
        "date": 1311458362799,
        "message": "Hello World!",
        "type": "incoming"
    },
    {
        "name": "Koushik Dutta",
        "number": "+15555555555",
        "date": 1311458362798,
        "message": "First post!",
        "type": "outgoing"
    }]
}

The /sms bucket also supports the following combinations of self explanatory query string parameters:

  • max_date - List messages before the provided date (inclusive). Milliseconds since epoch.
  • min_date - List messages after the provided date (inclusive). Milliseconds since epoch.
  • before_date - List messages before the provided date. Milliseconds since epoch.
  • after_date - List messages after the provided date. Milliseconds since epoch.

You can also look up an item specifically by key:

https://desksms.appspot.com/api/v1/your_email@gmail.com/sms?key=2323232%2F343434343

Remember to URL encode the key, as it will contain a slash character.

###Outbox Bucket (messages that are pending to be proxied and sent by the phone):

https://desksms.appspot.com/api/v1/your_email@gmail.com/outbox

Results in:

{
    "data": [{
        "date": 1311475416797,
        "message": "This will be sent from the phone!",
        "number": "5551234567"
    },
    {
        "date": 1311475435854,
        "message": "This will also be sent from the phone!",
        "number": "5557654321"
    }]
}

You don't really ever need to "read" the outbox. This API exists so that the phone can read it and and send queued text messages. The /outbox bucket also supports the following combinations of self explanatory query string parameters:

  • max_date - List messages before the provided date (inclusive). Milliseconds since epoch.
  • min_date - List messages after the provided date (inclusive). Milliseconds since epoch.
  • before_date - List messages before the provided date. Milliseconds since epoch.
  • after_date - List messages after the provided date. Milliseconds since epoch.

Remember to URL encode the key, as it will contain a slash character.

Call Bucket (Call History)

https://desksms.appspot.com/api/v1/your_email@gmail.com/call

Results in:

{
    "data": [{
        "number": "12065551234",
        "date": 1311565654204,
        "duration": 0,
        "type": "missed"
    },
    {
        "number": "15553305500",
        "date": 1311364202998,
        "duration": 0,
        "type": "missed"
    }]
}

##Sending a Text Message (Writing Data) Sending a text message is easy! Just do a POST request to the /outbox URL with JSON data in the similar format as you would receive from a GET request:

{
    "data": [{
        "message": "This will be sent from the phone!",
        "number": "5551234567"
    }]
}

Note that the "date" is not necessary, as it will be populated by the server/phone.

##Deleting Texts (Deleting Data) Deleting items is simply a DELETE request against any of the aforementioned GET URL queries.

You can also delete an item specifically by key:

https://desksms.appspot.com/api/v1/your_email@gmail.com/sms?key=2323232%2F343434343

Remember to URL encode the key, as it will contain a slash character.

Add a custom footer
Add a custom sidebar
Clone this wiki locally