InfoPi API Instructions on how to quickly integrate InfoPi messaging services into various solutions. Access Webservices URL: http://infopi.io/text/index.php?app=wsParameters 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=&h=&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=&h=&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:                                                                                                 2                                             +254987654321                                             1234                                             school                                             A                                            
2013-05-20 12:40:38
                                            1                                                 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=&h=&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.English User Guide How to register into the InfoPi System To register: Access the platform via infopi.io, text.co.ke or textkenya.com. Click on the  get started button. Click on register an account. Input the required details: your name, username, mobile number, email and the displayed captcha then click on submit. You will receive a welcome SMS that has the first login credentials from Medulla. Sample SMS: Alternatively, check your email to obtain the first login credentials. Sample email: You will be awarded 5 SMS credits for test purposes.How to login into the InfoPi system Access the platform via http://infopi.io/. If you are not registered in the platform, please register. Click on login. Input your username and password and click login. How to recover your password To recover your password: Access the platform via infopi.io. If you are not registered in the platform, please register. Click on login. Click on recover password. Input the required details: username, email and the displayed captcha then click submit. Check your email to obtain a temporary password. Sample email: Proceed to login. How to compose a message Login into the platform. On the main menu, click on messaging then compose message. Compose Message Write the desired message on the message text box. Note: The character limit per SMS is 160 characters but a message can be a concatenation of numerous SMSs. If the message has special characters such as ¶®|ĄÐ¾, the character limit per SMS is 70 characters. The message is referred to as a unicode message. Recipients The recipient can be: A group - To send the message to the group, type the character # followed by any character in the group name and select the desired group. Subusers - To send the message to the subusers in your account, type the character @ followed by any character in the username of the subuser then select the desired subuser. A contact in the phonebook - To send the message to a contact in the phonebook, type a few characters of the contact's name then select the desired contact. A contact not saved in the phonebook - To send the message to a contact that has not been saved in the phonebook, type the phone number of the desired recipient. Sender ID The sender ID is set up by the administrator. Message Footer By default, the message footer is the username. However this can be changed to any value or be left blank. The footer is usually appended at the end of the message. Send You can schedule the message or click the button send to send the message immediately. How to schedule a message Compose the desired message. Click on the calendar icon  and set the date and time you wish to have the message sent. Click send. Note: The message will remain in the queue until the scheduled time. How to access the Contacts List Login into the platform. On the main menu, click on my account then Contacts List. The contacts of InfoPi's support team appear on the Contacts List by default. How to create a group of contacts Access the Contacts List. Click on the icon to land on a similar page as shown below. Click on the icon. Input the required details: a suitable group name and group code. Set the broadcasting permissions the. There are 3 broadcasting permissions' setting options: Me only - Only the creator of the group has access to the contacts in the group and can send a broadcast message to the group members. Members - The creator of the group and his / her subusers can send a broadcast message to the group members. Anyone - The group is public. Click on save. How to add a contact to the Contacts List Access the Contacts List. Click on the add  button. If you wish to save the contact in a particular group, select the desired group in the group selection panel. If you haven't created any group and you wish to group your contacts, create a group. Input the required details: name, mobile number, email and tags. Note: Name and mobile number are mandatory fields. Click on save. How to add multiple contacts to the Contacts List Access the Contacts List. Click on the import  button. Prepare an excel file with  the contacts arranged in the order: name, mobile number, email, group code and tags as in the example below. Note: Name and mobile number are mandatory. Save the excel file in the csv format, for example, contacts.csv. Choose the saved file and click import. Click import to confirm the importation. How to send a message from an external file Login into the platform. On the main menu, click on messaging then send from file. Prepare an excel file of the messages to be sent in the order: contact, message as in the example below: Save the file in csv format, for example, message.csv. Select the saved file. To avoid sending duplicate messages to the same person, tick the prevent duplicates option then click upload file. Click send SMS to valid entries for confirmation. How to access message templates Login into the platform. On the main menu, click on messaging then message template. How to create a message template Access the message template page. Click on the icon. Input the template name and compose the template content. Note: #NAME# will be replaced with the recipient's name listed in phonebook #NUM# will be replaced with the recipient's phone number listed in phonebook Click on save. How to compose a message using a template Create the message template. Compose your message, however, rather than typing your message directly in the text box, select the template you created. Click send once you have filled all required fields. How to Access the Profile Management Page Login into the platform. On the main navigation menu, click on my account then preferences. How to Update your Password Access the profile management page. Type your preferred password on the space provided and retype it in the field that follows. Scroll down and click save to save the changes.How to update the user profile Access your profile. Input or change the details you wish to update such as name, emailand phone number, or contact details like address, city, state or province, country and zipcode. Note: The profile must have a name and an email. Click save to effect the changes. How to view the status of sent messages Login into the platform. How to view Incoming Messages One can receive messages through a shortcode such as "23456" or via USSD such as " *789# ". After the shortcode or USSD has been configured, one receives their incoming messages through their InfoPi accounts. To view the incoming messages, login into your account. On the main menu, click on messaging then inbox. The incoming messages are listed as below: Click the icon  to reply to the message and the icon  to forward the message. How to purchase SMS credits via Mpesa To purchase credits via Mpesa: Login into your account. On the main menu, click on buy credits then buy now. Click on the Mpesa payment option. On your phone: Go to your mpesa menu Click on Lipa na M-PESA Click on Buy Goods and Services Enter the till number: 573746 Enter the desired amount Input your PIN and confirm the transaction Input the transaction code as illustrated below and click on add credit. A summary of all transactions will be displayed. How to Access Sent Messages Login into the platform. On the main menu, click messaging then sent messages. The sent messages appear as below: Delivery Status:  The message has been sent and delivered.  The message has been sent and acknowledged by the destination network but not delivered. The message has been sent but has not yet been acknowledged by the destination network.  The message has failed either due to: An incorrect format of the recipient's number The recipient's number is restricted or blacklisted The length of message exceeds the permissible characters The message has been pending for more than 24 hours (The duration varies depending on the network) How to Delete Messages Access the message(s) you wish to delete, be it inbox messages or sent messages. Tick the check box against the message you wish to delete. Click to delete the message. How to add multiple contacts to a group Add all contacts to the contact list either singularly or in multiples. Ensure the group has already been created. Select the contacts to be added to the group as illustrated below: Click the select drop down menu to select the group at the top right corner. Click the icon to effect the change. How to delete Contacts Access the contacts list. Select the contacts to be deleted as illustrated below: Click the select drop down menu to select the delete option at the top right corner. Click the icon to effect the change.How to edit a contact Access the contacts list. Click on the name of the contact you wish to edit. Update the details. Click save to effect the changes. How to Access Application Settings Login into the platform. On the main menu, click on my account then Application Settings. How to Change the Message Footer Access the application settings. The default message footer is the username of your account therefore to change it, clear it and replace it with your desired footer. How to Access WebServices Settings Access application settings. The webservices settings are as illustrated below: You can adjust the settings to suit the needs of your application.How to Change the Language Settings Access the application settings. Français mode d'emploi