This web API allows you to control your Taykt account, including changing message content, viewing activity, creating new messages, and dynamically responding to a message from your own applications.
The API returns either XML or JSON representations in response to RESTful requests.
As there are messages from handsets and messages to handsets, terminology can get confusing. Here are the words we use:
Except where indicated below, all requests to this web service use HTTP BASIC Auth over SSL.
We'd like to be able to offer OAuth in time, but at the moment we don't. This is because we expect the API to be used by account holders to access their own keywords to build services for others. As a result we include the following important restriction on the API: You must not use this API in a way that makes third parties enter their login details. This restriction is included to prevent the spread the password anti-pattern.
If you want to provide a service to others, please get in touch: we may be able to allow third party use of the API in special circumstances; and by letting us know of your interest we might be able to bring-forward our plans for OAuth.
Follow @taykt for announcements regarding API changes.
We will introduce a different version of the API, via content negotiation, if we need to make breaking changes. Adding attributes or elements to representations, or even adding a new resource will not cause an increment in the version.
The API exposes a small set of resources, all of which respond to GET, and some of which can be manipulated via PUT, POST and DELETE. All requests must be made in UTF-8.
The date format returned and expected by the API is yyyyMMdd
As the word needs to be able to be entered, and the message read, on any SMS capable handset the available character set is restricted to the following:
ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz
01234567889][{}^|~\n\r()&@?!$#\"\\/'*:+%;,.<>-=_
£¥è¤éùìòÇØÄäøÆÖöæÑñÅßÜüåɧࡿ
Why such a limited set? While the iPhone and other new phones maybe able to handle UTF-8, older handsets may not.
By default the API will return XML. However we are aiming to support JSON in the future.
If a 4XX response code is given, check the response body as it should contain a helpful message.
200 - OK201 - Created (e.g., a new word was created successfully)400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
409 - Conflict
500 - Internal Server Error
501 - Not implemented
503 - Service Unavailable
From the command line, on UNIX at least, there is cURL. For those, either not on a flavour of UNIX or who prefer their tools GUI there is rest-client.
All examples provided use cURL. Where we put items in {curly_braces}, that would be a parameter you need to supply.
Web hooks allow you to dynamically create a MT message content based on the content of an MO message.
Here's how it works. When Taykt receives a message it will be POSTed to your URL which you will have registered for that word. We will wait for up to 10 seconds for your application to respond before closing the connection and sending the regular Taykt text registered against the word. This means that: (a) Your web hook needs to be mildly responsive; and (b) your standard message text can not be empty and needs to say something sensible.
When we POST the message to you, we include the entire text of the message plus an identifier which is unique per phone number. In effect it's a proxy for the phone number which allows you to keep track of what messages you have sent to that particular phone number.
The two POST parameters are pid and text. You need to respond with a message body that is the message text to send on, which, unsurprisingly need to be no longer than 160 characters.
The pid will be 36 characters in length (e.g. 7c48160a-3989-4ffe-9dc3-da2642d6500a).
To set up a web hook, go to the to Settings tab in Taykt, and click the button to "enable developer mode". From that point on when you edit or create a word you will have an additional text box that allows you to specify a URL (HTTP protocol only).
If you want to read more about web hooks, check out webhooks.org
Here's a simple echo example, written as a Java Servlet in Scala (full source, build instructions):
class EchoServlet extends HttpServlet {
override def doPost(req:HttpServletRequest, resp:HttpServletResponse) {
// Extract details sent from Taykt to this web hook:
val from = req.getParameter("pid")
val mo_msg = req.getParameter("text")
// Compose and send the response:
resp.setContentType("text/plain")
resp.setCharacterEncoding("utf-8");
resp.getWriter().println( from + " sent " + mo_msg )
}
}
You can try this particular service out with the web hook URL
of: http://taykt-demo.appspot.com/echo
Example call to the web hook:
$ curl http://taykt-demo.appspot.com/echo -X POST -d text="this is my message" -d pid="abc123"
abc123 sent this is my message
We also provide a second example which texts back the time in a given location:
$ curl http://taykt-demo.appspot.com/date -X POST -d text="demodate Sydney"
It's 2009-09-17 06:30 in Eastern Standard Time (New South Wales)
You can try out your web hook by assigning your hook to a word and texting in to that word. However, you'll probably want to test it out a little first, and you can do that using the example calls above. Here's a extended description of simulating what Taykt sends to your web hook.
The following cURL command simulates a message Taykt would send to your web hook. It assumes you have the word "echo" registered in Taykt and set up to point to http://taykt-demo.appspot.com/echo and that someone has texted in the message "echo me stuff". We've assumed the mobile number texting in has been converted by Taykt to the identifier of "7c48160a-3989-4ffe-9dc3-da2642d6500a":
$ curl -v http://taykt-demo.appspot.com/echo -X POST -d 'pid=7c48160a-3989-4ffe-9dc3-da2642d6500a' -d 'text=echo me stuff'
The resource back from the echo web hook is:
7c48160a-3989-4ffe-9dc3-da2642d6500a sent echo me stuff
The rest of this document is structured according to the resources you can request and act on.
Returns the list of messages associated with a given account.
| URL: | https://api.taykt.com/account/{email} |
| HTTP Method: | GET |
| Requires Authentication: | Yes |
email - the email address associated with the account.The message resource supports CRUD operations at the same address using a different METHOD.
| URL: | https://api.taykt.com/message/{word} |
| Requires Authentication: | Yes |
Create a message associated with a given word.
word - the word that is texted in to Taykt.A successful response will return a 201 HTTP code.
The above command will prompt you for body content; to send content finish with ctrl + D
Read a message associated with a given word.
word - the word that is texted in to Taykt.Please note: the mo_message links are not yet implemented and will return a 501 error.
Update a message associated with a given word.
word - the word that is texted in to Taykt.The above command will prompt you for body content; to send content finish with ctrl + D. There is no response body from this call.
If the operation is successful the response body will be empty and the status will be 200.
Delete the message associated with a given word.
word - the word that is texted in to Taykt.If the operation is successful the response body will be empty and the status will be 200.
Checks the availability of a word.
| URL: | https://api.taykt.com/word/{word} |
| HTTP Method: | GET |
| Requires Authentication: | No |
| Requires Encryption: | No |
word - the word to look up.Note that you should check not only the availability attribute, but also the word
attribute, as any leading or trailing space from the word you requested will have been trimmed meaning the
availability status is for the word defined by the value of the word attribute.
This call will return a 400 status code if the word requested contains unacceptable characters. For words, stick to letters and numbers.
Here are examples of simple applications built using the Taykt API .
That's the complete alpha API: please be gentle with us, and please report problems via email. Keep an eye on the @taykt Twitter account for news.