Home Groups Chat Apps Shop Press MyGupShup Communities
Join Now | Log In
 

GupShup Stream and Group APIs
Take GupShup to places

GupShup API enables developers to build SMS-based widgets and services. Using GupShup API, developers can build a variety of widgets and services that advertise their GupShup group messages on their website or blog, and post messages to their group through their favorite website.

GupShup API uses a REST-based interface. All requests are made as HTTP GET and POST requests. The REST response is either a XML or a JSON block.

  

Featured widget

 Customize Widget
Enter Group Name:
This group doesn't exist or its a private group.
Choose Color:
Embed Code:
 
 
API Methods

Public Stream

Groups Stream

  • Groups.getMessage  : This API method fetches the last posted message of a particular group.
  • Groups.getStream : Fetches the recent messages from the specified group, you can specify the number of messages you to fetch.
  • Groups.getInfo : This method fetches details about a given group. For example: number of posts made, group description etc.
  • Groups.subscribeGroupToken :  This method helps to subscribe a phone number to the particular group. This is a 2 phase registration process.

User and post APIs

In order to prevent DOS attacks, we are currently throttling the number on requests from a particular IP address to these throttle limites.

GupShup.getPublicStream

Parameters / Description

Parameter Required/Optional Description
v required This string should be set to 1.0 for this version of the API.
method required Get public stream from GupShup. Must be gupshup.getPublicStream.
from optional Starting message position from GupShup stream. Default is 0.
format optional Supported output format. Either XML (default) or JSON.
range optional Maximum number of items to fetch. Default is 15.
skipAdult optional Skip adult content from the GupShup stream. Either TRUE (default) or FALSE.

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?skipadult=false&from=0&range=10 &method=gupshup.getPublicStream&v=1.0&format=xml

Sample Response (XML)

Sample Response (JSON)

Error Codes

errorCode errorString
1 The specified range is invalid. Range can be a positive integer with maximum value of 15.
102 The specified response format "%0" is not supported.
107 The specified version "%0" is invalid. Please specify version as "1.0" or leave the field blank.
108 The specified method "%0" is not valid GupShup api.
109 The parameter "%0" is required. Please resend request.
110 The parameter "%0" is invalid. The parameter should be of type "%1".
111 The parameter "%0" is invalid. The parameter should be within a value of "%1".
113 The API call has not been executed since you have exceeded the throttle %0 limit of "%1".

Sample Error Response (XML)

Sample Error Response (JSON)

Groups.getMessage

Parameters / Description

Parameter Required/Optional Description
v required This string should be set to 1.0 for this version of the API.
method required Get latest message sent to a group. Must be groups.getMessage.
group required Name of the group.
format optional Supported output format. Either XML (default) or JSON.

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?group=jumpy&method=groups .getMessage&v=1.0&format=xml

Sample Response (XML)

Sample Response (JSON)

Error Codes

errorCode errorString
2 The specified group name is invalid.
102 The specified response format "%0" is not supported.
107 The specified version "%0" is invalid. Please specify version as "1.0" or leave the field blank.
108 The specified method "%0" is not valid GupShup api.
109 The parameter "%0" is required. Please resend request.
113 The API call has not been executed since you have exceeded the throttle %0 limit of "%1".

Sample Error Response (XML)

Sample Error Response (JSON)

Groups.getStream

Parameters / Description

Parameter Required/Optional Description
v required This string should be set to 1.0 for this version of the API.
method required Get recent message stream of a group. Must be groups.getStream.
group required Name of the group.
format optional Supported output format. Either XML (default) or JSON.
from optional Starting message position from GupShup stream. Default is 0.
range optional Maximum number of items to fetch. Default is 15.

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?group=jumpy&from=0&range=10 &method=groups.getStream&v=1.0&format=xml

Sample Response (XML)

Sample Response (JSON)

Error Codes

errorCode errorString
2 The specified group name is invalid.
3 The specified range is invalid. Range can be a positive integer with maximum value of 15.
102 The specified response format "%0" is not supported.
107 The specified version "%0" is invalid. Please specify version as "1.0" or leave the field blank.
108 The specified method "%0" is not valid GupShup api.
109 The parameter "%0" is required. Please resend request.
110 The parameter "%0" is invalid. The parameter should be of type "%1".
111 The parameter "%0" is invalid. The parameter should be within a value of "%1".
112 You are trying to access a private group. The method \"%0\" is only supported for public groups.
113 The API call has not been executed since you have exceeded the throttle %0 limit of "%1".

