Thumbnail
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": "491728953754",
    "to": "4923147790813",
    "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/chat-api/v2/channels/whatsapp/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

{
  "to": "12331132",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "1233423454",
    "contentType": "media",
    "media": {
      "type": "sticker",
      "url": "https://www.gstatic.com/webp/gallery/1.webp"
    }
  }
}

Group Messaging

We are announcing the deprecation of Groups through the WhatsApp Business API. The Groups API node will stop accepting any new WhatsApp Business API client phone numbers on July 6, 2020 and end for all WhatsApp Business API client phone numbers on Oct 6, 2020. Please begin migrating calls using this endpoint to avoid any disruption. 

 The Group Messaging feature enables you to further personalize WhatsApp interactions with your customers. With this new feature, your agents or advisors can connect directly with your customers with dedicated group profiles, powering conversations with VIP clients or consulting services, for example.

When creating a group, the logo and the subject are setup when creating the group, but can be changed later. The image can be the company logo, the photo of an advisor; pretty much any image that is relevant for that group. The subject must have a maximum of 35 characters.

The tyntec API currently supports the following functionalities:

  • manage group admins
  • listing all groups
  • creating a new group
  • getting list of participants and remove them from the group
  • getting information about the group
  • updating the group profile and icon
  • maintaining the invite link
  • group chat itself via the normal messaging api
  • group specific events, like user has joined group or user has left group

When a company sends a message to a group, it pays only a tyntec message once (not for each group participant who receives the message).

To Create a New Group:

Request
curl -X POST \
  https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/4923147790717/groups \
  -H 'Content-Type: application/json' \
  -H "apikey: $API_KEY" \
  -d '{
               "subject" : "Group Subject"
}'
 
Response
{
    "creationTime": "1564642001",
    "groupId": "4923147790717-1564642001"
}

To Update the Group Icon:

Request
curl -X PUT \
  https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/4923147790717/groups/4923147790717-1564642001/settings/icon \
  -H 'Content-Type: image/jpeg' \
  -H "apikey: $API_KEY" 
 
 
Response
201 Created

To Send a Link via a Message Template:

Request
curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H "apikey: $API_KEY" 
  -d '{
"to": "27345879345345", 
 "channels": ["whatsapp"],
"whatsapp": {
              "from" : "4923147790717",
              "template" : {
                             "templateId": "group_invite",
                             "language": {
                                           "policy": "deterministic",
                                           "code": "en"
                             },
                             "parameters" : [
                                           {"default": "https://chat.whatsapp.com/CwTQduEL81WHnO9R3QKV20"}
                                           ]
 
 
               },
              "contentType":"template"
}
}'
 
Response
{
    "messageId": "7e8083f5-6ead-4aea-a4b9-ec5feb948c88"
}

To Send a Text Message to the Group:

Request
curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H "apikey: $API_KEY"  \
  -d '{
"to": "4923147790717-1564642001", 
 "channels": ["whatsapp"],
"whatsapp": {
              "from" : "4923147790717",
              "text" : "Hi! And welcome to our group",
              "contentType":"text"
}
}'
 
Response
{
    "messageId": "8953ccfa-3a3a-4eca-a225-324bb8979332"
}

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/messaging/v2/chat/messages\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY' \
-d '{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": 545345345,
    "contentType": "template",
    "template": {
    "templateId" : "order_confirmation",
   "language" : {
      "policy"  : "deterministic",
      "code" : "en"
    },
    "parameters" : {
      "default" : "Ben",
      "default" : "2019-0000001",
      "default" : "600.00",
      "default" : "2019-06-01"
    }
  }
  }
}'

Simple Text Message

Simple Text Code:
curl –XPOST https://api.tyntec.com/messaging/v2/chat/messages\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: YOUR_API_KEY' \
-d '{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": 545345345,
    "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

curl –XPOST https://api.tyntec.com/messaging/v2/chat/messages\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY' \
-d '{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": 545345345,
      "contentType": "media", 
      "media" : {
        "type": "image" 
        "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.svg",
        "caption": "Tyntec Logo"
     }
  }
}'

Audio Files

Audio File Code:

curl –XPOST https://api.tyntec.com/messaging/v2/chat/messages\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY' \
-d '{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": 545345345,
      "contentType": “media", 
      "type": “audio" 
      "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec_song.mp3"
    }
}'

Location

Location Code:

# Send a location
Request
curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: c6aa0006798047f38d16ed7d2673c595' \
   -H "apikey: $API_KEY"  \
  -d '{
"to": "4917624435312", 
 "channels": ["whatsapp"],
"whatsapp": {
              "from" : "4923147790717",
              "location" : {
                             "longitude" : 7.4954884,
                             "latitude" : 51.5005765,
                             "name" : "tyntec GmbH",
                             "address" : "tyntec GmbH, Semerteichstraße, Dortmund"
              },
              "contentType":"location"
}
}'

