Product Guide

Message Type: Outbound (free form)

Suggest Edits

Send numerous message kinds using free-form messages. When specific circumstances are met, cut-off control stops users from receiving messages.

Only the first 24 hours after the consumer last got in touch with your company are allowed for the delivery of regular text messages or media communications (i.e., any non-message templates). If you want to contact clients outside of this window, you can utilise message templates because they are not subject to this restriction.

The following elements are sendable through WhatsApp; however, be aware of the restrictions and supported choices for each element.

Text

Send a message in the form of text to customers. You can send text in any of the following formats:

  • Bold (using asterisks)
  • Italic (using underscores)
  • Strikethrough (~using tildes~)
  • Code (using three backticks)

Each free-form message can have up to 4096 characters. Text restrictions differ for the pertinent areas of templates. Emojis may also be used in text communications.

The message length constraints also take into account URL character counts. Text messages and URLs should adhere to the character restriction. The option to show URL previews in messages is also available.

{
    "type": "text",
    "text": "Hello"
}

📘

In media messages, if “id” and “url” (originalUrl) fields are both present then “id” is given more preference over “url” to send media messages to WhatsApp. Either URL or id must be present to send media messages.

Files

Send files to customers. Files should have names in the form of text, up to 240 characters. If no name is given, WhatsApp will assign one.

You can send the following document file types:

  • PDF
  • DOC(X)
  • PPT(X)
  • XLS(X)

Document file sizes can be up to 100MB.

{
    "type": "file",
    "url": "http://unec.edu.az/application/uploads/2014/12/pdf-sample.pdf",
    "caption": "Cool File",
    "filename": "pdf-sample.pdf",
    "id": "mediaId"
}

Images

Send images to customers. You can also send messages in the form of an image and caption together. Image captions can be up to 3000 characters long.

The following image types are supported:

  • JPG
  • JPEG
  • PNG
  • Image sizes can be up to 5MB.
{
    "type": "image",
    "originalUrl": "https://homepages.cae.wisc.edu/~ece533/images/frymire.png",
    "caption": "Cool Image",
    "id": "mediaId"
}

Audio

Send audio messages to customers.

The following audio types are supported:

  • AAC
  • AMR
  • MP4
  • OPUS

Audio file sizes can be up to 16MB.

{
    "type": "audio",
    "url": "https://www.kozco.com/tech/LRMonoPhase4.wav",
    "fileName": "AudioFile",
    "id": "mediaId"
}

Video

Send video messages to customers. You can also send messages in the form of a video and captions together. Video captions can be up to 3000 characters long.

The following video types are supported:

  • MP4
  • 3GPP

Video sizes can be up to 16MB.

{
    "type": "video",
    "url": "https://www.buildquickbots.com/whatsapp/media/sample/video/sample02.mp4",
    "caption": "Video Caption",
    "id": "mediaId"
}

Stickers

Send stickers as messages to customers. There are a few formatting requirements to follow with stickers:

  • WEBP files only
  • Cannot exceed 100KB
  • Must be 512x512px
  • Must be a 16px margin around the sticker
  • Must have a transparent background

Animated stickers are not supported by WhatsApp.

{
  "type": "sticker",
  "url": "https://blog.jiayu.co/2019/07/telegram-animated-stickers/sticker.webp"
}

Location

Send a static location in the form of a message. Location messages are in the form of interactive maps.

The following components are included in your location messages:

  • Longitude - Coordinates between -180 and 180
  • Latitude - Coordinates between -90 and 90
  • Location Name - Name of the location (optional)
  • Address - Address of the location (optional)
{
  "type": "location",
  "longitude": -122.425332,
  "latitude": 37.758056,
  "name": "Gupshup",
  "address": "Mumbai"
}

Contacts

Send a contact saved in your address book. This allows recipients to autosave contacts into their devices using a save button.

Contact messages consist of an array of contact-related objects. Each of those objects contains a further set of sub-objects.

