icon_whatsapp_business_docs_center_33px_white_
WhatsApp Business API | Capabilities and Features

With the WhatsApp Business API, enterprises have access to an array of capabilities and multimedia features.

WhatsApp Use Cases | tyntec

Features of WhatsApp Business Account

Features of WhatsApp Businesss Solution | tyntec
  • Your Brand: with a Business Account, your company name is clearly visible at the top.
  • Your Logo: upload a logo for easy recognition (640x640 px, <5 MB)
  • Get Verified: With a verified badge in green (optional), you add more trust to your customer communications.
  • Encryption: WhatsApp messages are encrypted from tyntec to the device, and secured over HTTPS (and optional SSL/VPN) from your application to tyntec.
  • Message Templates: you can initiate conversations with pre-approved message templates (text and media).
  • Send Rich Media: you can send multimedia messages as message templates (see more information in Media Message Templates) and in the “support window”. These include images, documents, videos, locations, and more.
  • Contacts: send and receive contacts.

Allow Customers to Reach You and Process Conversational Signals:

Messaging Signals, WhatsApp Business API | tyntec
  • Delivery and Read Receipts: you see in real-time when the message has been delivered and read directly on the WhatsApp interface.
  • Track Replies: you can always refer to specific messages when replying.
  • Track Deleted Messages: Manage your messages and delete them when necessary.
  • Receive Media: your consumers can send an array of multimedia functions to your Business Account.

Mark User Messages as "Read"

Companies can mark messages received by their users as "read", indicating that the message was seen by an agent/chatbot of the company, boosting engagement transparency. This is shown as the double check mark that is already known in the WhatsApp user base.

This is how it works:

Whenever you  receives an inbound message from your user:

{
    "messageId": "ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t",
    "channel": "whatsapp",
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "receivedAt": "2019-11-19T15:30:25Z",
    "content": {
        "contentType": "text",
        "text": "Peng",
        "media": null,
        "location": null
    },
    "event": "MoMessage",
    "whatsapp": {
        "senderName": "Peter Daum @ tyntec"
    },
    "timestamp": "2019-11-19T15:30:25Z"

Take the message id – in this case ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t – and execute

PUT

https://api.tyntec.com/conversations/v3/messages/ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t

with the json payload.

{
               "status" : "read"
}

Stickers

Digital, often animated emoji stickers offer far more nuanced, varied, and personalized forms of expression compared to flat, often generic emoji sets. To convey emotions and reactions in an instant, folk often turn to visual short-hands such as emojis and animated GIFs.

WhatsApp stickers are digital elements that give your customer conversation a more branded look.

Stickers can only be sent as chat messages. To date, it's not possible to send stickers as a media message template.

How to send stickers

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "sticker",
        "sticker" : {
            "url": "https://www.tyntec.com/sites/default/files/2020-07/tyntec_rocket_sticker_512px_001_.webp"
        }
    }
}'

Content Types

WhatsApp supports a range of media message features, from simple text and images, to audio files, location and interactive buttons. Below you'll find the supported content types and sample codes.

Media Supported Content-Types
Audio audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus. NOTE: The base audio/ogg type is not supported.
Document Any valid MIME-type
Image image/jpeg, image/png
Sticker image/webp
Video video/mp4, video/3gpp. NOTE: Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.

Message Template

Template Message Code:

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: API_KEY' \
-d '{
  "from" : "{{whatsAppBusinessNumber}}",
  "to" : "{{receiverPhoneNumber}}",
  "channel": "whatsapp",
  "content": {   
    "contentType": "template",
    "template": {
        "templateId" : "order_confirmation",
        "templateLanguage" : "en",
        "components" : {
            "body" : [
                    {
                        "type": "text",
                        "text": "Ben"
                    },
                    {
                        "type": "text",
                        "text": "2019-0000001"
                    },
                    {
                        "type": "text",
                        "text": "600.00"
                    },
                    {
                        "type": "text",
                        "text": "2019-06-01"
                    }
            ]           
        }
   }
  }
}'

Simple Text Message

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    {
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "text",
        "text" : "Hi Susan!\n\nYay! You´re officially a Fashion member. We are excited to have you onboard.\n\nCheers,\nThe Fashion Team"
    }
}'

Images

image_wa_conversation_rounded_borders_image_message_as_image_message_0.35x
curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "image",
        "image" : {
            "url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Sample_EPC_QR_code.png",
            "caption" : "Welcome Louise!/n/nThanks for signing up with us./nIf you need anything please let us know./n/nYour Fashion Team"
        }
    }
}'

Audio Files

Audio File Code:

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "audio",
        "audio" : {
            "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.opus"
        }
    }
}'

Location

image_wa_conversation_rounded_borders_location_message_as_message_0.35x

Location Code:

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "location" : {
            "longitude" : 7.4954884,
            "latitude" : 51.5005765,
            "name" : "tyntec GmbH",
            "address" : "tyntec GmbH, Semerteichstraße, Dortmund"
        },
        "contentType":"location"
    }
}'

