Widgeous Developer's API
Widgeous applications are mainly about input/output handling. Through Widgeous API, developers no longer have to:
- worry about choosing which communication channels to integrate with;
- worry about the update/changes of channel protocols;
- learn the different APIs of different channels;
- worry about how to handle incoming and outgoing messages from different channels
Widgeous will be handling that all for you. All you need to do as a developer is to concentrate on the features of your application and leave the communication component to us.
How Widgeous API Works
Everytime a user tries to use your application through Widgeous, Widgeous will be doing some basic parsing to determine which application a user is trying to use and if a command is valid.
If it is valid, Widgeous will be making an HTTP call to your externally hosted application and pass the necessary arguments via HTTP POST.
The Arguments
These are the basic building blocks of Widgeous calls. Arguments tell your application on the who, the why, the what, the how of an input made to your application.
Basic arguments, passed via HTTP POST:
- application_name — The shortcode for the application.
- command — The command that triggers this call. Basically the 2nd word of the input.
- params — The parameters for the command.
- authenticated — Is user authenticated on Widgoeus? 1 - Yes; 0 - No.
- username — If a user is authenticated on Widgeous, this argument will be his/her Widgeous username.
- user_channel_hash — A unique hash generated to uniquely identify a user/channel, regardless of the user is logged in or not.
- channel — This can be either email, wlm (Windows Live Messenger), twitter or wdevice (Widgeous Device). More channels coming soon...
How to output to the user right after a call
It does not matter how the user has sent the input, to reply back to the user right after a call, simply output will do. Yes. That means echo, print, println, or whatever that's being known in your programming language.
Session
Widgeous has a limited session support to allow application developers to create a more user-friendly command-line applications. With session support, if used correctly, would eliminate the need of users from having to keep entering the APPLICATION_NAME COMMAND_NAME everytime.
To enable session support for a particular command, simply enable it at the Commands Manager of your application. Commands Manager is located at the Develop tab.
API Methods
Widgeous provides a few REST-based methods for applications to talk to Widgeous requiring Widgeous to first connect to the application server.
All method calls require the POSTing of API keys under the parameter name of 'api_key'. You may obtain your unique API key for your application at the application options page. It is important that all parameters are to be URL-encoded before being POSTed to Widgeous.
Methods currently available:
direct_message
Sending of direct message to a Widgeous user without involving any user queries. If the user is a registered Widgeous user, the direct message will be sent via the preferred messaging channel of the user.
URL: http://widgeo.us/api/direct_message
POST parameters:
- api_key — Your unique applicaation API key
- type — Recipient type. Currently accepts 'widgeous', 'sms', 'email' or 'user_channel_hash'.
- recipient — The recipient address, corresponding to the type specified in the previous parameter. For 'widgeous' type, recipient field would be the Widgeous username. 'sms' would be the SMS number of the user, including the '+' sign and coutnry code (Widgeous only supports Singapore numbers for the time being). 'email' would be the email. 'user_channel_hash' would be the unique 'user_channel_hash' given when the user made an earlier query to your application.
- message — The message to be delivered to the user. Keep it short as the message may be truncated when being delivered off different channels.
Regardless of 'type', if the recipient has become a registered Widgeous user, direct_message would return the user's Widgeous username.
end_session
End an existing session without requiring the user to type 'end'.
URL: http://widgeo.us/api/end_session
POST parameters:
- api_key — Your unique applicaation API key
- session_id — Session ID of which you wish to end.
Questions?
Please ask about it at our forums or you can email us at ask@widgeo.us should you have any questions or requests regarding the developer's API.