High-level objects include:

  • Name
  • Address
  • Emails
  • Organization
  • Phone
  • URL
  • Birthday
{
    "type": "contact",
    "contact": {
        "addresses": [
            {
                "city": "Menlo Park",
                "country": "United States",
                "country_code": "us",
                "state": "CA",
                "street": "1 Hacker Way",
                "type": "HOME",
                "zip": "94025"
            },
            {
                "city": "Menlo Park",
                "country": "United States",
                "country_code": "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": {
            "name": "WhatsApp",
            "details": "Design"
        },
        "phones": [
            {
                "phone": "+1 (940) 555-1234",
                "type": "HOME"
            }
        ],
        "urls": [
            {
                "url": "https://www.facebook.com",
                "type": "WORK"
            }
        ]
    }
}

Lists

Provide users with a list of up to 10 choices from which to choose to confirm a preference, such as a location for the service they are trying to learn more about.

One option can only be chosen by a user at a time.

List messages are made up of the following:

  • Header - Text is shown at the top of the list message. Maximum of 60 characters (optional)
  • Body - Message text content. Maximum of 1024 characters
  • Footer - Footer text content. Maximum of 60 characters
  • List
    • List title - List button text. Maximum of 20 characters
    • Section title - Not visible and used for reference. Maximum of 24 characters (optional)
    • Row titles - Single selection options accompanied by a radio button
    • Row descriptions - Provide additional context to selectable options (optional)
    • List item title - Name of the list item. Maximum of 24 characters
    • List item description - Details about the list item. Maximum of 72 characters (optional)
    • Postback - Payload value for list item. Maximum of 200 characters
{
    "type": "list",
    "title": "title text",
    "body": "body text",
    "globalButtons": [
        {
            "type": "text",
            "title": "button text"
        }
    ],
    "items": [
        {
            "subtitle": "first Subtitle",
            "options": [
                {
                    "title": "section 1 row 1",
                    "description": "first row of first section desctiption"
                },
                {
                    "title": "section 1 row 2",
                    "description": "second row of first section desctiption"
                }
            ]
        },
        {
            "title": "second section",
            "subtitle": "second Subtitle",
            "options": [
                {
                    "title": "section 2 row 1",
                    "description": "first row of second section desctiption"
                }
            ]
        },
        {
            "title": "third Section",
            "subtitle": "third Subtitle",
            "options": [
                {
                    "title": "section 3 row 1",
                    "description": "first row of third section desctiption"
                }
            ]
        }
    ]
}

Quick reply

{
    "type": "quick_reply",
    "msgid": "msg001",
    "content": {
        "type": "text",
        "text": "What's your favourite color?"
    },
    "options": [
        "Red",
        "Green",
        "Yellow",
        "Blue"
    ]
}

Quick reply with postback data

{
    "type": "quick_reply",
    "msgid": "msg001",
    "content": {
        "type": "text",
        "text": "What's your favourite color?"
    },
    "options": [
        {
            "type": "text",
            "title": "Apple",
            "postbackText": "Apple Selected"
        },
        {
            "type": "text",
            "title": "Banana",
            "postbackText": "Banana Selected"
        }
    ]
}

Quick reply with image content

{
    "type": "quick_reply",
    "msgid": "qr1",
    "content": {
        "type": "image",
        "url": "https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
        "text": "this is the body",
        "caption": "this is the footer"
    },
    "options": [
        {
            "type": "text",
            "title": "First",
            "postbackText": "dev-defined-postback1"
        },
        {
            "type": "text",
            "title": "Second",
            "postbackText": "dev-defined-postback2"
        },
        {
            "type": "text",
            "title": "Third",
            "postbackText": "dev-defined-postback3"
        }
    ]
}

Quick reply with video content

{
    "type": "quick_reply",
    "msgid": "qr1",
    "content": {
        "type": "video",
        "url": "https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4",
        "text": "this is the body",
        "caption": "Sample video"
    },
    "options": [
        {
            "type": "text",
            "title": "First",
            "postbackText": "dev-defined-postback1"
        },
        {
            "type": "text",
            "title": "Second",
            "postbackText": "dev-defined-postback2"
        },
        {
            "type": "text",
            "title": "Third",
            "postbackText": "dev-defined-postback3"
        }
    ]
}

Quick reply with file content

{
    "type": "quick_reply",
    "msgid": "qr1",
    "content": {
        "type": "file",
        "url": "https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf",
        "text": "this is the body",
        "filename": "Sample file",
        "caption": "this is the footer"
    },
    "options": [
        {
            "type": "text",
            "title": "First",
            "postbackText": "dev-defined-postback1"
        },
        {
            "type": "text",
            "title": "Second",
            "postbackText": "dev-defined-postback2"
        }
    ]
}

Single product message

Send a message that is interactive about a good or service that is offered in your catalogue. Without leaving the conversation, customers may inquire about the product, add it to their shopping, and submit the cart.

You need a Meta catalogue linked to your WhatsApp Business Account in order to send a Product message.

The following elements are present in product messages:

  • Body (required) (mandatory)
  • Footer Text (mandatory)

The following elements are included in the action component:

  • Catalog ID
  • The product ID that is listed in the catalogue is called the product retailer ID.
{
    "type": "product_details",
    "subType": "product",
    "catalogId": "6373780729363060",
    "productId": "MOBILE0001",
    "body": {
        "text": "We have exciting deals and discounts this Diwali😱🤯"
    },
    "footer": {
        "text": "footerContent!"
    }
}

Multi-product message

Send an interactive message about products or services that are present in your catalog. You can include a maximum of 30 products, presented in a maximum of 10 sections, in the message. Customers can ask questions about the product, add the product to the cart, and submit the cart without leaving the chat.

To send a Multi-product message, you must have a Meta catalog that is connected to your WhatsApp Business Account.

Multi-product messages contain the following components:

  • Header (mandatory)
  • Body (mandatory)
  • Footer
  • Action (mandatory)

The Action element contains the following components:

  • Catalog ID
  • Section
    • Title
    • Product Retailer ID: The product ID that is present in the catalog.
{
    "type": "product_details",
    "subType": "product_list",
    "catalogId": "6373780729363060",
    "productId": "",
    "body": {
        "text": "We have exciting deals and discounts this Diwali.😱🤯"
    },
    "footer": {
        "text": "Don't miss it out."
    },
    "header": {
        "type": "text",
        "text": "header content!"
    },
    "sections": [
        {
            "title": "MultiProduct_1",
            "productList": [
                {
                    "productId": "MOBILE0001"
                },
                {
                    "productId": "SONYTV001"
                }
            ]
        }
    ]
}

Order details

{
    "type": "order_details",
    "goodsType": "physical-goods",
    "referenceId": "cf5d108e-ff79-4396-aeda-559c87cc5915",
    "currency": "INR",
    "header": {
        "type": "image",
        "image": {
            "id": null,
            "link": "https://i.imgur.com/WUAs4vC.jpeg",
            "providerName": "providerName"
        }
    },
    "body": "bodyText",
    "footer": "footerText",
    "catalogId": null,
    "items": [
        {
            "name": "item1",
            "itemId": "item-1-id",
            "quantity": 2,
            "amount": {
                "value": 8000,
                "offset": 100
            },
            "saleAmount": {
                "value": 7000,
                "offset": 100
            },
            "countryOfOrigin": "INDIA",
            "importer": {
                "name": "importerName",
                "address": {
                    "addressLine1": "B8/733 nand nagri",
                    "addressLine2": "police station",
                    "city": "East Delhi",
                    "zoneCode": "DL",
                    "postalCode": "110093",
                    "countryCode": "IN"
                }
            }
        },
        {
            "name": "item2",
            "itemId": "item-2-id",
            "quantity": 1,
            "amount": {
                "value": 9000,
                "offset": 100
            },
            "saleAmount": {
                "value": 8000,
                "offset": 100
            },
            "countryOfOrigin": "INDIA",
            "importer": {
                "name": "importerName",
                "address": {
                    "addressLine1": "B8/733 nand nagri",
                    "addressLine2": "police station",
                    "city": "East Delhi",
                    "zoneCode": "DL",
                    "postalCode": "110093",
                    "countryCode": "IN"
                }
            }
        }
    ],
    "tax": {
        "value": 50,
        "offset": 100,
        "description": "tax Description"
    },
    "shipping": {
        "value": 100,
        "offset": 100,
        "description": "shipping Description"
    },
    "discount": {
        "value": 100,
        "offset": 100,
        "description": "discount Description"
    },
    "paymentConfiguration": "GupshupTest"
}

Payment eligibility

{
    "type": "payment_eligibility"
}

Order status update

OrderStatus , supports following value (case-sensitive) :-

  • pending
  • processing
  • partially_shipped
  • shipped
  • completed
  • canceled
{
    "type": "order_update",
    "referenceId": "reference-id-value",
    "orderStatus": "order-status-value",
    "statusDescription": "optional-text",
    "body": {
        "text": "your-text-body-content"
    },
    "footer": {
        "text": "your-text-footer-content"
    }
}

Updated over 1 year ago