Interactive Buttons

WhatsApp’s Message Templates support the usage of Interactive Buttons. This allows businesses to place actionable triggers in a conversation that lead your user to the next step.

There are 2 types of Interactive Buttons:

  • Call-to-Action Buttons
  • Quick Reply Buttons

Both button types can be used in Message Templates.

Note: Interactive buttons are available at no extra cost.

Call-to-Action Buttons

You can place up to 2 Call-to-Action Buttons in a Message Template. One button can be the trigger to call a phone number. The other button can be the trigger to open an URL.

Businesses typically use the phone number button to share a direct contact possibility with the customer. The URL button is typically used to provide more information, a payment link, or tracking link.

When submitting your Message Template, the parameters of the buttons used are subject to WhatsApp’s Message Template approval, and can’t be changed for this Message Template after approval was given.

URLs in Call-to-Action buttons can either be static or dynamic. If you want to use dynamic URLs, you will need to provide the static part of your URL with a variable when submitting your Message Template. You can then append the suffix variable when sending your Message Template.

Dynamic URL example:

https://your-business.com/static_part_of_the_url/{{1}}

Call-to-Action types

Need some inspiration? Read our blog post about the usage of Interaction Buttons.

API Request for Call-to-Action Buttons

When sending a Message Template with Interactive Buttons, you will need to ensure that the " index" matches the position of the button in your Message Template.

For example, if the URL button shall be placed in second position, the index has to be set to "1".

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "Additional Variable"
                    }
                ],
                "buttons" : [
                    {
                        "type" : "url",
                        "index": 1,
                        "text" : "test"
                    }
                ]
            }
        }
    }
}'

Quick Reply Buttons

Quick Replies are typically used for offering pre-defined answers to a question. You can place up to 3 Quick Reply Buttons within one Message Template. In comparison to Call-to-Action Buttons, you cannot assign a URL or phone number to a Quick Reply Button.

One prominent use case for Quick Reply Buttons is the usage in automated conversations, e.g. when using a chatbot. But Quick Reply Buttons can be also extremly helpful for your customer support agents to provide a frictionless conversation flow between your business and customers.

When submitting your Message Template, the parameters of the buttons used are subject to WhatsApp’s Message Template approval, and can’t be changed for this Message Template after approval was given.

Quick Reply Payloads

Each Quick Reply Button can be assigned a different payload which then sent back with the answer your user chooses. This payload enables you to associate for example an ID that correlates to any kind of ID in your systems. Making it easy for you to reference the answer.

API Request for Quick Reply Buttons

When sending a Message Template with Interactive Buttons, you will need to ensure that the " index" matches the position of the button in your Message Template.

For example, if the Quick Reply button shall be placed in first position, the index has to be set to "0". For Quick Reply Buttons the index options range from "0"(first position) to "2"(third position).

{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "event_rating",
            "templateLanguage" : "en",
            "components" : {
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "WhatsApp Demo"
                    }
 
                ],
                "buttons" : [
                    {
                        "type" : "quick_reply",
                        "index": 0,
                        "payload" : "event-id123"
                    },
                    {
                        "type" : "quick_reply",
                        "index": 1,
                        "payload" : "event-id123"
                    },
                    {
                        "type" : "quick_reply",
                        "index": 2,
                        "payload" : "event-id123"
                    }
                ]
            }
        }
    }
}

Querying the Message Status

The current status of a message can be checked via our API as well. This might be interesting for you if you haven’t setup a notification webhook or need to manually query the status. The following example explains how message status can be checked:
curl https://api.tyntec.com/conversations/v3/messages/77185196-664a-43ec-b14a-fe97036c697f/status \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

Below, will be the returning code if your message did not go through:

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
 "status": "failed"
}

If your message failed to go through, you can check the history in the next section — Querying the Message History

Querying the Message History

In case you need further details on a message, such as if you received a send failure — you can easily check this with the following:
curl https://api.tyntec.com/conversations/v3/messages/77185196-664a-43ec-b14a-fe97036c697f/events \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

This will trigger a response such as:

{
    "messageId": "d5e8278d-db38-403a-8df3-2f9169040aa0",
    "events": [
        {
            "timestamp": "2021-04-07T07:01:18.691Z",
            "event": "MessageStatus::accepted"
        },
        {
            "channel": "whatsapp",
            "timestamp": "2021-04-07T07:01:19.014Z",
            "event": "MessageStatus::dispatched"
        },
        {
            "channel": "whatsapp",
            "timestamp": "2021-04-07T07:01:19.064Z",
            "event": "MessageStatus::channelFailed",
            "details": {
                "code": "whatsapp::error::470",
                "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
            }
        },
        {
            "timestamp": "2021-04-07T07:01:19.464Z",
            "event": "MessageStatus::failed",
            "details": {
                "code": "tyntec::error:noFurtherChannelAvailable",
                "message": "No further channel after Channel[whatsapp] available"
            }
        }
    ]
}

In this example, the message because the brand tried to send a text message outside of the 24h support window, and no fallback was specified.