Interactive Buttons

The use of Interactive Buttons reduces friction in business-to-consumer communication by providing a clear and fast way to provide and collection information with specific tasks, such as making a purchase, selecting a service package or arranging deliveries.

Before, companies had to add the CTA or different options directly on the message template as text. Now, it’s possible to complete a task at the click of a button.

There are two types of interactive buttons:

  • Call-to-action
  • Quick reply

Interactive buttons are supported by message templates and available to you at no extra cost. Companies can add more than one button with specific functions, like “contact us”, “pay”, “track your delivery”, and more.

Call to action

There can be up to two call to action buttons. They come in three flavors:

  • Call Phone Number: This button sub type will let the user to call directly a predefined phone number
  • Visit Static Website: This button sub type will let the user visit a website directly with a static link. For example handy to be used for house rules, guidelines, ....
  • Visit Dynamic Website: This button sub type will let the user visit a website, which can be personalized with one parameter at the end.

A call to action can be setup as a media message template. Please see more information here.

 

You can find more information and inspiration about Interactive Buttons in this blog post.

The API request will look like this:

{
 "to": "{{toPhoneNumber}}", 
 "channels": ["whatsapp"],
 "whatsapp": {
    "from" : "{{whatsappPhoneNumber}}",
    "template" : {
        "templateId": "2fa_qr_code",
        "language": {
            "policy": "deterministic",
            "code": "nb"
        },
        "components" : [
            {"type" : "body",
                "parameters" : [
                    {"type" :"text", "text" : "Stephanie"}
                ]
            },
            {"type" : "button",
            "subType" : "url",
            "index" : 0,
            "parameters" : [{"type" :"text", "text" : "224f1bb5-1cda-48b0-997f-0cf73b00a4df "}]
 
            }
            ]
 
 
    },
    "contentType":"template"
 }
}

Quick Reply

This button will send back:

  • the predefined text of a button and
  • a freely specified payload.

to the customer via a Chat API event.  

The payload has to be set when sending the message template. There can be up to 3 buttons. 

The API request will look like this:

{
 "to": "{{toPhoneNumber}}", 
 "channels": ["whatsapp"],
 "whatsapp": {
    "from" : "{{whatsappPhoneNumber}}",
    "template" : {
        "templateId": "event_review",
        "language": {
            "policy": "deterministic",
            "code": "en"
        },
        "components" : [
            {"type": "header",
                "parameters" : [ {"type" : "media",
                    "media" : {"url" : "https://upload.wikimedia.org/wikipedia/commons/6/6c/Sample_EPC_QR_code.png", "type" :"image"}
                }]
            },
            {"type" : "body",
                "parameters" : [
                    {"type" :"text", "text" : "Stephanie"},
                    {"type" :"text", "text" : "Button Demo"},
                    {"type" :"text", "text" : "Dortmund"}
                ]
            },
            {"type" : "button",
            "subType" : "quick_reply",
            "index" : 0,
            "parameters" : [{"type" :"payload", "payload" : "224f1bb5-1cda-48b0-997f-0cf73b00a4df "}]
 
            },
            {"type" : "button",
            "subType" : "quick_reply",
            "index" : 1,
            "parameters" : [{"type" :"payload", "payload" : "224f1bb5-1cda-48b0-997f-0cf73b00a4df "}]
 
            },
            {"type" : "button",
            "subType" : "quick_reply",
            "index" : 2,
            "parameters" : [{"type" :"payload", "payload" : "224f1bb5-1cda-48b0-997f-0cf73b00a4df "}]
 
            }
            ]
 
 
    },
    "contentType":"template"
 }
}

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/messaging/v2/chat/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/messaging/v2/chat/messages/77185196-664a-43ec-b14a-fe97036c697f/history \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

This will trigger a response such as:

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
      "history": [
        {
            "happendAt": "2019-05-17T09:45:00Z",
            "state": "message-accepted"
        },
        {
            "deliveryChannel": "whatsapp",
            "happendAt": "2019-05-17T09:45:01Z ",
            "state": "message-routing-success"
        },
        {
            "deliveryChannel": "whatsapp",
            "happendAt": "2019-05-17T09:45:02Z ",
            "state": "message-dispatching-success"
        },
        {
            "deliveryChannel": "whatsapp",
            "happendAt": "2019-05-17T09:45:03Z ",
            "state": "message-failed",
            "details": {
                "code": "470",
                "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
            }
        },
        {
            "happendAt": "2019-05-17T09:45:04Z ",
            "state": "message-finally-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.