WhatsApp Business API | Self-Service

WhatsApp Self Service

Managing and maintaining your WhatsApp Business Account is easy with tyntec’s self-service, such as our Profile API and webhook API.

 

 

WhatsApp Profile API

The WhatsApp Profile API is a self-service API, allowing you to change your core company details for your WhatsApp Business Account (WABA). In your WhatsApp profile, you’ll be able to update:

  • Company logo (deletion also possible)
  • Public URL for company logo
  • About information
  • Company description
  • e-mail and contact information
  • Company address
  • Vertical/industry
  • Websites

In addition, the Profile API supports patching of single / specific information if needed.

With this API, our customers with an activated WhatsApp Business Account can change/update their information in an automated manner.

How to Get Your Current Profile

curl https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/<PHONENUMBER>/settings/profile -H 'apikey: <APIKEY>'

Response

{
    "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
    "description": "tyntec WhatsApp Business API Demo",
    "email": "support@tyntec.com",
    "vertical": "Professional Services",
    "websites": [
        "https://tyntec.com"
    ],
    "about": "Hey there! I am using WhatsApp."
}

How to Update Your Complete Profile

curl –XPATCH https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/<PHONENUMBER>/settings/profile -H 'apikey: <APIKEY>'  -d ‘
{
    "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
    "description": "tyntec WhatsApp Business API Demo",
    "email": "support@tyntec.com",
    "vertical": "Professional Services",
    "websites": [
        "https://tyntec.com"
    ],
    "about": "Hey there! I am using WhatsApp."
}
‘

Response: 204 No-Content

Update a Part of the Profile

curl –XPATCH https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/<PHONENUMBER>/settings/profile -H 'apikey: <APIKEY>'  -d ‘
{
    "email": "support@tyntec.com",
    "vertical": "Professional Services",
    "websites": [
        "https://tyntec.com", “https://api.tyntec.com/reference”
    ]
}
‘

Response: 204 No-Content

Webhook API

The webhook self-service API allows you to specify applications with webhooks.

In this first version, only a default application per API key is supported, without the possibilities to specify callbacks per WhatsApp Phone Number.

The requests :

The events supported :

"MoMessage",              

"MessageStatus::accepted",

"MessageStatus::delivered",

"MessageStatus::seen",

"MessageStatus::failed",

"MessageStatus::channelFailed",

"MessageStatus::deleted",

"WhatsAppGroupEvent::userJoined",

"WhatsAppGroupEvent::userLeft",

"WhatsAppGroupEvent::subjectChanged",

"WhatsAppGroupEvent::descriptionChanged"

Please note that the patch operation must define all events, any missing will be removed.

How to specify applications with webhooks

{
        "callbackVersion": "2.11",
        "inboundMessageUrl": "<your server>",
        "messageStatusUrl": "<your server>",        
        "eventFilter": [
            "MessageStatus::accepted",
            "MessageStatus::channelFailed",
            "MessageStatus::deleted",
            "MessageStatus::delivered",
            "MessageStatus::failed",
            "MessageStatus::seen"
        ]
    }

Message Templates Management

The Message Template API is a self-service API that allows our customers to:

  • Get current templates
  • Request new templates
  • Add localizations to existing templates
  • Delete templates.  

With this API, customers can request classic text templates as well as the media message templates.

Alternatively, you can use the Message Template Manager directly on your my.tyntec.com account. Check instructions here.

Get current templates

These are examples on requesting new WhatsApp templates.

The name of a template must match ^[a-z][a-z_0-9]+$, so start with lower case letter and consist only of lower case letters, numbers and _.

In general a template can consist of the following three components:

Header

  • Could be either a text (up to 60 characters), an image or a document.
  • In case of a text up to one variable is supported. The variable is indicated by {{1}}.

Body

  • Simple text, that can contain newlines, emojis or urls and variables.
  • Variables are indicated by {{n}}, n sequential natural number without repetition.
  • A variable counts as 1 character for the length.
  • When a Footer or Header component is used it can be at most 160 characters. Otherwise it's 1024 characters.
  • The body must be present and not empty.

Footer

  • Text based footer up to 60 characters.

Adding media samples to message templates

WhatsApp requires that media samples are provided alongside message templates that are categorized as ‘media’ (images, videos, documents). Previously, WhatsApp did not check the media element of message templates. Due to an increase in spam-like media, however, WhatsApp now requests any enterprise with a WhatsApp Business Profile to provide a media sample to avoid customer friction.

This is how you can submit media message templates for:

Please have a look at more information on how to submit your media sample via the API extension below:

