@axis-llc/axis-gupshup-whatsapp

Gupshup WhatsApp API

About

A library wrapping 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 does not connect with the Inbound APIs (that are responsible for receiving messages from customers through webhooks)

Installation

npm i axis-gupshup-whatsapp

or

yarn add axis-gupshup-whatsapp

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('axis-gupshup-whatsapp')

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: "[e-mail]"	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: "[phone]"	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
• User Opt-ins

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: '[e-mail]',
                        type: 'WORK',
                    },
                    {
                        email: '[e-mail]',
                        type: 'WORK',
                    },
                ],
                name: {
                    firstName: 'John',
                    formattedName: 'John Smith',
                    lastName: 'Smith',
                },
                org: {
                    company: 'WhatsApp',
                    department: 'Design',
                    title: 'Manager',
                },
                phones: [
                    {
                        phone: '[phone]',
                        type: 'HOME',
                    },
                    {
                        phone: '[phone]',
                        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