Sample Error Response (XML)

Sample Error Response (JSON)

Groups.getInfo

Parameters / Description

Parameter Required/Optional Description
v required This string should be set to 1.0 for this version of the API.
method required Get information about a group. Must be groups.getInfo.
group required Name of the group.
format optional Supported output format. Either XML (default) or JSON.

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?group=jumpy&method=groups.getInfo &v=1.0&format=xml

Sample Response (XML)

Sample Response (JSON)

Error Codes

errorCode errorString
2 The specified group name is invalid.
102 The specified response format "%0" is not supported.
107 The specified version "%0" is invalid. Please specify version as "1.0" or leave the field blank.
108 The specified method "%0" is not valid GupShup api.
109 The parameter "%0" is required. Please resend request.
112 You are trying to access a private group. The method \"%0\" is only supported for public groups.
113 The API call has not been executed since you have exceeded the throttle %0 limit of "%1".

Sample Error Response (XML)

Sample Error Response (JSON)

Groups.subscribeGroupToken

Parameters / Description

Parameter Required/Optional Description
v required This string should be set to 1.0 for this version of the API.
method required Subscribe user to a group. Must be groups.subscribeToken.
group required in phase II Name of the group.
phone required Phone number of the user.
token required in phase II  
confirm required in phase II A 4 digit alpha numeric string that is sent to user's phone.
format optional Supported output format. Either XML (default) or JSON.

Sample Request - Phase I

http://api.smsgupshup.com/GupshupAPI/rest?phone=9819535746&group=jumpy &method=groups.subscribeGroupToken&v=1.0&format=xml

Sample Response - Phase I (XML)

Sample Response - Phase I (JSON)

Sample Request - Phase II

http://api.smsgupshup.com/GupshupAPI/rest?phone=9819535746&group=jumpy &confirm=UY9Z&token=85aa39fbcf69e44ff603a2e2391f1b22&method= groups.subscribeGroupToken&v=1.0&format=xml

Sample Response - Phase II (XML)

Sample Response - Phase II (JSON)

Error Codes

errorCode errorString
1 The specified group name is invalid.
2 The specified phone number is invalid.
3 Due to privacy policy of the parties involved the current action is deemed invalid.
5 The specified phone number has 5 unconfirmed actions. All actions to %0 have now been disabled pending further confirmation.
6 The token string specified is invalid.
7 The confirmation string specified is invalid.
8 The user "%0" has already subscribed to group "%1".
9 There have been more that 5 attempts. This action has now been disabled.
10 Subscription action is only supported for public groups.
102 The specified response format "%0" is not supported.
107 The specified version "%0" is invalid. Please specify version as "1.0" or leave the field blank.
108 The specified method "%0" is not valid GupShup api.
109 The parameter "%0" is required. Please resend request.
110 The parameter "%0" is invalid. The parameter should be of type "%1".
111 The parameter "%0" is invalid. The parameter should be within a value of "%1".
113 The API call has not been executed since you have exceeded the throttle %0 limit of "%1".

Sample Error Response (XML)

Sample Error Response (JSON)

API Throttling

Description

In order to prevent Denial Of Service attacks, we are currently throttling the number on requests from a particular IP address to the following limits.

Throttle timing Throttle Warn Value Throttle Limit Value
per Minute 25 30
per Hour 990 1000
per Day 9990 10000

A throttle tag is appended with the response once a throttle warn limit is reached.

Sample Throttle Response (XML)

Sample Throttle Response (JSON)

The following error response will be returned once the throttling limit is reached.

Sample Throttle Error Response (XML)

Sample Throttle Error Response (JSON)

Challenge

Parameters / Description

Parameters Required/Optional Description
method required users.getChallenge. Get the salt and challenge to be used to encrypt password.
format optional Supported output format. Either JSON (default) or XML.
v required 1.0

Sample Request
http://api.smsgupshup.com/GupshupAPI/rest?method=users.getChallenge&v=1.0

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
129 There was an internal error and your last action could not be performed. Please resubmit your last action after some time.
108 The method is not a valid GupShup API

Sample Error Response (JSON)

Sample Error Response (XML)

Login

Parameters / Description

Parameters Required/Optional Description
method required users.login
format optional Supported output format. Either JSON (default) or XML
phone required 10-digit mobile number
countryCode required 91 (for India)
challenge required Challenge received from previous request
rand required Encrypted password [md5(md5(plainTextPwd+salt)+challenge)]
v required 1.0

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?phone=9821107770&rand=%
2BMfd9oadhBIrXHU3edNQIg%3D%3D&countryCode=91&challenge=BXuQQ2056310911
&method=users.login&v=1.0

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
108 The method is not a valid GupShup API
129 There was an internal error and your last action could not be performed. Please resubmit your last action after some time.
109 91 (for India)
109 You have not provided the parameter "phone number", which is a required parameter. Please resend request with the parameter in place.
109 You have not provided the parameter "country code", which is a required parameter. Please resend request with the parameter in place.
120 You have provided an invalid value for the parameter "country code". Please resend request with the correct value of the parameter.
2 You have provided an invalid value for the parameter "phone". Please resend request with the correct value of the parameter.
121 Authentication unsuccessful. This is possibly because of an incorrect password.
122 The mobile phone number provided has not been activated yet. Please visit http://www.smsgupshup.com to activate the mobile phone.
123 The mobile phone number provided has been disabled. Please email 'support@smsgupshup.com' to reactivate the mobile phone.

Sample Error Response (JSON)

Sample Error Response (XML)

Group Post

Parameters / Description

Parameters Required/Optional Description
method required groups.postMessage
format optional Supported output format. Either JSON (default) or XML.
token required Token obtained using users.login api
groupName required name of the group
text required message to post on the group
v required 1.0

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?text=Test+Post&token=IIQiU1107028137
&groupName=APICreated&method=groups.postMessage&v=1.0

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
108 The method is not a valid GupShup API
6 The token string specified is invalid.
129 There was an internal error and your last action could not be performed. Please resubmit your last action after some time.
1 You have provided an invalid value for the parameter "group". Please resend request with the correct value of the parameter.
124 This SMS GupShup group has been disabled. Please email 'support@smsgupshup.com' to re-enable the group.
125 This message contains non-ASCII characters. Please remove those and resubmit the message.
126 This message exceeds the permitted length of %<ml> characters. Please reduce the length of the message to within allowed limits and resubmit.
127 You have hit a throttle limit. Please see other accompanying messages for details.
128 The last message you submitted is a duplicate of your earlier message. You cannot send duplicate messages.

Sample Error Response (JSON)

Sample Error Response (XML)

My Groups

Parameters / Description

Parameters Required/Optional Description
method required users.getMyGroups
format optional Supported output format. Either JSON (default) or XML.
token required Token obtained using users.login api
v required 1.0
from optional Starting position. Default is 0.
range optional Maximum number of items to fetch. Default is 15.

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?token=IIQiU1107028137
&method=users.getMyGroups&v=1.0

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
108 The method is not a valid GupShup API.
6 The token string specified is not valid.
129 There was an internal error and your last action could not be performed. Please resubmit your last action after some time.
107 You have provided an invalid value for the parameter "version". Please specify version as "1.0" or leave the field blank.

Sample Error Response (JSON)

Sample Error Response (XML)

Logout

Parameters / Description

Parameters Required/Optional Description
method required users.logout
format optional Supported output format. Either JSON (default) or XML.
token required Token obtained using users.login api
v required 1.0

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?token=vmtzf757754542&method=users.logout&v=1.0

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
108 The method is not a valid GupShup API.
129 There was an internal error and your last action could not be performed. Please resubmit your last action after some time.
107 You have provided an invalid value for the parameter "version". Please specify version as "1.0" or leave the field blank.

Sample Response (JSON)

Sample Error Response (XML)

Users.getJoinedGroups

Parameters / Description

Parameters Required/Optional Description
format optional json/XML.
v required This string should be set to 1.0 for this version of the API.
method required Users.getJoinedGroups, to get the joined groups by a user
token required Obtained using Login api, needs to be passed if getAll is
true (if passed user should own the group)
from optional (number) start position, default is zero
range optional (number) number of items, default is 15s

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?
method=users.getJoinedGroups&v=1.0&format=XML&from=0&range=2&token=zt00e-639104101

Sample Response (JSON)

Sample Response (XML)

Errors

Error Code Description
1 The token string specified is invalid.
131 range parameter should be between 1 and 30.
150 from parameter should be 0 or positive integer
Users.getJoinedGroupsStream

