gupshup-whatsapp-api

v1.0.2

Published

3 years ago

An unofficial library to help with the usage of GupShup WhatsApp APIs(v2) for messages and user opt-ins

Downloads

374

0High
0Medium
0Low

ashwamegh

gupshup whatsapp-api messaging-api messaging whatsapp

Gupshup WhatsApp API

About

This is an unofficial library to leverage Gupshup Whatsapp API (v2) to be able to send Outbound messages of types (text, templates, video, audio, location, contact card, stickers, images) and fetch/send the opt-in requests to the users and the opted-in users list.

Note: It dooes not connect with the Inbound APIs (that are responsible for receiving messages from customers through webhooks)

Installation

npm i gupshup-whatsapp-api

yarn add gupshup-whatsapp-api

Basic Usage

You will be needed to create gupshup instance with provided apiKey. You can obtain the api key from Whatsapp Dashboard (https://www.gupshup.io/whatsapp/dashboard) for your specific app or if you are testing with the sandbox application.

const Gupshup = require('gupshup-whatsapp-api')

let client = new Gupshup({
	apiKey: 'YOUR_API_KEY'
});

Options

Request Body

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | channel | string | The channel name, i.e.whatsapp | true | | destination | string | Customer's Whatsapp number | true | | source | string | Your Whatsapp business number | true | | message | Message Payload | Payload for the sending message | true | | src.name | string | Your whatsapp application name | false (required for sandbox apps) |

Message Payload

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | isHSM | string | true (for template message) and false (for session message) | false | | type | string | Whatsapp message type( text, audio, video, file, image , location, contact, sticker) | true | | text | string | The text message to be sent to the customer, in case of type=text | false | | url | string | The public URL where the file / audio / video attachment to be sent to the customer is hosted | false | | originalUrl | string | The public URL where the image to be sent to the customer is hosted. Only to be sent for type = image | false | | previewUrl | string | The public URL where a thumbnail of the image to be sent to the customer is hosted. Only to be sent for type = image | false | | caption | string | Add caption to media messages, applicable to media type = image|video|file | false | | longitude | number | To be sent for type = location | false | | latitude | number | To be sent for type = location | false | | name | string | Name of the location. Only to be sent for type = location | false | | address | string | Postal address of the location. Only to be sent for type = location | false | | contact | Contact Card | Contact details to be sent when type = contact | false |

Contact Card

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | addresses | [Contact Address] | Contact address for the person | false | | birthday | string | Person's date of birth | true | | emails | [Contact Email] | Person's email or emails | true | | name | Contact Name | Person's first, last and formatted name | true | | org | Contact Organization | Person's organization details | true | | phones | [Contact Phone] | Person's contact phone numbers | true | | url | [Contact URL] | Person's contact URLs | true |

Contact Address

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | city | string | Eg: "Menlo Park" | true | | country | string | Eg: "United States" | true | | countryCode | string | Eg: "us" | true | | state | string | Eg: "CA" | true | | street | string | Eg: "1 Hacker Way" | true | | type | string | Eg: "HOME" | true | | zip | string | Eg: "94025" | true |

Contact Email

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | email | string | Eg: "[email protected]" | true | | type | string | Eg: "WORK" | true |

Contact Name

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | firstName | string | Eg: "John" | true | | formattedName | string | Eg: "John Smith" | true | | lastName | string | Eg: "Smith"| true |

Contact Organization

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | company | string | Eg: "WhatsApp" | true | | department | string | Eg: "Design" | true | | title | string | Eg: "Manager" | true |

Contact Phone

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | phone | string | Eg: "+1 (650) 555-1234" | true | | type | string | Eg: "WORK" | true | | wa_id | string | Eg: "16505551234" | false |

Contact URL

| Property | Type | Description | Required | | ------------- | ------------- | ----------- | -------- | | url | string | Eg: "https://www.facebook.com" | true | | type | string | Eg: "WORK" | true |

Supported Resources

Messages

1. Send Text Message

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		isHSM: "false",
		type: "text",
		text: "hi there"
	}
}).then((response) => {
	console.log("Text message sent", response)
}).catch(err => {
	console.log("Text message err:", err)
})

2. Send Template Message

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		isHSM: "true",
		type: "text",
		text: "Hi Ashwamegh, your order is confirmed and will be delivered to you by 15 Feb"
	}
}).then((response) => {
	console.log("Template text message sent", response)
}).catch(err => {
	console.log("Template text message err:", err)
})

3. Send Image as a Message

