Templates

What are templates, and how to use them

What are Templates?

Templates are exactly what they sound like, they are pre-designed message formats that businesses use for automated communication with customers.

---

First Steps

Name

• Requests must have a unique name / language pair

• name can only contain lowercase, underscore characters, and numbers

Language

• Can have multiple languages set for a template

Currently supported are en & en_Us

Catergory

Possible Values for category:

• "MARKETING"

• "AUTHENTICATION"

• "UTILITY"

When entering the initial fields, there are some things to keep in mind.

Components

A template will consist of its basic information such as name, category , etc. Its structure is determined by components . The request can have up to four objects each having a different type, either HEADER, BODY, FOOTER or BUTTONS.

You can add images, videos, and text to the HEADER

HEADER

• Optional

• Maximum of 1 tag

• Must have a format of either TEXT, DOCUMENT, IMAGE, VIDEO

• Limited to 60 Characters

• The image format will require an example image url from https://www.channel360.co.za/api/templates/upload. The url must then again be used in campaign creation as a tag.

BODY

• Required

• Can have multiple tags

• Limited to 1024 characters

FOOTER

• Optional

• Limited to 60 characters

BUTTONS

• Optional

• Limited to 25 characters

• Maximum of 1 tag

Header Parameters

Headers don't need an example property, you simply add the parameter and off you go:

{
   "type":"HEADER",
   "format":"TEXT",
   "text":"Hello {{1}}",
   "example":{
      "header_text":[
         "Pete"
      ]
   }
}

Body Parameters

Body requires an example:

{
   "type":"BODY",
   "text":"Is this your number {{1}}? We would love to give you a call!",
   "example":{
      "body_text":[
         [
            "0852345678"
         ]
      ]
   }
}

Button Parameters

Button requires an example:

 {
     "type": "BUTTONS",
     "buttons": [
     {
                "type": "URL",
                "text": "View Dashboard",
                "url": "https://channel360.co.za/organization/{{1}}",
                "example": [
                    "639700347749ed00181de224"
                ]
        }
    ]
}

Tags

Tags are used in conjunction with the component parameters. They are essentially a means to add dynamic data into the HEADER, BODY and BUTTONS.

Tags can be created for the HEAD or BODY content types

• index should start at 1 and increment up

• index of tag should match the order that you want to populate replacement tags for the HEAD / BODY / BUTTONS

Tag Structure

head: [
    {
        index: number;
        type: string;
        value?: string;
        url?: string;
        prompt?: string;
        fields?: string[]; //used for csv fields or subscriber fields depending on type
    }
];
body: [
    {
        index: number;
        type: string;
        value?: string;
        url?: string;
        prompt?: string;
        fields?: string[]; //used for csv fields or subscriber fields depending on type
    }
];
body: [
    {
        index: number;
        type: string;
        value?: string;
        url?: string;
        prompt?: string;
        fields?: string[]; //used for csv fields or subscriber fields depending on type
    }
];

Tag Fields

Field	Description	Notes
index	Indexed used to populate replacement tags in template	Head and body
type	Type of Tag (see below)	The head tags cannot be populated with a csv
value	Used to store the value for 'hard-coded/on-campaign-creation' fields
url	Used to specify the url for tag types ( csv | image, video)	The following endpoint should be used to upload any files required by templates: {{url}}/v1.1/templates/upload This endpoint returns a list of the uploaded files along with their public url which must be specified
prompt	Used to populate the prompt when assigning a value to this tag on campaign creation	Used for csv/subscriber fields
fields	Array of fields to be used for tag replacement

Tag Types

Option	Description	Notes
csv	CSV Merge file uploaded to s3 and url saved against record	populate fields with the desired field + populate url with the key returned by {url}/v1.1/templates/upload
hard-coded	Hard Coded value (setup at on template creation)	populate value field with string value
on-campaign-creation	On Campaign Creation	populate the value with the text you would like to use when passing the tags object on campaign creation
image	Image uploaded to s3 and url saved against record	populate url field with the location returned by {url}/v1.1/templates/upload
video	Image uploaded to s3 and url saved against record	populate url field with the location returned by {url}/v1.1/templates/upload
subscriber-field	Subscriber field to use for tag replacement	populate fields with the subscriber field you want to replace - currently available fields are as follows: mobileNumber, firstName, lastName

Want to upload an image?

This endpoint facilitates the uploading of an image.

Upload Image