Parameters / Description

Parameters Required/Optional Description
format optional json/XML.
v required This string should be set to 1.0 for this version of the API.
method required Users.getJoinedGroupsStream, to get the Stream of the goups joined by a user
token required Obtained using Login api, needs to be passed if getAll is
true (if passed user should own the group)
from optional (number) start position, default is zero
range optional (number) number of items, default is 15

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?
method=users.getJoinedGroupsStream&v=1.0&format=xml&from=0&range=1&token=VQvO4-1666345403

Sample Response

Sample Response (XML)

Errors

Error Code Description
1 The token string specified is invalid.
131 range parameter should be between 1 and 30.
150 from parameter should be 0 or positive integer
Groups.postReply

Parameters / Description

Parameter Required/Optional Description
Format Optional json/XML
v Required This string should be set to 1.0 for this version of the API.
method Required Reply to a group, must be groups.postReply.
token Required Obtained using Login api
groupName Optional grp name from which reply is posted, if unspecified then default group is assumed
text Required reply text, must contain @ followed by a valid group name (destination group)

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?v=1.0&method=groups.postReply&token=abcdDFE- 87Jk&groupName=groupone&text=@grouptwo this is a sample post using api

Sample Response

Sample Response (JSON):

Error Codes :

errorCode errorString
157 Its a partial success, for example if there are more than one group specified in the text (@ followed by grp names) and if some of the groups are invalid and
some are valid, then there will be corresponding custom message with ID as 157. This may arise in the following conditions:
1. Reciever throttle
2. Muted user
3. More number of groups specified in the text and only for some groups the message is delivered
4. Any privacy settings of the destination group (group specified in the text) which does not allow to post the message
156 The reply message can not be empty.
155 This group is private and only group owner can request this information.
1 You have provided an invalid value for group name parameter. Please resend request with the correct value of the parameter.
124 This SMS GupShup group has been disabled. Please email 'support@smsgupshup.com' to reenable the group.
125 This message contains non-ASCII characters. Please remove those and resubmit the message.
156 The reply message can not be empty
126 This message exceeds the permitted length of %s characters. Please reduce the length of the message to within allowed limits and resubmit.
Groups.getReplies

Parameters / Description

Parameter Required/Optional Description
Format Optional json/XML
v Required This string should be set to 1.0 for this version of the API.
method Required Get replies from a group, must be groups.getReplies
getAll Optional (true/false) get hidden replies (default is false)
token Optional Obtained using Login api, needs to be passed if getAll is true (if passed user should own the group)
groupName Required grp name whose replies are needed
from Optional (number) start position, default is zero
range Optional (number) number of items, default is 15

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?v=1.0&method=groups.getReplies&groupName=sriharigrp1

Sample Response(JSON)

Sample Response (XML):

Error Codes :

errorCode errorString
1 You have provided an invalid value for group name
parameter. Please resend request with the correct
value of the parameter.
153 The token string specified is invalid.
155 This group is private and only group owner can request this information.
154 Only group owner can request this information.
131 range parameter should be between 1 and %s.
150 from parameter should be 0 or positive integer
Groups.inviteFriends

Parameters / Description

Parameter Required/Optional Description
Format Optional json/XML
v Required This string should be set to 1.0 for this version of the API.
method Required Invite to a group, must be groups.inviteFriends
token Required Obtained using Login api
groupName Optional Group name for which invites are to be sent (if not present, default group will be used)
phoneNumbers Required Comma separated phone number list (Only Indian mobile numbers)

Sample Request

http://api.smsgupshup.com/GupshupAPI/rest?v=1.0&method=Groups.inviteFriends&token=abcdDFE-87Jk&groupName=group1&phoneNumbers=919191919191

Sample Response

Sample Response(JSON)

Error Codes :

errorCode errorString
163 It is a failure in the case when only one phone number is invited and it's processing is failed.
Message: Invite cannot be sent to your friends.
161 It is a failure case when one or more phone numbers are not valid.
Message: One or more phone numbers are not valid.
162 It is a part failure message. It is displayed when at least one phone number was successfully invited, but some other phones could not be.
Message: Invites have been sent to some of your friends. Some phone numbers could not be invited.
   
 

 

    
© 2009 Webaroo Technology (India) Private Limited. All Rights Reserved.