API

Hellotxt API Documentation.

Introduction

Here at Hellotxt we have done the hard work creating an open API. For all of you who are interested in putting your programming skills to good use, why not use our API to enhance the Hellotxt social experience?

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 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 key fill out the Hellotxt App Form Request or if you prefer send a request to: api [at] hellotxt [dot] com and agree to the API terms of service.

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.
NameDescriptionRequired?TypeDefault
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>
	<avatar><![CDATA[http://hellotxt.com/avatar/fabrizio/medium/image.jpg]]></avatar>
</rsp>

Post

user.post

Description: Posts a message to the user’s Hellotxt services.

URL: http://hellotxt.com/api/v1/method/user.post
Method: POST
Returns: OK. Error message on failure.
NameDescriptionRequired?TypeDefault
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 no string -
networks Social network accounts to update. Must be in the format social_id-code_social_id,social_id-code_social_id... code_social_id is 4+ characters long and social_id is 2 characters long [tw, fb, id, ps, bb, wp,...]. no string -
poi_lat Latitude of the POI associated to the post no string -
poi_long Longititude of the POI associated to the post no string -
poi_name Name of the POI associated to the post. If left blank and the poi_lat and poi_long parameters are provided it defaults to 'current position' no string -
scheduled_time Scheduled time of the post. Must be in the ISO 8601 format no string -
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.
NameDescriptionRequired?TypeDefault
app_key Application Key. yes string -
user_key User Key. yes string -

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
	<services>
		<service id="tw" name="twitter" description="Twitter">
			<code>LvjQ</code>
			<nick><![CDATA[test]]></nick>
			<checked>true</checked>
			<inhome>checked</inhome>
			<friend>unchecked</friend>
			<colleague>false</colleague>
			<tags>tw1 pe</tags>
		</service>
		<service id="id" name="identica" description="Identica">
			<code>zp6P</code>
			<nick><![CDATA[test2]]></nick>
			<checked>false</checked>
			<inhome>checked</inhome>
			<friend>unchecked</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.
NameRequired?TypeDefault
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.
NameDescriptionRequired?TypeDefault
app_key Application Key. yes string -
user_key User Key. yes string -
networks Social network accounts from which the friends are taken. Must be in the format social_id-code_social_id,social_id-code_social_id... code_social_id is 4+ characters long and social_id is 2 characters long [tw, fb, id, ps, bb, wp,...]. no string -

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="OK">
<friends>
	<friend id="133" service_id="tw" service_code="o3lW">
		<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" service_code="jL51">
		<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: Ask hellotxt to fetch the user's friends status updates from various social networks.

URL: http://hellotxt.com/api/v1/method/user.checkfriends
Method: POST
Returns: OK. Error message on failure.
NameDescriptionRequired?TypeDefault
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.
NameDescriptionRequired?TypeDefault
app_key Application Key. yes string -
email New user's email yes string -
pass New user's password (min 5 chars). If left blank a random one will be generated and sent to the user's email no 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.
NameDescriptionRequired?TypeDefault
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>

Remove a service

user.removeservice

Description: Remove a service from the given user

URL: http://hellotxt.com/api/v1/method/user.removeservice
Method: POST
Returns: OK. Error message on failure.
NameDescriptionRequired?TypeDefault
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. 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>Error: No Social</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.
NameDescriptionRequired?TypeDefault
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>

Follow on Twitter Follow on Facebook