udefn API is a programatic interface which users can utilize to
create their own bots. udefn API is very easy to integrate with and requires very minimal programming expertise. We have architected udefn API in such a way that you don't need powerful servers to receive query requests.
You have two options to receive incoming queries from mobile users.
- You can either poll udefn servers to get messages which are designated to your bots and send back responses. This enables you to run your bots on your laptop, home computer etc.
- Or you can specify a Message receiver link in your bot settings and udefn will post message details to this location when a mobile user queries your bot
To send responses back to mobile user, you can call
SendOutgoingMessage API. If you already specified a Message receiver link in bot settings, udefn can capture the your response to postback and send the contents to the mobile user.
udefn API page has detailed instructions on how to use udefn API.
Bot is an automated program which responds to mobile user's queries. They can be query or alert based.
There are two types of bots -
- Query - Query bots send exactly one response for each request from the mobile user.
- Alert - Alert bots on the other had can send multiple responses for each request from mobile user. The number of responses and duration of responses are strictly controlled by udefn. Bots have to specify how many maximum responses they might send. This is displayed to the mobile user. The most number of responses that an alert bot can send is 50 and maximum duration to send these responses within is 24 hours.
There are two categories of bots -
- Reverse-Charge - Query response from your bot can be approximately 70 characters long. udefn will append contextual advertisements to the message. Bot earns points for each query per plan pricing.
- Charge - Query response from your bot can be approximately 140 characters long. udefn will not place any advertisements in the response. Bot incurs charges for each query per plan pricing. Bot has to ensure that valid billing info is provided before they can process any incoming messages.
All messages may be subjected to standard rates per your plan with your carrier. Please visit your carrier for more information.
Sign in to your udefn account and Enable publisher features by clicking on Account settings.
- Click on My bots link and then click Create a new bot link.
- Refer to bot settings section to learn more about various fields while creating a bot.
- Make a note of the BotID for the newly created bot. You should pass this in your API call when reading incoming messages and sending outgoing messages.
- You can code your bot in your preferred language. We have sample code in Ruby, PHP and C#. We will be adding more samples soon. The workflow is straight forward.
- If you choose to poll udefn for incoming messages -
- Your bot should poll udefn server to see if you have any incoming messages from users by calling GetIncomingMessages API. We recommend setting your polling to every 4 to 8 seconds. If the message is not picked up for processing by bot in 30 seconds, it will marked as timed out and an response will be sent to the mobile user. Along the same line, bot should send initial response within 30 seconds. If not, the request will be marked as timed out and an response will be sent to the mobile user. Refer to API documentation for details on various input and output parameters.
- When you receive incoming messages from users, you should perform the published action and send one (or more) response back to the user by calling SendOutgoingMessage API. Refer to API documentation for details on various input and output parameters. After receiving incoming messages, you have 30 seconds to send the response back to the user. If this timer expires, a notice detailing the expiry is sent to the user and future attempt to send response message to the user for the expired query will be rejected.
- Repeat step 4.1.1 - 4.1.3.
- If you choose to specify Message receiver link and receive HTTP posts for each incoming message -
- Code a HTTP page which processing incoming posts and performs the published action. If you enabled Parse receiver page for message response? in your bot settings, the content of this page will be parsed for outgoing response to the user. You don't have to call SendOutgoingMessage API. Certain cases dictate that you call SendOutgoingMessage API explicitly. In those cases, follow 4.1.2.
- MO_MOOutgoingID - string(50) - Message ID of the incoming message. This should be included when calling SendOutgoingMessage API.
- MO_TransactionID - string(50) - Transaction ID associated with the incoming message.
- MO_BotID - string(50) - ID of the bot this message is intened for. If you created more than one bot, this ID will be unique for each of them.
- MO_Carrier - string(50) - Name of the mobile user's carrier. See Carrier Info page for list of carriers.
- MO_Body - string(160) - Message body sent by the mobile user. Keyword part of the body will be removed by udefn and bot will receive the remainder of body.
- MO_Language - string(50) - Language of the incoming message
- MO_GeneratedAtUtc - datetime in yyyy-MM-dd HH:mm:ss'Z' format - Timestamp of when the incoming message was received by udefn in UTC.
- MO_ProcessedAtUtc - datetime in yyyy-MM-dd HH:mm:ss'Z' format - Timestamp of when the incoming message was processed by udefn in UTC.
- MO_ResponseBeforeUtc - datetime in yyyy-MM-dd HH:mm:ss'Z' format - Timestamp of window, within which the bot should send a response. If you have Parse receiver page for message response? checked, you can ignore this field.
- MT_MaxLength - int - Maximum allowed length of the response body. For Reverse charge bots, this will be 70 characters and for Charge bots, this will be 140 characters. If bot's response exceeds this limit, the response will be truncated to this limit.
- MO_ProfileID - int - If you created any Bot fields for your bot, this field will include a unique ID identifying mobile user's profile. All messages from the same mobile user to a particular bot will have the same MO_ProfileID.
- LC_Count - int- If you checked Request user's location? when setting up the bot, this field will contain the total number of locations of that particular mobile user. Mobile users have the option to enter more than one location.
LC_0 .. LC_x - string - these fields will contain mobile user's location values. These are free text fields. So these fields can contain complete street address, or just the city. - Profile_ - string - If you created any Bot fields for your bot, mobile user will be prompted to enter details for each of them. For example, if you created a Bot fields called "Name", a parameter called Profile_Name will be included.
An example of a typical POST parameters.
MO_MOOutgoingID=22f35f75-a1ac-42c6-8596-6fceb432cd65&MO_TransactionID=22f35f75-a1ac-42c6-8596-6fceb432cd65&MO_BotID=64fa2912-5dfa-4198-a635-80558e57ceb5&MO_ProfileID=108&MO_Carrier=Verizon Wireless&MO_Body=hello world&MO_Language=English&MO_GeneratedAtUtc=2009-02-06 12:38:45Z&MO_ProcessedAtUtc=2009-02-06 12:38:46Z&MO_ResponseBeforeUtc=2009-02-06 12:39:16Z&MT_MaxLength=150&LC_Count=1&LC_0=Rochester,NY&Profile_Field1=profilevalue
To send a response to this request, you could write the response to the POST'ed page. HTML tags will be stripped and only the text will be processed.
You entered - hello world
Or you could make a call to
SendOutgoingMessage API. API supports GET and POST methods. Check out
API page for more details.
http://api.udefn.com/apigateway.ashx?outputType=Json&type=Api&method=SendOutgoingMessage&moOutgoingID=22f35f75-a1ac-42c6-8596-6fceb432cd65&language=&body=You entered - hello world&responseExpected=false&username=yourUsername&apiKey=yourApiKey
Yahoo Developer Network has extensive documentation on various languages and JSON. Visit
json.org to see if there are any JSON library published for your favorite language.
Type - You can set this to alert or query. Please refer
types of bots to learn more about each of them.
Category - You can set this to reverse-charge or charge. Please refer
bot categories to learn more about each of them.
Visible to everyone? - If you would like to share your bot with public, you can select this option. This will make your bot publicly visible.
Visible only to users - If you would like to share your bot with only a select group of users, you can enter their usernames or emails separated by a comma.
Default keyword - You can optionally provide a default keyword which will be provided as default keyword option for users when they add your bot to their profile.
MultipleResponse - If your bot generates multiple responses (for example, an alarm bot might send a confirmation messages once set and an alert messages when alarm expires), check this box. udefn has a maximum limit of 5 response messages per incoming message query and 24 hour window limit within which multiple responses can be sent by the bot.
Allow multiple instances? - If the functionality of your bot is such that it can be added multiple times to users profiles (for example, an email bot), check this box.
Message receiver link - This is optional. You can decide to poll for incoming messages or specify a valid location to receive incoming requests. udefn will perform a validation to ensure that you have access to this location by making a
GET request passing in HTTP parameter called
GN_VerifyCode and this location should return this code on its page. Refer to
POST Parameters for a list of parameters that will be POST'ed to this link. See our
code samples for more details.
Parse receiver page for message response? - If you specified a Message receiver link, you can send response text directly in this response or choose to send
outgoing message by calling
SendOutgoingMessage API. Refer to
API documentation for details on various input and output parameters.
Request user's location? - If your bot needs mobile user's location (which they can enter in their account settings), you can enable this. Mobile users can decide whether they want to allow or disallow sending their location.
Bot fields - You can optionally get profile based information from users. For example, an email bot might require POP3 server name, Username, and Password information from user when they add the bot to their profile. This information will be passed on to the bot when they poll for incoming messages. This enables users to just send in their keyword to invoke the bot (without having to SMS complicated account settings).
udefn supports following field types -
- Text
- Password
- Number
- Email
- List (You can specify multiple values separated by , in Value field)
Before an bot can go live, it has to be approved by udefn. Please refer to
guidelines,
program policy, and
terms of service for more information. Once you have created your bot, you can queue it for approval from its draft status. udefn will review your bot and approve it or recommend changes to be made. Once satisfied, your bot will be approved and will go live. Once live, you can make changes to your ad without going through approval again. However, if
Type,
Visible to everyone? or
Category is changed, your bot will automatically be set to
draft status and you can queue it for approval.
Bot announcements are a way to let mobile users know about updates or enhancements to your bot. You can select a bot and select announcement type (Email or Txt). All mobile users who have added your bot in their profile and opt-ed to receive announcements will receive it. This announcement will also be available through the
bot gallery.
udefn supports payments using
Paypal™. Sign in to your udefn account and click on
Deposit information link and update your deposit information. You will be responsible for any fees charged by
Paypal™.
Before a bot can go live, you have to specify a valid billing method by clicking on Billing information or deposit method by clicking on Deposit information depending on the type of bot (charge or reverse-charge). You either get paid points (reverse-charge bots) or get charged points (charge bots) for each query response. There is no monthly fees or setup fees. And there is no up-front payment. udefn will bill publishers the earlier of 30 days or 100000.00 points. If the attempt to bill to provided method fails, the bots will go offline immediately. When payment method is corrected and successfully billed, it will to live again.