HelloTxt API Documentation.

Introduction

This document outlines the operability of the HelloTxt API. You will find reference material and the API Tools on how to successfully communicate to the API with an external application.

Currently in Private Beta

These API documents are a work in progress and will be changing without notice quite often. Feel free to experiment with the public endpoints but be advised that any application you build with them might break unexpectedly. Until the API if official released publically, please filling out the HelloTxt App Form Request or if you prefer send a request to: api@hellotxt.com .

API Test Tool

An API Test Tool is available at http://hellotxt.com/api/tools. This web based tool has all the necessary form fields needed to test and view the output of all API calls.

Each method description below has a direct link to test that particular API call.

Requirements

Each developer on the HelloTxt API platform will be required to obtain a developer’s API key for each application they intend on producing. Your initial developer keys will be limited to testing on your own social networks registered through HelloTxt API. To obtain a developer’s key fill the HelloTxt App Form Request or if you prefer send a request to: api@hellotxt.com .

Authentication

Authentication is based on a directory with the developer application key / user application key combination. Never should user passwords be captured or sent for validation via the API interface. Doing so will result in an immediate termination of the developer key and possibly overall restriction from using HelloTxt’s services.

Responses

Every request made to the API will return one of two status codes. Currently, all responses will be in XML format. Eventually there will be facilities for JSON and Atom responses.

Example response:

<?xml version="1.0"?>
<rsp status="OK">
  <method>user.services</method>
</rsp>

Example error response:

<?xml version="1.0"?>
<rsp status="FAIL">
  <method>user.services</method>
  <message>User application key could not be validated.</message>
</rsp>

Note: All API queries will produce a response.

Methods

Authentication

user.validate

Description: Validates the given user’s application key.

URL: http://hellotxt.com/api/v1/method/user.validate

Method: POST

Returns: OK, nick, name. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.validate

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
	<rsp status="OK">
	<nick><![CDATA[fabrizio]]></nick>
	<name><![CDATA[Fabrizio Giordano]]></name>
</rsp>

Post

user.post

Description: Posts a message to the user’s HelloTxt services. You can specify the group (inhome, friend, colleague) or a tag of services to update.

URL: http://hellotxt.com/api/v1/method/user.post

Method: POST

Returns: OK. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.post

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-
body	Message body.	yes, not required if there is an multimedia.	string	-
title	Title of the posted message. This will only appear if the specified service supports a title field.	no	string	-
group	The Group (inhome, friend, colleague) or the tag of services to update. If you specify 'all', all user's services will be updated.	no	string	inhome
image	RAW encoded image. format jpg, gif, png	no	RAW	-
debug	Set this value to "1" to avoid posting test data.	no	string	0

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<rsp status="OK">
</rsp>

Services

user.services

Description: Returns a list of services the particular user has set up through HelloTxt.

URL: http://hellotxt.com/api/v1/method/user.services

Method: POST

Returns: OK. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.services

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-
group	The Group of serives to update. (inhome, friend, colleague, all)	no	string	all

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
	<services>
		<service id="tw" name="twitter">
			<code>LvjQ</code>
			<inhome>checked</inhome>
			<friend>unchecked</friend>
			<colleague>false</colleague>
			<tags>tw1 pe</tags>
		</service>
		<service id="id" name="identica">
			<code>zp6P</code>
			<inhome>false</inhome>
			<friend>checked</friend>
			<colleague>false</colleague>
			<tags>zp6P</tags>
		</service>
	</services>
</rsp>

Latest Status Update

user.latest

Description: Returns a list of 20 status update sent through HelloTxt.

URL: http://hellotxt.com/api/v1/method/user.latest

Method: POST

Returns: OK, latest 20 status update through HelloTxt. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.latest

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
<messages>
	<message id="84299">
		<title><![CDATA[]]></title>
		<body><![CDATA[i'm very happy]]></body>
	</message>
	<message id="84294">
		<title><![CDATA[walk]]></title>
		<body><![CDATA[up to the mountain]]></body>
		<img><![CDATA[http://hellotxt.com/i/2ILU]]></img>
		<img_raw><![CDATA[http://hellotxt.fab/image/2ILU.b.jpg]]></img_raw>
	</message>
</messages>
</rsp>

Get Friends

user.getfriends

Description: Returns a list of given user's friends.

URL: http://hellotxt.com/api/v1/method/user.getfriends

Method: POST

Returns: OK, list of friends. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.getfriends

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
<friends>
	<friend id="133" service_id="tw">
		<name><![CDATA[Fabrizio Giordano]]></name>
		<nickname><![CDATA[htxt]]></nickname>
		<avatar><![CDATA[http://s3.amazonaws.com/.../image.jpg]]></avatar>
		<status time="1247507070"><![CDATA[I've been enjoying]]></status>
	</friend>
		<friend id="35" service_id="fb">
		<name><![CDATA[Mark Erio]]></name>
		<nickname><![CDATA[marick]]></nickname>
		<avatar><![CDATA[http://s3.amazonaws.com/.../image.jpg]]></avatar>
		<status time="1247506925"><![CDATA[Every summer]]></status>
	</friend>
</friends>
</rsp>

Check Friends

user.checkfriends

Description: .

URL: http://hellotxt.com/api/v1/method/user.checkfriends

Method: POST

Returns: OK. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.checkfriends

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
</rsp>

Register

user.register

Description: Register a new user in HelloTxt.

URL: http://hellotxt.com/api/v1/method/user.register

Method: POST

Returns: OK, user_key. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.register

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
email	New user's email	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
<user_key>12345abcdef</user_key>
</rsp>

Add/Update a service

user.addservice

Description: Add/update a service to the given user

URL: http://hellotxt.com/api/v1/method/user.addservice

Method: POST

Returns: OK. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.addservice

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-
service	Service to add/update. [tw, fb, id, ps, bb, wp,...]	yes	string	-
code	The service's code you want to update.	no	string	-
nick	The service's nick you want to add/update.	yes	string	-
pwd	The service's password you want to add/update. (base64 encoded)	yes	string	-

Example response 1:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
</rsp>

Example response 2:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="FAIL">
<message>Nick already exist</message>
</rsp>

User key

user.key

Description: Give the user's key of the given mobile key's user.

URL: http://hellotxt.com/api/v1/method/user.key

Method: POST

Returns: OK, user_key. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.key

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
mobile_key	User Mobile Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
<user_key>12345abcdef</user_key>
</rsp>

User Tags deprecated: see user.services

user.tags

Description: Give the user's tags and services for each tag.

URL: http://hellotxt.com/api/v1/method/user.tags

Method: POST

Returns: OK, tags, services for each tag. Error message on failure.

API Tools URL: http://hellotxt.com/api/tools/user.tag

Name	Description	Required?	Type	Default
app_key	Application Key.	yes	string	-
user_key	User Key.	yes	string	-

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
	<tags>
		<tag value="personal">
			<services>
				<service id="id" name="identica">
					<nick><![CDATA[myaccountatidentica]]></nick>
				</service>
			</services>
		</tag>
		<tag value="mimi">
			<services>
				<service id="tw" name="twitter">
					<nick><![CDATA[fadfdsj]]></nick>
				</service>
			</services>
		</tag>
	</tags>
</rsp>

HelloTXT

HelloTxt API Documentation.

Introduction

Currently in Private Beta

API Test Tool

Requirements

Authentication

Responses

Methods

Authentication

Post

Services

Latest Status Update

Get Friends

Check Friends

Register

Add/Update a service

User key

User Tags deprecated: see user.services