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: "[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
• 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: '[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