Create a template

With this API you'll be able to submit a WhatsApp template creation request to Meta. Note that a template can not be used until Meta approves it. Typically, the templates are approved within 5 minutes from the request submission but may take up to 24 hours. This might change in the future though and we'll update accordingly. You'll have to fetch the templates from time to time to get their latest status.

POST /v1/businesses/{businessId}/create/template

Path Parameters

Name	Type	Description
businessId	String

201: Created

{
    "entity": {
        "id": "template_test",
        "templates": [
            {
                "channel": null,
                "id": "1385622408844485",
                "language": {
                    "code": "en_US"
                },
                "status": "MESSAGE_TEMPLATE_STATUS_PENDING",
                "createdAt": "2023-01-18T01:07:20.075195879Z",
                "updatedAt": "2023-01-18T01:07:20.075195879Z",
                "externalTemplate": null,
                "components": [],
                "templateComponents": [
                    {
                        "header": {
                            "media": {
                                "type": "TYPE_IMAGE",
                                "example": [
                                    "https://uploads-ssl.webflow.com/60c6f467ba3a281e33bc3449/62bcc6414212753dc33b5c2d_312313.png"
                                ]
                            }
                        }
                    },
                    {
                        "body": {
                            "text": {
                                "text": "Hi {{1}}, Welcome to Connectly. Do you want to learn more?",
                                "example": [
                                    "Lorem"
                                ]
                            }
                        }
                    },
                    {
                        "footer": {
                            "text": {
                                "text": "Reply 'Stop' to opt out",
                                "example": []
                            }
                        }
                    },
                    {
                        "button": {
                            "quickReply": {
                                "text": "Learn more"
                            }
                        }
                    },
                    {
                        "button": {
                            "quickReply": {
                                "text": "Not interested"
                            }
                        }
                    }
                ],
                "rejectionReason": null
            }
        ],
        "name": "template_test3",
        "category": "MARKETING",
        "createdAt": null,
        "updatedAt": null
    }
}

200: OK

The payload is the message template object which consists of:

1. name - the name of the template

2. category - category of the template. Can be any of:

   MESSAGE_TEMPLATE_GROUP_CATEGORY_AUTHENTICATION
   MESSAGE_TEMPLATE_GROUP_CATEGORY_MARKETING
   MESSAGE_TEMPLATE_GROUP_CATEGORY_UTILITY

3. language - a language object. It only has one property called code and you can see all the supported language codes here

4. template_components - a list of the components that represent the template structure

Template Components

WhatsApp templates have media size limits. To know about them visit Meta documentation

Header

Template headers have 4 types:

1. TYPE_IMAGE - image header. You need to specify the image URL link in example to increase the template approval speed

2. TYPE_VIDEO - video header. You need to specify the video URL link in example to increase the template approval speed

3. TYPE_DOCUMENT - document header. You need to specify the document URL link in example to increase the template approval speed

4. TYPE_TEXT - text header. If you want to specify the dynamic text content in the header you can do so like this {{1}}. ONLY ONE VARIABLE IS ALLOWED IN THE HEADER.

Body

In the body component, you specify the template's main text content.

The template body supports the variables. These are dynamic fields that can be replaced with different text values when you send out the templates. See here for information on how to send the templated messages.

If you want to specify the variable in the template body, use the following syntax:

{{1}} # just one variable
{{1}} {{2}} # two variables
{{1}} {{2}} {{3}} # three variables
{{1}} {{2}} {{3}} {{4}} # four variables
# and etc

Whenever you specify the number wrapped around the curly braces (e.g {{1}}), you indicate it is a variable.

The variables must be numerated from 1-15 For example, if you have 4 variables their numbers must be strictly increasing with each. We do not allow duplicates in the variable numbers and you can not skip the number.

Footer

The message template footer.

Button

The buttons are interactive components that you use to interact with your recipients.

You can use up to 3 buttons per template.

There are two types of buttons supported on the templates:

1. quickReply - when a Quick Reply button is tapped, a message containing the button text is sent in the conversation. Quick Reply buttons can trigger auto responses.

2. url - take your customers to your website. WhatsApp automatically disapproves shortened links (eg. bit.ly). Please use the full URL and add UTM parameters if required for tracking.

3. phoneNumber - allow your customers to call you directly.

Note that you can't have Quick Reply and Call-To-Action buttons simultaneously(up to 3 quick reply buttons OR call to action with either URL and/or phone)

Examples

Simple Template with a body and no variables

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "example text"
          }
        }
      }
    ]
}

Simple Template with a body with one variable

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "Hi {{1}}, this example text with variable"
          }
        }
      }
    ]
}

Simple Template with a body with 4 variables

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "example text {{1}} and {{2}} and {{3}} and {{4}}"
          }
        }
      }
    ]
}

Template with an image header and body varaibles

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "header": {
          "media": {
            "type": "TYPE_IMAGE",
            "example": [
              "https://cdn.connectly.ai/3776/3776db4b-f5ef-4099-9089-82646ddbd1a0"
            ]
          }
        }
      },
      {
        "body": {
          "text": {
            "text": "example text with variable {{1}}."
          }
        }
      }
    ]
}

Template with text header and body variables

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "header": {
          "text": {
            "text": "hello {{1}} !"
          }
        }
      },
      {
        "body": {
          "text": {
            "text": "example text with variable {{1}}."
          }
        }
      }
    ]
}

Template with a document header, footer, and no variables

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "header": {
          "media": {
            "type": "TYPE_DOCUMENT",
            "example": [
              "https://cdn.connectly.ai/64c2/64c28f21-b25e-4ee2-bc20-da6aa3d73347"
            ]
          }
        }
      },
      {
        "body": {
          "text": {
            "text": "sample text"
          }
        }
      },
      {
        "footer": {
          "text": {
            "text": "sample text"
          }
        }
      }
    ]
}

Template with a quick reply button

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "hello"
          }
        }
      },
      {
        "button": {
          "quickReply": {
            "text": "1"
          }
        }
      },
      {
        "button": {
          "quickReply": {
            "text": "2"
          }
        }
      }
    ]
}

Template with a CTA button that leads to the website

we can add variable in url, e.g www.example.com/{{1}}

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "hello"
          }
        }
      },
      {
        "button": {
          "url": {
            "text": "site",
            "url": "www.example.com"
          }
        }
      }
    ]
}

Template with a CTA button that starts a phone call

{
    "name": "<TEMPLATE_NAME>",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "body": {
          "text": {
            "text": "hello"
          }
        }
      },
      {
        "button": {
          "phoneNumber": {
            "text": "call us!",
            "phoneNumber": "[phone]"
          }
        }
      }
    ]
}

Carousel template

To create this carousel template:

You can use this structure:

{
    "name": "carousel_demo_1",
    "language": {
        "code": "en_US"
    },
    "category": "MESSAGE_TEMPLATE_GROUP_CATEGORY_MARKETING",
    "template_components": [
        {
            "body": {
                "text": {
                    "text": "Hey there! 👋 We heard you're interested in some fresh, delicious fruits 🍎🍇"
                }
            }
        },
        {
            "carousel": {
                "cards": [
                    {
                        "components": [
                            {
                                "header": {
                                    "media": {
                                        "type": "TYPE_IMAGE",
                                        "example": [
                                            "https://i.ibb.co/yB7pCHDs/2025-02-20-16-38.png"
                                        ]
                                    }
                                }
                            },
                            {
                                "body": {
                                    "text": {
                                        "text": "These fruits are packed with goodness and perfect for you, {{1}}! 🍓🍊"
                                    }
                                }
                            },
                            {
                                "button": {
                                    "url": {
                                        "text": "Check them out in our store",
                                        "url": "https://connectly.ai/example/store/item/{{1}}"
                                    }
                                }
                            },
                            {
                                "button": {
                                    "quickReply": {
                                        "text": "Want to see more?"
                                    }
                                }
                            }
                        ]
                    },
                    {
                        "components": [
                            {
                                "header": {
                                    "media": {
                                        "type": "TYPE_IMAGE",
                                        "example": [
                                            "https://i.ibb.co/nM0rYxBj/2025-02-20-16-38-1.png"
                                        ]
                                    }
                                }
                            },
                            {
                                "body": {
                                    "text": {
                                        "text": "For just {{1}}, you can unlock some amazing fruit coupons! 🍏🎉"
                                    }
                                }
                            },
                            {
                                "button": {
                                    "url": {
                                        "text": "Grab your coupons here",
                                        "url": "https://connectly.ai/example/subscribe/{{1}}"
                                    }
                                }
                            },
                            {
                                "button": {
                                    "quickReply": {
                                        "text": "Want to explore more?"
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

To send that template as a WhatsApp message, see Sending a Carousel template message

Template

Below is a sample request:

{
    "name": "template_test",
    "language": {
        "code": "en_US"
    },
    "template_components": [
      {
        "header": {
          "media": {
            "type": "TYPE_IMAGE",
            "example": [
              "https://uploads-ssl.webflow.com/60c6f467ba3a281e33bc3449/62bcc6414212753dc33b5c2d_312313.png"
            ]
          }
        }
      },
      {
        "body": {
          "text": {
            "text": "Hi {{1}}, Welcome to Connectly. Do you want to learn more?"
          }
        }
      },
      {
        "footer": {
          "text": {
            "text": "Reply 'Stop' to opt out"
          }
        }
      },
      {
        "button": {
          "quickReply": {
            "text": "Learn more"
          }
        }
      },
      {
        "button": {
          "quickReply": {
            "text": "Not interested"
          }
        }
      }
    ]
}

If successfully accepted, the above request will return 200 with the following response:

{
    "entity": {
        "id": "template_test",
        "templates": [
            {
                "channel": null,
                "id": "1385622408844485",
                "language": {
                    "code": "en_US"
                },
                "status": "MESSAGE_TEMPLATE_STATUS_PENDING",
                "createdAt": "2023-01-18T01:07:20.075195879Z",
                "updatedAt": "2023-01-18T01:07:20.075195879Z",
                "externalTemplate": null,
                "components": [],
                "templateComponents": [
                    {
                        "header": {
                            "media": {
                                "type": "TYPE_IMAGE",
                                "example": [
                                    "https://uploads-ssl.webflow.com/60c6f467ba3a281e33bc3449/62bcc6414212753dc33b5c2d_312313.png"
                                ]
                            }
                        }
                    },
                    {
                        "body": {
                            "text": {
                                "text": "Hi {{1}}, Welcome to Connectly. Do you want to learn more?",
                                "example": [
                                    "Lorem"
                                ]
                            }
                        }
                    },
                    {
                        "footer": {
                            "text": {
                                "text": "Reply 'Stop' to opt out",
                                "example": []
                            }
                        }
                    },
                    {
                        "button": {
                            "quickReply": {
                                "text": "Learn more"
                            }
                        }
                    },
                    {
                        "button": {
                            "quickReply": {
                                "text": "Not interested"
                            }
                        }
                    }
                ],
                "rejectionReason": null
            }
        ],
        "name": "template_test3",
        "category": "MARKETING",
        "createdAt": null,
        "updatedAt": null
    }
}