Overview

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.

Currently, SMS delivery is limited to Indian mobile phones.

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.

API Methods

Public stream

GupShup.getPublicStream

Groups

GupShup.getPublicStream

Overview » GupShup.getPublicStream

Parameters / Description

At GupShup we recognize that privacy is important. This document outlines the types of personal information we receive and collect when you use Webaroo's services, as well as some of the steps we take to safeguard information. We hope this will help you make an informed decision about sharing personal information with us.

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 10.
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)

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <list size="3">
        <item>
            <group>jumpy</group>
	    <icon>http://resource.smsgupshup.com/getimage?id=jumpy</icon>
            <message>hey! this message has been posted via API! </message>
            <picture/>
            <medium>api</medium>
            <timestamp>12/26/2007 17:53:58 IST</timestamp>
        </item>
        <item>
            <group>dobby</group>
	    <icon>http://resource.smsgupshup.com/getimage?id=dobby</icon>
            <message>hello a message from dobby</message>
            <picture/>
            <medium>website</medium>
            <timestamp>12/24/2007 18:21:43 IST</timestamp>
        </item>
        <item>
            <group>winky</group>
	    <icon>http://resource.smsgupshup.com/getimage?id=winky</icon>
            <message>hello a message from winky</message>
            <picture/>
            <medium>website</medium>
            <timestamp>12/24/2007 18:21:35 IST</timestamp>
        </item>
    </list>
</response>

Sample Response (JSON)

{"response": {"list": {
    "@size": "3",
    "item": [
        {
            "group": {"$": "jumpy"},
	    "icon": {"$":"http://resource.smsgupshup.com/getimage?id=jumpy"},
            "message": {"$": "hey! this message has been posted via API!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/26\/2007 17:53:58 IST"}
        },
        {
            "group": {"$": "dobby"},
	    "icon": {"$":"http://resource.smsgupshup.com/getimage?id=dobby"},
            "message": {"$": "hello a message from dobby"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 18:21:43 IST"}
        },
        {
            "group": {"$": "winky"},
	    "icon": {"$":"http://resource.smsgupshup.com/getimage?id=winky"},
            "message": {"$": "hello a message from winky"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 18:21:35 IST"}
        }
    ]
}}}

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)

<response>
    <error>
        <id>109</id>
            <msg>
                The parameter "group" is required. Please resend request.
            </msg>
    </error>
</response>

Sample Error Response (JSON)

{"response":{
    "error":{
    "id":{"$":"109"},
    "msg":{"$":"The parameter \"group\" is required. Please resend request."}
}}}

groups.getMessage

Overview » 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)

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item group="jumpy" icon="http://resource.smsgupshup.com/getimage?id=jumpy">
        <message>hey! this message has been posted via API! </message>
        <picture/>
        <medium>api</medium>
        <timestamp>12/26/2007 17:53:58 IST</timestamp>
    </item>
</response>

Sample Response (JSON)

{"response": {"item": {
    "@group": "jumpy",
    "@icon": "http://resource.smsgupshup.com/getimage?id=jumpy",
    "message": {"$": "hey! this message has been posted via API!"},
    "picture": {"$": ""},
    "medium": {"$": "api"},
    "timestamp": {"$": "12\/26\/2007 17:53:58 IST"}
}}}

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)

<response>
    <error>
        <id>109</id>
            <msg>
                The parameter "group" is required. Please resend request.
            </msg>
    </error>
</response>

Sample Error Response (JSON)

{"response":{
    "error":{
    "id":{"$":"109"},
    "msg":{"$":"The parameter \"group\" is required. Please resend request."}
}}}

groups.getStream

