DeskSMS API

#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.

##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

[email protected]
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/[email protected]/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.

All requests come with the following prefix/format:

https://desksms.appspot.com/api/v1/[email protected]/<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) ###SMS Bucket (messages you have sent and received):

https://desksms.appspot.com/api/v1/[email protected]/sms

Results in:

{
    "data": [{
        "name": "Koushik Dutta",
        "read": false,
        "number": "+15555555555",
        "thread_id": 5,
        "date": 1311458362799,
        "message": "Hello World!",
        "type": "incoming",
        "id": 217,
        "key": "+15555555555\/1311458362799"
    },
    {
        "name": "Koushik Dutta",
        "read": false,
        "number": "+15555555555",
        "thread_id": 5,
        "date": 1311458362798,
        "message": "First post!",
        "type": "outgoing",
        "id": 216,
        "key": "+15555555555\/1311458362798"
    }]
}

Note: The key is a concatenation of the number and the date.

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

• max_date - List messages before the provided date. Milliseconds since epoch.
• min_date - List messages after the provided date. Milliseconds since epoch.
• number - List messages only from a specific number. The number must be an exact match.

You can also look up an item specifically by key:

https://desksms.appspot.com/api/v1/[email protected]/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/[email protected]/sms

Results in:

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

Note: The key is a concatenation of the number and the date.

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. Milliseconds since epoch.
• min_date - List messages after the provided date. Milliseconds since epoch.
• number - List messages only from a specific number. The number must be an exact match.

You can also look up an item specifically by key:

https://desksms.appspot.com/api/v1/[email protected]/sms?key=2323232%2F343434343

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

##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/[email protected]/sms?key=2323232%2F343434343

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