API

Instructions on how to quickly integrate InfoPi messaging services into various solutions.

Access

Webservices URL: http://infopi.io/text/index.php?app=ws

Parameters

Listed in the below table are webservices parameters for individual tasks.

Name

Description

h

webservices token, configured by user from Preferences menu

u

username

p

password, supplied for op=get_token

op

operation or type of action

format

output format selection

from

SMS sender ID (for op=pv)

to

destination numbers, @username or #groupcode, may use commas

footer

SMS footer (for op=pv)

nofooter

remove SMS footer

msg

message (+ or %20 for spaces, urlencode for non ascii chars)

schedule

schedule message delivery, format: YYYY-MM-DD hhss

type

message type (flash or text)

unicode

whether message unicode or not (1=unicode, 0=not unicode)

queue

queue code

src

sender number or ID

dst

destination number (single number)

dt

send SMS date/time

smslog_id

SMS Log ID

last

last SMS log ID (this number not included on result)

c

number of delivery status that will be retrieved

kwd

keyword

query

query server for useful information

Please note that all values should be URL encoded.

Return Codes

Below table lists return codes after unsuccessful call to a webservices operation. Successful operation will return an OK data in the response message.

Please note that by default the response message is a JSON encoded message.

Error code

Description

ERR 100

authentication failed

ERR 101

type of action is invalid or unknown

ERR 102

one or more field empty

ERR 103

not enough credit for this operation

ERR 104

webservice token is not available

ERR 105

webservice token not enable for this user

ERR 106

webservice token not allowed from this IP address

ERR 200

send message failed

ERR 201

destination number or message is empty

ERR 400

no delivery status available

ERR 401

no delivery status retrieved and SMS still in queue

ERR 402

no delivery status retrieved and SMS has been processed from queue

ERR 501

no data returned or result is empty

There might appear new error codes in the future.

You should be aware that new codes might appear in this syntax:

Error code

Description

ERR 1xx

authentication or parameter erorrs

ERR 2xx

specific pv errors

ERR 4xx

delivery status errors

ERR 5xx

others

Protocol for API tasks

Send Message

Send message to a single or multiple mobile numbers, @username or #groupcode

Parameters

Name or description

Operation

pv

Mandatory

u h to msg

Optional

type unicode from footer nofooter format

Returns

return codes

Parameter to can be international formatted mobile number, #groupcode or @username, or a mix of them. Separate by commas for multiple values. Numbers starting without country code will be replaced by default country code in your user preferences account.

Outgoing SMS and delivery status

List outgoing SMS and delivery status.

Parameters

Name or description

Operation

ds

Mandatory

u h

Optional

queue src dst dt smslog_id c last format

Returns

data or return codes

Parameter c will retrieve as many as c value, last retrieves data from last SMS log ID.

 

Inbox

List SMS on user's inbox.

Parameters

Name or description

Operation

ix

Mandatory

u h

Optional

queue src dst dt smslog_id c last format

Returns

data or return codes

Parameter c will retrieve as many as c value, last retrieves data from last SMS log ID.

User Credit

Get user's credit information.

Parameters

Name or description

Operation

cr

Mandatory

u h

Optional

format

Returns

user's credit or return codes

Get Token

Get user's webservices token. This can be used as a login mechanism.

Parameters

Name or description

Operation

get_token

Mandatory

u p

Optional

format

Returns

webservices token or return codes

Set Token

Set user's webservices token. This can be used as a change password mechanism.

Parameters

Name or description

Operation

set_token

Mandatory

u h

Optional

format

Returns

new webservices token or return codes

Get Contact List

Get contact list by name, mobile or email.

Parameters

Name or description

Operation

get_contact

Mandatory

u h kwd

Optional

c format

Returns

list of contacts similar or the same as kwd or return codes

Get Group Contact List

Get group contact list by name or code

Parameters

Name or description

Operation

get_contact_group

Mandatory

u h kwd

Optional

c format

Returns

list of contact groups similar or the same as kwd or return codes

Query

Query server for useful information such as user's data, user's credit, last smslog_id for inbox, incoming and outgoing SMS

Parameters

Name or description

Operation

query

Mandatory

u h

Optional

format

Returns

server's information

 

Examples

Send SMS

Example webservice URL:

http://infopi.io/text/index.php?app=ws&u=<username>&h=<token>&op=pv&to=0987654321&msg=test+only

Explanation

operation op pv (send SMS) was accessed by a user using username u and webservices token h with destination number to 0987654321, message msg 'test only' and expected output format is the default format, JSON format.

When successful InfoPi will returns OK status message in JSON format:

{"data":[{"status":"OK","error":"0","smslog_id":"30","queue":"afb5f34575e30ec4efe4471cf5d1bee4","to":"0987654321"}],"error_string":null}

If error occurred Infopi returns one of the return code, also in JSON format.

List of incoming SMS

Example webservice URL:

http://infopi.io/text/index.php?app=ws&u=<username>&h=<token>&op=in&kwd=school&format=xml

Explanation:

InfoPi webservices in infopi.io with operation op in (incoming SMS) was accessed by a user using username u and webservices token h with keyword kwd school and expected output format is in XML format format=xml.

When successful InfoPi will return OK status message in XML format:

<response>   

                     <data>       

                                  <item>           

                                              <id>2</id>           

                                              <src>+254987654321</src>           

                                              <dst>1234</dst>           

                                              <kwd>school</kwd>           

                                              <msg>A</msg>           

                                              <dt>2013-05-20 12:40:38</dt>           

                                              <status>1</status>       

                                </item>   

                   </data>

</response>

If error occurrs InfoPi will return one of the error codes, also in XML format.

List of Contacts on Phonebook

Example webservice URL:

http://infopi.io/text/index.php?app=ws&u=<username>&h=<token>&op=get_contact&kwd=james

Explanation:

Infopi webservices in infopi.io with operation op get_contact was accessed by a user using username u and webservices token h with keyword kwd james and expected output format is in JSON format.

When successful InfoPi will return OK status message in JSON format:

{"status":"OK","error":"0","data":[{"pid":"1234","gpid":"2","p_desc":"James Doe","p_num":"08901230659","email":"","group_name":"Test Group","code":"TESTGROUP"}],"multi":true}

If error occurred InfoPi will returns one of the return code, also in JSON format.