Product Guide

API Reference

Suggest Edits

API Endpoint

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

Supported methods

  • GET
  • POST

Request Headers

Content-Typeapplication/x-www-form-urlencoded

Request Body

KeyDescriptionExample
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 useridsh1gw4e
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:

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

Updated almost 3 years ago