Upload Image

API call to Upload an Image

POSThttps://www.channel360.co.za/v1.1/templates/:upload

Body

multipart/form-data

filestring

Example: "Monkey-Selfie.webp"

Response

200

Successfully Uploaded Image

Body

application/json

uploadedFilesobject

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/templates/:upload', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "uploadedFiles": {
    "fieldname": "file",
    "originalname": "Monkey-Selfie.webp",
    "encoding": "7bit",
    "mimetype": "image/webp",
    "size": 94234,
    "bucket": "channel360-template-tags",
    "key": "2022-11-14T14:36:14.607Z-Monkey-Selfie.webp",
    "acl": "private",
    "contentType": "application/octet-stream",
    "contentDisposition": "null",
    "contentEncoding": "null",
    "storageClass": "STANDARD",
    "serverSideEncryption": null,
    "metadata": {
      "fieldName": "file"
    },
    "location": "https://channel360-template-tags.channel360-template-tags.s3.af-south-1.amazonaws.com/2022-11-14T14%3A36%3A14.607Z-Monkey-Selfie.webp",
    "etag": "\"153e7972bea747b4f6d537eb0aa95714\""
  }
}

Want to upload a Template?

This endpoint facilitates the uploading of a Template.

Upload Template

Upload Template

API call to Upload a Template

POSThttps://www.channel360.co.za/v1.1/templates/upload

Body

multipart/form-data

filestring

Example: "CompanyLogo.png"

Response

200

Successfully Uploaded Template

Body

application/json

uploadedFilesobject

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/templates/upload', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "uploadedFiles": {
    "fieldname": "file",
    "originalname": "CompanyLogo.png",
    "encoding": "7bit",
    "mimetype": "image/png",
    "size": 94234,
    "bucket": "channel360-template-tags",
    "key": "2022-11-14T14:31:35.967Z-CompanyLogo.png",
    "acl": "private",
    "contentType": "application/octet-stream",
    "contentDisposition": "null",
    "contentEncoding": "null",
    "storageClass": "STANDARD",
    "serverSideEncryption": "null",
    "metadata": {
      "fieldName": "file"
    },
    "location": "https://channel360-template-tags.channel360-template-tags.s3.af-south-1.amazonaws.com/2022-11-14T14%3A31%3A35.967Z-CompanyLogo.png",
    "etag": "\"14772585a3432789898f56f26870g97987\""
  }
}

Want to ingest a Template?

This endpoint allows you to ingest and process a template.

Ingest Template

Ingest Template

API call to ingest template

POSThttps://www.channel360.co.za/v1.1/org/{orgId}/whatsapp/templates/ingest

Path parameters

orgId*string

Body

multipart/form-data

filestring

Example: "test_file"

Response

200

Successfully ingested template

Body

application/json

messageTemplatesobject

Request

JavaScriptCurlPython

const response = await fetch('https://www.channel360.co.za/v1.1/org/{orgId}/whatsapp/templates/ingest', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "messageTemplates": {
    "name": "test_file",
    "components": {
      "type": "HEADER",
      "format": "IMAGE",
      "example": [
        [
          {
            "type": "object",
            "properties": {
              "header_handle": "https://scontent.whatsapp.net/v/t61.29466-34/323056745_843799486733776_336064991092086792_n.jpg?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=bZq4rhHy8gUAX-e3Hz0&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&oh=01_AdRAgjaSHIVynENmq03ex1jkCPn64m-mo3G2rC3zQIL8TQ&oe=65846005"
            }
          },
          {
            "type": "BODY",
            "text": "test"
          },
          {
            "type": "FOOTER",
            "text": "test"
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "PHONE_NUMBER",
                "text": "Phone Number",
                "phoneNumber": "[phone]"
              },
              {
                "type": "URL",
                "text": "Url",
                "url": "https://docs.channel360.co.za/"
              }
            ]
          }
        ]
      ]
    },
    "language": "en_US",
    "status": "APPROVED",
    "category": "MARKETING",
    "id": "2907957541046"
  }
}

---

Want to get your Template approved?

The link below specifies all that needs to be known about getting your templates approved.

Get your template approved

Message Template Guidelines - WhatsApp Business Platform - Documentation - Facebook for DevelopersFacebook for Developers

Get started in

WhatsApp has rules! We cannot just make any message we want and send them off to millions of people. It must meet the criteria. Only then can we send millions of messages.