Supported Content-Types: image/jpeg, image/png
maximum file size: 5 MB

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "image",
		originalUrl: "https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
		previewUrl: "https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
		caption:"Sample image"
	}
}).then((response) => {
	console.log("Image message sent", response)
}).catch(err => {
	console.log("Image message err:", err)
})

4. Send Document/File as a Message

Supported Content-Types: Any valid MIME-type
maximum file size: 100 MB

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "file",
		url: "https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf",
		filename: "Sample file"
	}
}).then((response) => {
	console.log("Document message sent", response)
}).catch(err => {
	console.log("Document message err:", err)
})

5. Send Audio as a Message

Supported Content-Types: audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus. Note: The base audio/ogg type is not supported.
maximum file size: 16 MB

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "audio",
		url: "https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_700KB.mp3"
	}
}).then((response) => {
	console.log("Audio message sent", response)
}).catch(err => {
	console.log("Audio message err:", err)
})

6. Send Video as a Message

Supported Content-Types: video/mp4, video/3gpp. Note: Only H.264 video codec and AAC audio codec is supported.
maximum file size: 16 MB

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "video",
		url:"http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4",
		caption:"Sample video"
	}
}).then((response) => {
	console.log("Video message sent", response)
}).catch(err => {
	console.log("Video message err:", err)
})

6. Send Location as a Message

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "location",
		longitude: 43.43,
		latitude: 33.34,
		name: "Name of the location",
		address: "Postal address"
	}
}).then((response) => {
	console.log("Location message sent", response)
}).catch(err => {
	console.log("Location message err:", err)
})

7. Send Contact Card as a Message

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: "contact",
		contact: {
			addresses: [
				{
					city: "Menlo Park",
					country: "United States",
					countryCode: "us",
					state: "CA",
					street: "1 Hacker Way",
					type: "HOME",
					zip: "94025"
				},
				{
					city: "Menlo Park",
					country: "United States",
					countryCode: "us",
					state: "CA",
					street: "200 Jefferson Dr",
					type: "WORK",
					zip: "94025"
				}
			],
			birthday: "2012-08-18",
			emails: [
				{
					email: "[email protected]",
					type: "WORK"
				},
				{
					email: "[email protected]",
					type: "WORK"
				}],
			name: {
				firstName: "John",
				formattedName: "John Smith",
				lastName: "Smith"
			},
			org: {
				company: "WhatsApp",
				department: "Design",
				title: "Manager"
			},
			phones: [
				{
					phone: "+1 (940) 555-1234",
					type: "HOME"
				},
				{
					phone: "+1 (650) 555-1234",
					type: "WORK",
					wa_id: "16505551234"
				}
			],
			urls: [
				{
					url: "https://www.facebook.com",
					type: "WORK"
				}
			]
		}
	}
}).then((response) => {
	console.log("Contact Card sent", response)
}).catch(err => {
	console.log("Contact Card err:", err)
})

8. Send Sticker as a Message

client.message.send({
	channel : "whatsapp",
	source : "917834811114",
	destination : "919876543210",
	'src.name': "GupshupAppTest",
	message : {
		type: 'sticker',
		url:"https://cdn.getstickerpack.com/storage/uploads/sticker-pack/tunes-traffic/7.png"
	}
}).then((response) => {
	console.log("Location message sent", response)
}).catch(err => {
	console.log("Location message err:", err)
})

Messages API Response

{	"status":"submitted",
	"messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"
}

User Opt-ins

1. Get Opt-in users list

client.optins.getUsers('GupshupAppTest')
.then((response) => {
	console.log("Optins User list: ", response)
}).catch(err => {
	console.log("Optins User list error: ", err)
})

API Response

{
	"status": "success",
	"users": [
		{
			"countryCode": "91",
			"lastMessageTimeStamp": 1585593959851,
			"optinSource": "URL",
			"optinStatus": "OPT_IN",
			"optinTimeStamp": 1585504095053,
			"phoneCode": "8x98xx21x4"
		}
	]
}

2. Send User Opt-in Request

client.optins.sendUserOptinRequest({
	appName: 'GupshupAppTest',
	userMobileNumber: 919876543210
})
.then((response) => {
	console.log("Optin request sent: ", response)
}).catch(err => {
	console.log("Optin request error: ", err)
})

API Response

{
	"status": 202
}

Development

yarn install

Testing

yarn test

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Gupshup WhatsApp API

About

Installation

Basic Usage

Options

Request Body

Message Payload

Contact Card

Contact Address

Contact Email

Contact Name

Contact Organization

Contact Phone

Contact URL

Supported Resources

Messages

Messages API Response

User Opt-ins

API Response

API Response

Development

Testing