Overview » 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 10.

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)

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <list group="jumpy" icon="http://resource.smsgupshup.com/getimage?id=jumpy" size="10">
   <item>
     <message>hey! this message has been posted via API! </message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/26/2007 17:53:58 IST</timestamp>
   </item>
   <item>
     <message>this message has been posted via API! </message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/26/2007 17:50:10 IST</timestamp>
   </item>
   <item>
     <message>this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!</message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/26/2007 17:44:25 IST</timestamp>
   </item>
   <item>
     <message>hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API! </message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/26/2007 17:37:57 IST</timestamp>
   </item>
   <item>
     <message>hey!!! this message has been posted via API!! njoy!</message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/24/2007 18:11:59 IST</timestamp>
   </item>
   <item>
     <message>hey!!! this message has been posted via API!! enjoy!</message>
     <picture/>
     <medium>api</medium>
     <timestamp>12/24/2007 18:10:49 IST</timestamp>
   </item>
   <item>
     <message>hello ppl this is my fifth post!</message>
     <picture/>
     <medium>website</medium>
     <timestamp>12/24/2007 16:23:16 IST</timestamp>
   </item>
   <item>
     <message>hello ppl this is my fourth post!</message>
     <picture/>
     <medium>website</medium>
     <timestamp>12/24/2007 16:23:11 IST</timestamp>
   </item>
   <item>
     <message>hello ppl this is my third post!</message>
     <picture/>
     <medium>website</medium>
     <timestamp>12/24/2007 16:23:06 IST</timestamp>
   </item>
   <item>
     <message>hello ppl this is my second post!</message>
     <picture/>
     <medium>website</medium>
     <timestamp>12/24/2007 16:23:00 IST</timestamp>
   </item>
   </list>
</response>

Sample Response (JSON)

{"response": {"list": {
    "@group": "jumpy",
    "@icon": "http://resource.smsgupshup.com/getimage?id=jumpy",
    "@size": "10",
    "item": [
        {
            "message": {"$": "hey! this message has been posted via API!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/26\/2007 17:53:58 IST"}
        },
        {
            "message": {"$": "this message has been posted via API!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/26\/2007 17:50:10 IST"}
        },
        {
            "message": {"$": "this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/26\/2007 17:44:25 IST"}
        },
        {
            "message": {"$": "hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!! hey!!! this message has been posted via API!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/26\/2007 17:37:57 IST"}
        },
        {
            "message": {"$": "hey!!! this message has been postedededed via API!! njoy!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/24\/2007 18:11:59 IST"}
        },
        {
            "message": {"$": "hey!!! this message has been posted via API!! njoy!"},
            "picture": {"$": ""},
            "medium": {"$": "api"},
            "timestamp": {"$": "12\/24\/2007 18:10:49 IST"}
        },
        {
            "message": {"$": "hello ppl this is my fifth post!"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 16:23:16 IST"}
        },
        {
            "message": {"$": "hello ppl this is my fourth post!"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 16:23:11 IST"}
        },
        {
            "message": {"$": "hello ppl this is my third post!"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 16:23:06 IST"}
        },
        {
            "message": {"$": "hello ppl this is my second post!"},
            "picture": {"$": ""},
            "medium": {"$": "website"},
            "timestamp": {"$": "12\/24\/2007 16:23:00 IST"}
        }
    ]
}}}

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)

<response>
    <error>
        <id>109</id>
            <msg>
                The parameter "group" is required. Please resend request.
            </msg>
    </error>
</response>

Sample Error Response (JSON)

{"response":{
    "error":{
    "id":{"$":"109"},
    "msg":{"$":"The parameter \"group\" is required. Please resend request."}
}}}

groups.getInfo

Overview » 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)

<response>
    <item group="jumpy" icon="http://resource.smsgupshup.com/getimage?id=jumpy">
        <id>5</id>
        <owner>6</owner>
        <posts>10</posts>
        <subscribers>1</subscribers>
        <description />
    </item>
</response>

Sample Response (JSON)

{"response": {"item": {
 "@group": "jumpy",
 "@icon":"http://resource.smsgupshup.com/getimage?id=jumpy",
 "id": {"$": "5"},
 "owner": {"$": "6"},
 "posts": {"$": "10"},
 "subscribers": {"$": "1"},
 "description": {"$": ""}
}}}

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)

<response>
    <error>
        <id>109</id>
            <msg>
                The parameter "group" is required. Please resend request.
            </msg>
    </error>
</response>

Sample Error Response (JSON)

{"response":{
    "error":{
    "id":{"$":"109"},
    "msg":{"$":"The parameter \"group\" is required. Please resend request."}
}}}

groups.subscribeGroupToken

Overview » groups.subcribeGroupToken

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)

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <token>85aa39fbcf69e44ff603a2e2391f1b22</token>
</response>

Sample Response - Phase I (JSON)

{"response": {"token": {"$": "85aa39fbcf69e44ff603a2e2391f1b22"}}}

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)

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <success>0</success>
</response>

Sample Response - Phase II (JSON)

{"response": {"success": {"$": "0"}}}

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)

<response>
    <error>
        <id>109</id>
            <msg>
                The parameter "group" is required. Please resend request.
            </msg>
    </error>
</response>

Sample Error Response (JSON)

{"response":{
    "error":{
    "id":{"$":"109"},
    "msg":{"$":"The parameter \"group\" is required. Please resend request."}
}}}

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)

<response>
    <item group="jumpy" icon="http://resource.smsgupshup.com/getimage?id=jumpy">
        <id>26</id>
        <owner>27</owner>
        <posts>3</posts>
        <subscribers>0</subscribers>
        <description />
    </item>
    <throttle type="per minute">
        <current>25</current>
        <maximum>30</maximum>
    </throttle>
</response>

Sample Throttle Response (JSON)

{"response": {
    "item": {
        "@group": "jumpy",
        "@icon": "http:\/\/resource.smsgupshup.com\/getimage?id=jumpy",
        "id": {"$": "26"},
        "owner": {"$": "27"},
        "posts": {"$": "3"},
        "subscribers": {"$": "0"},
        "description": {"$": ""}
    },
    "throttle": {
        "@type": "per minute",
        "current": {"$": "25"},
        "maximum": {"$": "30"}
    }
}}

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

Sample Throttle Response (XML)

<response>
    <error>
        <id>113</id>
        <msg>The API call has not been executed since you have exceeded the throttle per minute limit of "10".</msg>
    </error>
</response>

Sample Throttle Response (JSON)

{"response": {"error": {
    "id": {"$": "113"},
    "msg": {"$": "The API call has not been executed since you have exceeded the throttle per minute limit of \"10\"."}
}}}

API Call

Overview

API Methods

GupShup.getPublicStream

Parameters / Description

Sample Request

Sample Response (XML)

Sample Response (JSON)

Error Codes

Sample Error Response (XML)

Sample Error Response (JSON)

groups.getMessage

Parameters / Description

Sample Request

Sample Response (XML)

Sample Response (JSON)

Error Codes

Sample Error Response (XML)

Sample Error Response (JSON)

groups.getStream

Parameters / Description

Sample Request

Sample Response (XML)

Sample Response (JSON)

Error Codes

Sample Error Response (XML)

Sample Error Response (JSON)

groups.getInfo

Parameters / Description

Sample Request

Sample Response (XML)

Sample Response (JSON)

Error Codes

Sample Error Response (XML)

Sample Error Response (JSON)

groups.subscribeGroupToken

Parameters / Description

Sample Request - Phase I

Sample Response - Phase I (XML)

Sample Response - Phase I (JSON)

Sample Request - Phase II

Sample Response - Phase II (XML)

Sample Response - Phase II (JSON)

Error Codes

Sample Error Response (XML)

Sample Error Response (JSON)

API Throttling

Description

Sample Throttle Response (XML)

Sample Throttle Response (JSON)

Sample Throttle Response (XML)

Sample Throttle Response (JSON)

Featured Widgets

Widget for your GupShup group

Customize Widget

Contact Us