API Reference

API Endpoint


https://media.smsgupshup.com/GatewayAPI/rest

Supported methods

GET
POST

Request Headers


Content-Type	application/x-www-form-urlencoded

Request Body

Key	Description	Example
userid REQUIRED \| string	The userid of your Gupshup account. The number must be in pure numeric format with no special Characters.	2000155005
password REQUIRED \| string	The password of your Gupshup account for authentication of the userid	sh1gw4e
phone_number REQUIRED \| string	The phone number of the user who has provided explicit consent to the business to receive notifications on WhatsApp. Number must be in E.164 format.	91989212345
method REQUIRED \| string	The API method to perform a specific action i.e. mark the phone number as Opt-in user Must be: OPT_IN	OPT_IN
auth_scheme REQUIRED \| string	The authentication scheme of the API. Must be: plain	plain
v REQUIRED \| string	The API version. Must be: 1.1	1.1
channel REQUIRED \| string	The channel for which user has provided his consent to be contacted by the business Must be: WHATSAPP	WHATSAPP
format OPTIONAL \| string	The API response message format. Default value is text, unless otherwise specified. Must be one of: text, json, xml	json

Sample Requests

Simple request
Below is a sample GET request to mark a user as Opt-In:

https://media.smsgupshup.com/GatewayAPI/rest?method=OPT_IN&format=json&userid=2000XXXXXX&password
=XXXXXXXX&phone_number=919777777778&v=1.1&auth_scheme=plain&channel=WHATSAPP

Encrypted request

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64_Encoded_Encrypted_ Data}}
where value of encrdata={{method=OPT_IN&format=json&password=XXXXXXXX&phone_number=919777777778&v=1.1&auth_sc heme=plain&channel=WHATSAPP}}

The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the Key shared, in the “encrdata” parameter.
You must use the key generated for your enterprise account to encrypt API parameter values when sending the API request. Once the request is received by Gupshup, the payload is decrypted by Gupshup and sent ahead to WhatsApp.

API Response

A successful API request generates an HTTP 200 response. The response to a request where output format was specified as json, is a JSON array with response status, unique identifier and method as OPT_IN.

{
"response": {
"id": "3795200898494416206",
"phone": "",
"details": "OPT_IN", "status": "success"
},
"data": {
"response_messages": [
{
"id": "3795200898494416206",
"phone": "919777777778",
"details": "OPT_IN", "status": "success"
}
]
}
}

This indicates that the mobile number 919777777778 has been successfully opted in under a Unique
Identifier ‘3795200898494416206’. The identifier string is unique for each recipient number and is auto generated at the time of opt-in submission.

API Errors

An error response is generated when any of the required parameters is not specified correctly or any other technical error exists. The error response will indicate an error code along with the actual error message.
typical error response is:

{
"response": {
"id": "105",
"phone": "",
"details": "The phone number \"666\" is not a valid phone number", "status": "error"
}
}

Below is the list of API failure or errors in case request is badly formed or parameters are missing:


100	An unknown exception has occurred. Please retry the request after some time.
101	The parameter X is required. Please resend request.
102	Authentication failed due to invalid userId or password.
103	Authentication Failed as userid X does not exist.
105	The phone number XXXXX is not a valid phone number.
106	The method is not supported.
175	The "INTERNATIONAL_PHONE" service is disabled for you. Kindly get the service enabled before using this action
312	You are already opted In.

Updated about 2 months ago