Session Messages

In this section, you will get acquainted with Free form, or sessions messages which are text or media messages that can contain any content. These messages are only allowed to be sent if there is an open conversation session. An open conversation session refers to any conversations that were started from:

• a business-initiated message that were responded to by the user, which opens a 24-hour session.
• a user-initiated message that were responded to by your agents or your chatbot which opens a 24-hour session.
• a user-initiated conversation that were started from other entry points - such as click to whatsapp ads, which opens a 72-hour session.

For more information, please refer to the conversation categories guide.

Unifonic Conversations API

Before we begin, this is the API end point: https://apis.unifonic.com/v1/messages

You will also require a publicId and secret key to be used as Headers.

Free-form Messages

Free form messages are regular messages which don’t need approval from Facebook. Business is able to send a free-form message only if a user is the one to initiate conversation or respond to the message template. These messages are considered to support messages and Business is encouraged to have Chatbot and Escalation path available on the number.

Free form messages can be sent only 24 hours from the last user message. Every time when the user sends a new message 24-hour window will extend.

The following types are supported for free-form messages

• Text - up to 4096 characters
• Media (Images/Documents/Audio/Video/Stickers)
• Location
• Interactive Buttons
• Interactive List
• Contacts

Text messages

• Text messages may contain up to 4096 characters and 1024 Unicode characters

• Business is able to format messages as Bold (* *), Italic (_ _), Strikethrough (~ ~), and Code ( ).

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "text",
    "text": "{{text}}"
  }
}

• Support for sending url in text field and enabling previewing of url

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "text",
    "text": "https://www.sampleurl.com/sampleurl",
    "preview_url": true
  }
}

👍

preview_url helps with click through

Enabling preview url allows WhatsApp to show a preview of what the URL is about, this typically increases user trust for your website link

Media messages

Supported Message Types

To send any media message

• The Business will need to provide a URL that is publicly available along with the media.
• A caption of up to 1024 characters can also be added.

Image Message:

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "image",
    "url": "{{urlImagePng}}"
    
  }
}

Video Message

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "video",
    "url": "{{urlVideoMp4}}"
  }
}

Document Message

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "file",
    "url": "{{urlFilePdf}}",
    "fileName": "testing.pdf",
    "text": "text111"
  }
}

Audio Message

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "audio",
    "url": "{{urlAudioMp3}}"
  }
}

Sticker Message

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "sticker",
    "url": "{{urlSticker}}"
  }
}

🚧

Animated stickers are not supported for on-prem hosted customers.

Location Messages

Business is able to send static location with provided following details:

• Longitude- mandatory - coordinates between -180 and 180
• Latitude- mandatory - coordinates between -90 and 90
• Name - optional
• Address - optional

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "location",
    "location": {
        "latitude": 37.758056,
        "longitude": -122.425332,
        "name": "Facebook HQ",
        "address": "Hacker Way"
    }
  }
}

Contact Messages

Business is able to send a contact which can contain the following data:

• Name
• Address

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "contacts",
        "contacts": [
            {
                "addresses": [
                    {
                        "city": "Singapore",
                        "country": "Singapore",
                        "countryCode": "sg",
                        "state": "Singapore",
                        "street": "Nil",
                        "type": "WORK",
                        "zip": "33333"
                    }
                ],
                "name": {
                    "firstName": "Johnny",
                    "middleName": "M",
                    "lastName": "Doe",
                    "prefix": "Mr.",
                    "suffix": "",
                    "formattedName": "John M. Doe"
                },
                "birthday": "2010-11-11",
                "emails": [
                    {
                        "email": "[email protected]",
                        "type": "WORK"
                    }
                ],
                "org": {
                    "company": "Unifonic",
                    "department": "Engineering",
                    "title": "Mule"
                },
                "phones": [
                    {
                        "phone": "+65XXXXXXX",
                        "type": "WORK"
                    }
                ],
                "urls": [
                    {
                        "url": "https://unifonic.com",
                        "type": "url type"
                    }
                ]
            }
        ]
    }
}

Interactive Buttons

Businesses can use interactive buttons to send customers messages with up to 3 predefined responses.

These work in the same way as quick replies in message templates, but are available for free-form messages. Users will only be able to select one option at a time per message but can change their selection.

Quick reply messages are made up of the following:

• Header - optional - Text up to 60 characters, image, video, document
• Body - Text up to 1024 characters
• Footer - optional - Text only up to 20 characters
• Buttons - Text only with a maximum of up to 20 characters, only 3 butttons are allowed and are shown in sequence

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "replyButton",
    "body": "free text",
    "header": {"type":"text","text":"header Message"},
    "footer": {"text":"test footer messages"},
    "buttons":[
        {
            "title": "section title1",
            "id": "id1"
        },
        {
            "title": "section title2",
            "id": "id2"
        },
        {
            "title": "section title3",
            "id": "id3"
        }
    ]
  }
}

Interactive Lists

Businesses can send to customers a message to select from a list of up to 10 options to confirm the option they would like to choose. For example: While the customer is booking an appointment they can choose available timings.

List messages can contain the following:

• Header - optional - Text shown at the top of the list message
• Body - Up to 1024 characters
• Footer - optional - Up to 60 characters
• List
  • List title - List button text, up to 20 characters
  • Section title - Not visible and used for reference
  • Row titles - Single selection options accompanied by a radio button
  • Row descriptions - Provide additional context to selectable options

{
  "recipient": {
    "contact": "+971543455235",
    "channel": "whatsapp"
  },
  "content": {
    "type": "listMessage",
    "body": "test",
    "header": {"type":"text","text":"header Message"},
    "footer": {"text":"Verify Session Messages"},
    "button":"button",
    "sections":[
        {
            "title": "section title",
            "rows": [
                {
                    "id": "id",
                    "title": "row title",
                    "description": "description2"
                },
                {
                    "id": "id2",
                    "title": "row title2",
                    "description": "description2"
                }
                ,
                {
                    "id": "id3",
                    "title": "row title3",
                    "description": "description2"
                }
                ,
                {
                    "id": "id4",
                    "title": "row title4",
                    "description": "description2"
                }
                ,
                {
                    "id": "id5",
                    "title": "row title5",
                    "description": "description2"
                }
                ,
                {
                    "id": "id6",
                    "title": "row title6",
                    "description": "description2"
                }
                ,
                {
                    "id": "id7",
                    "title": "row title7",
                    "description": "description2"
                }
            ]
        },
        {
            "title": "section title2",
            "rows": [
                {
                    "id": "id21",
                    "title": "row title21",
                    "description": "description3"
                }
            ]
        }
        ,
        {
            "title": "section title3",
            "rows": [
                {
                    "id": "id31",
                    "title": "row title31",
                    "description": "description4"
                },
                {
                    "id": "id32",
                    "title": "row title32",
                    "description": "description4"
                }
            ]
        }
    ]
  }
}

Single Product Message

Businesses can send to customers a product from a catalog that they have curated on the Meta Platform.

Single Product messages can contain the following:

• Header - optional - Text shown at the top of the list message
• Body - Up to 1024 characters
• Footer - optional - Up to 60 characters
• Catalog ID - identifier of the catalog which you have added on your platform. You can find catalog using this API
• Product Retailer ID - unique identifier of a product within a catalog

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "product",
        "body": "your-text-message-content",
        "footer": {
            "text": "your-footer-content"
        },
        "catalogId": "1148409582413138",
		"productRetailerId": "cat587"
    }
}

Multi-Product Message

Businesses can send to customers some curated items from a connected catalog that is maintained on the Meta Platform.

• Header - mandatory- Text shown at the top of the list message
• Body - Up to 1024 characters
• Footer - optional - Up to 60 characters
• Catalog ID - identifier of the catalog which you have added on your platform. You can find catalog using this API
• sections - an array of sections in a catalog
  • title - section title
  • product items -
    • product retailer ID - unique identifier of a product within a catalog

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "productList",
        "header": {
            "type": "text",
            "text": "Menu"
        },
        "body": "Buy a Text",
        "footer": {
            "text": "Unifonic Menu "
        },
         
        "catalogId": "61932108984534334349",
       
        "sections": [
            {
                "title": "apple1",
                "productItems": [
                    {
                        "productRetailerId": "u3vxgpep0t"
                    },
                    {
                        "productRetailerId": "y3ciclp14p"
                    },
                    {
                        "productRetailerId": "wwxoco8db1"
                    }
                ]
            },
            {
                "title": "grapes2",
                "productItems": [
                    {
                        "productRetailerId": "y3ciclp14p"
                    },
                    {
                        "productRetailerId": "u3vxgpep0t"
                    },
                    {
                        "productRetailerId": "wwxoco8db1"
                    }
                ]
            },
            {
                "title": "grapes3",
                "productItems": [
                    {
                        "productRetailerId": "y3ciclp14p"
                    },
                    {
                        "productRetailerId": "u3vxgpep0t"
                    },
                    {
                        "productRetailerId": "wwxoco8db1"
                    }
                ]
            }
    
        ]
       }
    }

Catalogue Link Message

Customers can send a link which shows an entire product catalogue by assembling a wa.me link and including it in a standard text message. When sending a text message, you can use the optional preview_url set to true to have the message render a set of product catalog thumbnails of any URL in the message body string.

To assemble wa.me link, append your business phone number, including country code, to the end of the following string: https://wa.me/c/
e.g. https://wa.me/c/15555455657

{
  "recipient": {
    "contact": "{{phoneNumber}}",
    "channel": "whatsapp"
  },
  "content": {
    "type": "text",
    "text": "https://wa.me/c/{{whatsappNumber}}",
    "previewUrl": true
  }
}

In order to connect a Meta product catalogue to your whatsapp number, contact the Unifonic Support Team.

Catalogue Session Message

Catalog messages are free-form messages that allow you to showcase your product catalog entirely within WhatsApp. Catalog messages display a product thumbnail header image of your choice, custom body text, a fixed text header, a fixed text sub-header, and a View catalog button.

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "catalogMessage",
        "body": "Hello! Thanks for your interest. Order is easy. Just visit our catalog and add items to purchase.",
        "footer": {
            "text": "free text"
        },
        "thumbnailProductRetailerId": "cat103"  //any item's id in your catalog to be used as thumbnail
    }
}

The message which your user will receive looks like this: