Quick Replies

cURL

curl --location 'https://api.gupshup.io/wa/api/v1/msg' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: {{APIKEY}}' \
--data-urlencode 'source={{SOURCE}}' \
--data-urlencode 'destination={{DESTINATION}}' \
--data-urlencode 'message={
	"type":"quick_reply",
	"msgid":"{{POSTBACK_TRACKING_ID}}",
	"content":{
		"type":"{{QUICK_REPLY_TYPE}}",
		"text":"{{BODY_CONTENT}}",
		"url":"{{HEADER_MEDIA_URL}}",
		"caption":"{{FOOTER}}",
		"header":"{{HEADER_TEXT}}",
		"filename":"{{FILE_NAME}}"
	},
	"options":[
		{
			"title":"{{BUTTON_TITLE}}",
			"postbackText":"{{POSTBACK_TRACKING_TEXT}}",
		}
	]
}' \
--data-urlencode 'src.name={{APP_NAME}}'

Sample Requests- Quick Replies

curl --location 'https://api.gupshup.io/wa/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: xvnwgh9vgbbl6gjeezymu5v5iepxq2zt' \
--header 'cache-control: no-cache' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=918097424541' \
--data-urlencode 'destination=91735824xxxx' \
--data-urlencode 'message={
	"type":"quick_reply",
	"content":{
		"type":"text",
		"text":"body",
		"caption":"footer",
		"header":"header"
	},
	"options":[
		{
			"title":"button title 1",
			"postbackText":"tracking text"
		}
	]
}' \
--data-urlencode 'src.name=TedLasso'

curl --location 'https://api.gupshup.io/wa/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: xvnwgh9vgbbl6gjeezymu5v5iepxq2zt' \
--header 'cache-control: no-cache' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=918097424541' \
--data-urlencode 'destination=91735824xxxx' \
--data-urlencode 'message={
	"type":"quick_reply",
	"content":{
		"type":"file",
		"text":"body",
		"caption":"footer",
		"url":"https://www.clickdimensions.com/links/TestPDFfile.pdf",
		"filename":"sample"
	},
	"options":[
		{
			"title":"button title 1",
			"postbackText":"tracking text"
		}
	]
}' \
--data-urlencode 'src.name=TedLasso'

curl --location 'https://api.gupshup.io/wa/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: xvnwgh9vgbbl6gjeezymu5v5iepxq2zt' \
--header 'cache-control: no-cache' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=918097424541' \
--data-urlencode 'destination=91735824xxxx' \
--data-urlencode 'message={
	"type":"quick_reply",
	"content":{
		"type":"image",
		"text":"body",
		"caption":"footer",
		"url":"https://picsum.photos/200"
	},
	"options":[
		{
			"title":"button title 1",
			"postbackText":"tracking text"
		}
	]
}' \
--data-urlencode 'src.name=TedLasso'

curl --location 'https://api.gupshup.io/wa/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: xvnwgh9vgbbl6gjeezymu5v5iepxq2zt' \
--header 'cache-control: no-cache' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=918097424541' \
--data-urlencode 'destination=91735824xxxx' \
--data-urlencode 'message={
	"type":"quick_reply",
	"content":{
		"type":"video",
		"text":"body",
		"caption":"footer",
		"url":"https://file-examples.com/storage/fe3cb26995666504a8d6180/2017/04/file_example_MP4_480_1_5MG.mp4"
	},
	"options":[
		{
			"title":"button title 1",
			"postbackText":"tracking text"
		}
	]
}' \
--data-urlencode 'src.name=TedLasso'

Header Parameters

Parameter	Type	Required	Description	Example
`apikey`	string	Yes	API key for Gupshup account	`61b3021c97214370b341f8baaae0xxxx`

Body Parameters

Parameter	Type	Required	Description	Example
`source`	integer	Yes	Source phone number	`918XXXX4278`
`destination`	integer	Yes	Destination phone number	`918XXXX2043`
`src.name`	string	Yes	App name	`august18`
`message`	object	Yes	Message details (see below)

Message Object

The message object follows the schema below.

Field	Type	Required	Description	Example
`type`	string	Yes	Type of session message	`quick_reply`
`msgid`	string	No	Tracking ID for postback text	`QR123456789`
`content`	object	Yes	Content of the message	See content schema below
`options`	array	Yes	Quick reply options (up to 3)

Content Object

The content object contains the body and media of the message.

Field	Type	Required	Description	Example
`type`	string	Yes	Content type	`text`
`text`	string	Yes	Body of the message	`Hello from Gupshup Team`
`url`	string	No	URL of the media header	`https://example.com/file.jpg`
`caption`	string	No	Footer text	`Check this out!`
`filename`	string	No	Name of the file attached	`file.jpg`

Options (Quick Reply)

Each option in the options array allows users to respond with a pre-defined message.

Field	Type	Required	Description	Example
`title`	string	Yes	Title of the quick reply button	`Yes`
`postbackText`	string	No	Text sent back when the option is clicked	`User clicked Yes`

Responses

Success (200 OK)

On success, the API returns a status of submitted along with a unique messageId for tracking purposes.

Field	Type	Description	Example
`status`	string	Status of the message	`submitted`
`messageId`	string	ID of the sent message	`183dc8f1-xxxx4fxxx7`

Success Response

{
  "status": "submitted",
  "messageId": "183dc8xxxxxxxxxxxxb1bfe07"
}

Error Responses

400 Error

{
  "message": "Invalid Destination",
  "status": "error"
}

This response indicates invalid input, such as an incorrect phone number or app details.

Field	Type	Description	Example
`message`	string	Error message	`Invalid Destination`
`status`	string	Status of the error	`error`

401 Unauthorized

{
  "message": "Authentication Failed",
  "status": "error"
}

This response occurs when authentication fails due to an invalid API key.

Field	Type	Description	Example
`message`	string	Error message	`Authentication Failed`
`status`	string	Status of the error	`error`

429 Too Many Requests

{
  "message": "Too Many Requests",
  "status": "error"
}

This response indicates the rate limit has been exceeded.

Field	Type	Description	Example
`message`	string	Error message	`Too Many Requests`
`status`	string	Status of the error	`error`