Media based headers (video, image, document): 

    {        
        "name": "test_template_media_header",        
        "category": "ACCOUNT_UPDATE",
        "localizations": [
            {
                "language": "en",
                "components": [
                    {
                        "type": "HEADER",
                        "format": "IMAGE",
                        "example": {
                            "mediaId" : "d1c3f5d3-4be0-49cd-a5f8-f90acaaa53a5",  this will be available later
                            "url": "https://upload.wikimedia.org/wikipedia/commons/1/16/HDRI_Sample_Scene_Balls_%28JPEG-HDR%29.jpg"
                        }
                    },
                    {
                        "text": "Hi {{1}},\n\nthis is an {{2}}. For you!",
                        "type": "BODY",
                        "example": {
                            "texts": [
                                "Peter",
                                "Example"
                            ]
                        }
                    },
                    {
                        "type": "BUTTONS",
                        "buttons": [
                            {
                                "type": "URL",
                                "text": "test",
                                "url": "https://www.tyntec.com/{{1}}",
                                "example": {
                                    "url": "https://www.tyntec.com/EXAMPLE"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }

Text based header:

    {        
        "name": "test_template",        
        "category": "ACCOUNT_UPDATE",
        "localizations": [
            {
                "language": "en",
                "components": [
                    {
                        "type": "HEADER",
                        "format": "TEXT",
                        "text": "{{1}} stranger",
                        "example": {
                            "text" : "Hello"
                        }
                    },
                    {
                        "text": "Hi {{1}},\n\nthis is an {{2}}. For you!",
                        "type": "BODY",
                        "example": {
                            "texts": [
                                "Peter",
                                "Example"
                            ]
                        }
                    },
                    {
                        "type": "BUTTONS",
                        "buttons": [
                            {
                                "type": "URL",
                                "text": "test",
                                "url": "https://www.tyntec.com/{{1}}",
                                "example": {
                                    "url": "https://www.tyntec.com/EXAMPLE"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }

Body only template request

{
  "name": "body_only",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}!"
        }
      ]
    },
    {
      "language": "fr",
      "components": [
        {
          "type": "BODY",
          "text": "Bonjour {{1}}!"
        }
      ]
    }
  ]
}

Body with footer template request

{
  "name": "body_and_footer",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}!"
        },
        {
          "type": "FOOTER",
          "text": "Your demo team"
        }
      ]
    }
  ]
}

Text-based header template request

{
  "name": "body_and_text_header",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Hello {{1}}"
        },
        {
          "type": "BODY",
          "text": "This is an example of a text based header"
        }
      ]
    }
  ]
}

Media-based header template request

{
  "name": "body_and_media_header",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "HEADER",
          "format": "IMAGE"
        },
        {
          "type": "BODY",
          "text": "The format could be as well DOCUMENT"
        }
      ]
    }
  ]
}

Requesting new localization

These are examples on requesting new localizations for WhatsApp templates.

You must have requested a template before.

In general a localization of a template can consist of the following three components:

Header

  • Could be either a text (up to 60 characters), an image or a document.
  • In case of a text up to one variable is supported. The variable is indicated by {{1}}.

Body

  • Simple text that can contain newlines, emojis, URLs and variables.
  • Variables are indicated by {{n}}, n sequential natural number without repetition.
  • A variable counts as 1 character for the length.
  • When a Footer or Header component is used it can be at most 160 characters. Otherwise it's 1024 characters.
  • The body must be present and not empty.

Footer

  • Text based footer up to 60 characters

Body only localization request

{
   "language": "en",
   "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}!"
        }
   ]    
}

Body with footer template localization request

{
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}!"
        },
        {
          "type": "FOOTER",
          "text": "Your demo team"
        }
      ]
}

Text-based header template localization request

{
      "language": "en",
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Hello {{1}}"
        },
        {
          "type": "BODY",
          "text": "This is an example of a text based header"
        }
      ]
}

Media-based header template localization request

{
      "language": "en",
      "components": [
        {
          "type": "HEADER",
          "format": "IMAGE"
        },
        {
          "type": "BODY",
          "text": "The format could be as well DOCUMENT"
        }
      ]
}

Interactive template request with quick reply buttons

You can add up to 3 quick reply buttons.

{
  "name": "quick_reply_buttons",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Quick reply buttons are possible as well"
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type" : "QUICK_REPLY",
              "text" : "Cool!"
            },
            {
              "type" : "QUICK_REPLY",
              "text" : "Nice!"
            }
          ]
        }
      ]
    }
  ]
}

Interactive template request with call to action buttons

You can use either one url or one phone number or both types here:

{
  "name": "body_and_text_header",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Quick reply buttons are possible as well"
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type" : "PHONE_NUMBER",
              "text" : "Support",
              "phoneNumber" : "+1231312313"
            },
            {
              "type" : "URL",
              "text" : "Your documents",
              "url" : "https://www.example.com/{{1}}"
            }
          ]
        }
      ]
    }
  ]
}