How to create a WhatsApp template with media

 

WhatsApp messaging allows to send messages with embedded media. This is common practice when implementing WhatsApp marketing messaging, to include media in the messages to enhance the user experience of the recipient.

Meta requirements impose to create templates that must be approved by them, to be used as engaging first message to final customers.

Templates can include media, and this must be configured when the template is created, following the appropriate API payload syntax.

 

This document provides information on how to create a marketing WhatsApp template with media header using SCG APIs. We will provide examples on how to create an SCG WhatsApp template using some of the available components and how to send a message using the new template.

 

SCG-WhatsApp supported Media

Syniverse SCG templates for WhatsApp support the following media types:

• Documents (pdf)
• Images (jpeg, png)
• Video (mp4)

 

Uploading a media sample

To create a template with a media header, it is required to upload a media sample file. We could use the Postman or cURL command to directly execute an SCG API call with a POST request to upload the media sample file and obtain a media “handle”. This “handle” is the SCG response after uploading the media sample file and will be used when creating the template.

 

 

When executed, SCG API response looks like:

 

The cURL command to upload the media sample is:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/external_message_templates/{WABA}/media_upload' \
-H 'int-companyId: XXXXXX' \
-H 'int-appId: XXXXX' \
-H 'int-txnId: 12345678' \
-H 'Authorization: Bearer {SCG_TOKEN}' \
-F 'file="@/c/tmp/Syn logo.jpeg"'

API response:

 % Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 369 0 208 100 161 71 55 0:00:02 0:00:02 --:--:-- 126
{"handle":"4::aW1hZ2UvanBlZw==:ARbkARUYFR0lZmjNIObxNjUHqcWUFvQcmsprNRdQo3sfEjY9z866lDfVRt04PYRK7C
7gNwVCCczm5dY_qbPUBD5zxNpPuMXCRWK0kOhDRxDyNg:e:1718114614:776163296743789:100057487373647:ARbu3Yd
k8kXkCGcOXP4"}

This handle is the reference to the media sample file and is ready for the next API call.

 

Creating the template

To create the template with an image media header, we must include an entry for header with the following syntax:

{
  "type": "HEADER",
  "format": "<FORMAT>",
  "example": {
    "header_handle": [
      "<HEADER_HANDLE>"
    ]
  }
}

Where:

FORMAT valid values are: IMAGE, VIDEO, or DOCUMENT. In this example, we will use IMAGE as we uploaded a .jpeg file.

HEADER_HANDLER must be the “handle” value we obtain from the previous step.

 

In this example:

{
  "type": "HEADER",
  "format": " IMAGE ",
  "example": {
    "header_handle": [
"4::aW1hZ2UvanBlZw==:ARbkARUYFR0lZmjNIObxNjUHqcWUFvQcmsprNRdQo3sfEjY9z866lDfVRt04PYRK7
C7gNwVCCczm5dY_qbPUBD5zxNpPuMXCRWK0kOhDRxDyNg:e:1718114614:776163296743789:100057487373647:ARbu3Y
dk8kXkCGcOXP4"
    ]
  }
}

 

The bellow script creates a template with an image media header by the SCG API call:

The API response is:

 

The cURL command to create the SCG WhatsApp template is:

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/external_message_templates/{WABA}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {SCG_TOKEN}' \
-d '{
  "language": "en_US",
  "name": "da_test_085",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "4::aW1hZ2UvanBlZw==:ARbkARUYFR0lZmjNIObxNjUHqcWUFvQcmsprNRdQo3sfEjY9z866lDfVRt04PYRK7C7gNwVCCczm5dY_qbPUBD5zxNpPuMXCRWK0kOhDRxDyNg:e:1718114614:776163296743789:100057487373647:ARbu3Ydk8kXkCGcOXP4"
        ]
      }
    },
    { "text": "Hi {{1}}, this is a message with image media header ",
      "type": "BODY",
      "example": {
        "body_text": [
          [
            "Manuel"  
          ]
        ]
      }
    }
  ]
}'

Where the response from SCG API is:

% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 369 0 208 100 161 71 55 0:00:02 0:00:02 --:--:-- 126
{"id": "389407736825003"}

 

Using the template to send a message

Once the template is approved by Meta, you could be able to send messages with it. To use the template with image media header, we must make reference to the template name:

The message in the mobile device is as follows: