Creating WhatsApp Message templates

Step-by-step process of creating a Whatsapp Message Template using the Touchpoints API.

To create a WhatsApp template there are multiples steps:

1. Create a Project: A project acts as an entity that houses the messaging template.

2. Retrieve a Channel Group: Templates are linked to a WABA (WhatsApp Business Account), and the channel group holds a unique ID that identifies the WABA.

3. Create a Channel Template: This step involves creating the actual messaging template that will be sent.

4. Activate the Template: This action submits the template to Meta for approval.

5. Checking the Template status: Check the current status of the template

Once the template is activate it (approved by Meta), it can be used for sending messages by following the step here.

Before starting this guide make sure you have API Access and you are using the necessary Access Policies and Roles on your Access Key.

Lets go through each of the steps in greater details.

1- Create a project

This will create a Message Template project where the WhatsApp template will be added to.

Create project

post

/workspaces/{workspaceId}/projects

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

Body

namestring

descriptionstring

typeenumrequired

enum for all the different project types Touchpoints API supports.

Options: chatwidget, form, knowledgeBase, deepLink, channelTemplate, website, htmlEmail, popup, helpcenter, adCreative, preferencecenter, landingpage

scopeenum

dictionary:

• 0 DEFAULT: This should indicate that the project is of our current scope (can be used across all BirdCRM services).
• 1 SAVED_TEMPLATE: This should indicate that the project is a saved template, meaning that it came from extending one of BirdCRM library templates. They can be used for creating other Projects, such as inline campaigns and flows content.
• 2 INLINE_MESSAGE: This should indicate that the project is an inline message, meaning that it was created from a campaign or flow using a library template or a saved template. They are linked to an specific instance of other BirdCRM services (Campaigns, Flows, etc.).
• 3 (PLATFORM_REVIEWED_TEMPLATE): This should indicate that the project is a platform reviewed template, meaning the template must go through a external platform review.

Options: 0, 1, 2, 3

tagsnullable string[]

Tags for this project

directoryIdnullable string uuid

suitesenum[]

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/projects' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"type":"chatwidget","scope":0,"tags":[null],"suites":["marketing"]}'

201

404

409

422

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "type": "chatwidget",
  "scope": 0,
  "supportedPlatforms": [
    "all"
  ],
  "activeResourceId": "123e4567-e89b-12d3-a456-426614174000",
  "draftCount": 1,
  "pendingCount": 1,
  "activeCount": 1,
  "inactiveCount": 1,
  "createdAt": "2025-02-18T20:35:18.980Z",
  "updatedAt": "2025-02-18T20:35:18.980Z",
  "metadata": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "tags": [
    "text"
  ],
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "directoryId": "123e4567-e89b-12d3-a456-426614174000",
  "locales": [
    "en"
  ],
  "approvedTemplateChannelsId": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "approvedTemplateChannelGroupIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "suites": [
    "marketing"
  ]
}

Created

To create a project, follow these steps:

1. Make a POST request to the /workspaces/{workspaceId}/projects endpoint.

2. Provide the necessary request body parameters, such as the project name, description, and type.

Message Templates are referred to as channel templates through the API. In this case, we need to set the project type to"channelTemplate"

Example request

{
    "type": "channelTemplate",
    "scope": 3,
    "name": "text_wa_1",
    "description": "My whatsapp template created via api",
    "suites": ["marketing"]
}

Key Fields	Description
scope	Select 3 as Meta requires this template to be sent for review.
suites	select the suite where this template will be used
name	Unique project name

Example response

{
    "id": "11323dfa-121f-4a4e-b4ef-35d325eaacb5",
    "name": "text_wa_1",
    "description": "My whatsapp template created via api",
    "type": "channelTemplate",
    "scope": 3,
    "supportedPlatforms": [
        "all"
    ],
    "suites": [
        "marketing"
    ],
    "draftCount": 0,
    "pendingCount": 0,
    "activeCount": 0,
    "inactiveCount": 0,
    "activeResourceId": null,
    "createdAt": "2024-09-19T17:19:04.087Z",
    "updatedAt": "2024-09-19T17:19:04.087Z"
}

Upon successful creation, you will receive a response with the details of the newly created project, including the project ID.

2- Retrieve channel group

Use the endpoint below to retrieve all channel groups associated with your WABAs. Select the channel group you wish to use for creating a template. Keep in mind that templates are linked to a specific WABA.

Get enriched Channel groups for ChannelTemplate

get

/workspaces/{workspaceId}/projects/channel-templates/channel-groups

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/workspaces/{workspaceId}/projects/channel-templates/channel-groups' \
  --header 'Authorization: Bearer jwt'

200

404

422

200

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "platformGroupName": "text",
      "platformGroupId": "text",
      "platformId": "text",
      "createdAt": "2025-02-18T20:35:18.980Z",
      "updatedAt": "2025-02-18T20:35:18.980Z",
      "channels": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "identifier": "text"
        }
      ]
    }
  ]
}

OK

Example response

    "results": [
        {
            "id": "3f979241-dea3-4f55-b7bb-d769eec27e51",
            "platformId": "whatsapp",
            "platformGroupId": "114128184961630",
            "platformGroupName": "Bird WABA",
            "channelIds": [
                "7b87eea0-631e-576d-a849-ecf58e837b6a"
            ],
            "createdAt": "2024-09-19T15:00:15.849Z",
            "updatedAt": "2024-09-19T15:00:15.849Z"
        }
    ]
}

Field	Description
id	This is the channel group ID required for future calls. It has a one-to-one relationship with your WABA.
platformGroupId	This is a WABA ID
platformGroupName	This is the WABA name
channelIds	List of channels associated to given WABA

3 - Create a Channel Template

This is the actual creation of the WhatsApp template.

You need to set up a Whatsapp Channel first before completing this step. For more info please visit our platform documentation or check the Channels API.

Create channeltemplate

post

/workspaces/{workspaceId}/projects/{projectId}/channel-templates

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

projectIdstringrequired

Body

descriptionstring

supportedPlatformsnullable enum[]

assetsnullable one of[]

stylesnullable one of[]

variablesnullable object[]

deploymentsnullable object[]

genericContentnullable object[]

platformContentnullable object[]

shortLinksnullable object

defaultLocalestring

Other propertiesany

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"supportedPlatforms":["all"],"assets":[{"key":"logoUrl"}],"styles":[{"key":"text","valueString":"text"}],"variables":[{"key":"text","type":"string","format":"none","sourceUrl":{"fullyReplaced":true,"value":"text"},"examplesLocale":{"ANY_ADDITIONAL_PROPERTY":{"exampleValueStrings":[null],"exampleValues":[{"sections":[{"title":"text","items":[{"type":"reply-action","replyAction":{"text":"text"}}]}]}]}}}],"deployments":[{"value":"text","key":"whatsappCategory","channelIds":[null]}],"genericContent":[{"locale":"en","blocks":[{"type":"action","action":{"type":"link","link":{"text":"text","url":"https://example.com"}}}]}],"platformContent":[{"locale":"en","platform":"text","channelIds":[null],"blocks":[{"type":"action","action":{"type":"link","link":{"text":"text","url":"https://example.com"}}}],"approvals":[{"approvalReference":"123e4567-e89b-12d3-a456-426614174000","platform":"whatsapp","status":"pending","reasonCode":"whatsapp_scam","platformStatus":"whatsapp_approved","channelIds":[null]}],"channelGroupIds":[null]}],"shortLinks":{},"defaultLocale":"text","ANY_ADDITIONAL_PROPERTY":"anything"}'

201

400

404

409

422

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "defaultLocale": "en",
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2025-02-18T20:35:18.980Z",
  "updatedAt": "2025-02-18T20:35:18.980Z",
  "isCloneable": true,
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherType": "text",
  "reviewInfo": {
    "status": "pending",
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "currentStep": 1
  },
  "status": "draft",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "assets": [
    {
      "key": "logoUrl"
    }
  ],
  "styles": [
    {
      "key": "text",
      "valueString": "text"
    }
  ],
  "deployments": [
    {
      "value": "text",
      "platform": "text",
      "key": "whatsappCategory",
      "locale": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "variables": [
    {
      "key": "text",
      "description": "text",
      "characterLimit": 1,
      "type": "string",
      "format": "none",
      "sourceUrl": {
        "fullyReplaced": true,
        "value": "text"
      },
      "examplesLocale": {
        "ANY_ADDITIONAL_PROPERTY": {
          "exampleValueStrings": [
            null
          ],
          "exampleValues": [
            {
              "sections": [
                {
                  "title": "text",
                  "items": [
                    {
                      "type": "reply-action",
                      "replyAction": {
                        "text": "text"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ],
  "genericContent": [
    {
      "locale": "en",
      "type": "text",
      "blocks": [
        {
          "type": "action",
          "action": {
            "type": "link",
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ]
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "blocks": [
        {
          "type": "action",
          "action": {
            "type": "link",
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ],
      "approvals": [
        {
          "approvalReference": "123e4567-e89b-12d3-a456-426614174000",
          "platform": "whatsapp",
          "status": "pending",
          "reasonCode": "whatsapp_scam",
          "platformStatus": "whatsapp_approved",
          "channelIds": [
            null
          ]
        }
      ],
      "channelGroupIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "shortLinks": {}
}

Created

Once you have created a project, you can add a channel template to it. Follow these steps:

1. Make a POST request to the /workspaces/{workspaceId}/projects/{projectId}/channel-templates endpoint.

2. Pass the project ID and other required parameters in the request.

Create a channel template example request

{
   "defaultLocale":"en",
   "platformContent":[
      {
         "platform":"whatsapp",
         "locale":"en",
         "blocks":[
            {
               "type":"text",
               "role":"header",
               "text":{
                  "text":"My header"
               }
            },
            {
               "type":"text",
               "role":"body",
               "text":{
                  "text":"Hey {{firstname}}! Bird would love for you to schedule a demo with us."
               }
            },
            {
               "type":"text",
               "role":"footer",
               "text":{
                  "text":"Reply STOP to unsubscribe."
               }
            }
         ],
         "channelGroupIds":[
            "ec4be352-af2a-45f5-b341-b90ad6091c33"
         ]
      }
   ],
   "variables":[
      {
         "type":"string",
         "key":"firstname",
         "examplesLocale":{
            "en":{
               "exampleValueStrings":[
                  "Dan"
               ]
            }
         }
      }
   ],
   "supportedPlatforms":[
      "whatsapp"
   ],
   "shortLinks":{
      "enabled":true,
      "domain":"brd1.us"
   },
   "deployments":[
      {
         "key":"whatsappTemplateName",
         "platform":"whatsapp",
         "value":"text_wa_template_1"
      },
      {
         "key":"whatsappCategory",
         "platform":"whatsapp",
         "value":"MARKETING"
      },
      {
         "key":"whatsappAllowCategoryChange",
         "platform":"whatsapp",
         "value":"false"
      }
   ]
}

Key fields	Description
defaultLocale	This locale will be used as a fallback if the locale specified for content is not supported.
platformContent	This is the content that is specific to a platform, in this case, we are adding content for Whatsapp. In the Blocks Documentation section, there is more info on the type of blocks you can add as content. Here is important to specify your channelGroupIds array with the corresponding ID. For more information about channel groups visit the Channels API reference.
variables	List of variables to be used in a template.
supportedPlatforms	Platforms where this template can be used. Since this message is just meant to be used in Whatsapp, we will just include this platform.
deployments	Information about the template used by Whatsapp on deployment. You can read more about Whatsapp templates here.
platformContent.channelGroupIds	Channel group id obtained on the previous API call which relates to yourn WABA
deployments.whatsappAllowCategoryChange	Default: false If set to true, Meta will assign a category based on their template guidelines. If omitted, the template will not be automatically categorized and may be rejected if it is deemed miscategorized.
deployments.whatsappTemplateName	This is the name of the template that will be registered with Meta

If successful, you will receive a response containing the details of the newly created channel template, including its ID. The template will have a status of Draft.

platformContent: This defines the template structure, referred to as "blocks." The structure of this object varies depending on the type of template you're creating. On the subpage, you'll find examples of different block types and their combinations.

Response

{
    "id": "34dcb086-82c7-47f2-8939-7f0057def64e",
    "projectId": "11323dfa-121f-4a4e-b4ef-35d325eaacb5",
    "defaultLocale": "en",
    "status": "draft",
    "assets": [],
    "styles": [
        ...
    ],
    "deployments": [
        {
            "key": "whatsappTemplateName",
            "locale": null,
            "platform": "whatsapp",
            "channelIds": null,
            "value": "text_wa_template_1"
        },
        {
            "key": "whatsappCategory",
            "locale": null,
            "platform": "whatsapp",
            "channelIds": null,
            "value": "MARKETING"
        },
        {
            "key": "whatsappAllowCategoryChange",
            "locale": null,
            "platform": "whatsapp",
            "channelIds": null,
            "value": "false"
        }
    ],
    "variables": [
        {
            "key": "firstname",
            "type": "string",
            "format": "none",
            "examplesLocale": {
                "en": {
                    "exampleValueStrings": [
                        "Dan"
                    ]
                }
            }
        }
    ],
    "genericContent": [],
    "platformContent": [
        {
            "locale": "en",
            "type": null,
            "platform": "whatsapp",
            "channelIds": null,
            "channelGroupIds": [
                "3f979241-dea3-4f55-b7bb-d769eec27e51"
            ],
            "blocks": [
                {
                    "type": "text",
                    "role": "header",
                    "text": {
                        "text": "My header"
                    }
                },
                {
                    "type": "text",
                    "role": "body",
                    "text": {
                        "text": "Hey {{firstname}}! Bird would love for you to schedule a demo with us"
                    }
                },
                {
                    "type": "text",
                    "role": "footer",
                    "text": {
                        "text": "Reply STOP to unsubscribe."
                    }
                }
            ]
        }
    ],
    "supportedPlatforms": [
        "whatsapp"
    ],
    "shortLinks": {
        "enabled": true,
        "domain": "brd1.us"
    },
    "createdAt": "2024-09-20T09:11:46.28Z",
    "updatedAt": "2024-09-20T09:11:46.28Z",
    "isCloneable": true,
    "editorId": "57fee30f-3e5c-41a9-9c86-70743e866c94",
    "editorType": "accesskey"
}

Key fields	Description
projectId	The project ID is required when sending a template message via channels API
status	Draft indicates the template has been created and the next step is to activate it
id	Template id. Required to be use on the next steps to activate the template

On the above screenshot we can see the recent created template on our Bird CRM UI (Message Templates).

4 - Activate template

After creating the WhatsApp Message Template, you need to activate it to make it available for use. Follow these steps:

1. Make a PUT request to the /workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate endpoint.

2. Pass the workspace ID, project ID, and channel template ID in the request URL.

3. Send the request.

If the call is successful, you will receive a 200 OK response indicating that the WhatsApp template has been submitted for approval and has a pending status. WhatsApp reviews the submitted template to ensure it complies with its guidelines. They assess factors such as the template structure, content, language, and intended use case. You can read more about this on our docs.

"status": "pending"

Please note that the exact details and procedures of the WhatsApp approval process may vary, and it's recommended to refer to WhatsApp's official documentation. If the approval is successful the message template will be marked as active and will be ready to use.

Activate ChannelTemplate

put

/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

projectIdstringrequired

channelTemplateIdstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate' \
  --header 'Authorization: Bearer jwt'

200

404

422

200

No body

Activated

Deactivate ChannelTemplate

put

/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/deactivate

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

projectIdstringrequired

channelTemplateIdstringrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/deactivate' \
  --header 'Authorization: Bearer jwt'

200

404

422

200

No body

Deactivated

5 - Checking the status

Get ChannelTemplate

get

/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}

Authorizations

useraccessKey

Path parameters

workspaceIdstringrequired

projectIdstringrequired

channelTemplateIdstringrequired

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}' \
  --header 'Authorization: Bearer jwt'

200

404

422

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "defaultLocale": "en",
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2025-02-18T20:35:18.980Z",
  "updatedAt": "2025-02-18T20:35:18.980Z",
  "isCloneable": true,
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherType": "text",
  "reviewInfo": {
    "status": "pending",
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "currentStep": 1
  },
  "status": "draft",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "assets": [
    {
      "key": "logoUrl"
    }
  ],
  "styles": [
    {
      "key": "text",
      "valueString": "text"
    }
  ],
  "deployments": [
    {
      "value": "text",
      "platform": "text",
      "key": "whatsappCategory",
      "locale": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "variables": [
    {
      "key": "text",
      "description": "text",
      "characterLimit": 1,
      "type": "string",
      "format": "none",
      "sourceUrl": {
        "fullyReplaced": true,
        "value": "text"
      },
      "examplesLocale": {
        "ANY_ADDITIONAL_PROPERTY": {
          "exampleValueStrings": [
            null
          ],
          "exampleValues": [
            {
              "sections": [
                {
                  "title": "text",
                  "items": [
                    {
                      "type": "reply-action",
                      "replyAction": {
                        "text": "text"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ],
  "genericContent": [
    {
      "locale": "en",
      "type": "text",
      "blocks": [
        {
          "type": "action",
          "action": {
            "type": "link",
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ]
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "blocks": [
        {
          "type": "action",
          "action": {
            "type": "link",
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ],
      "approvals": [
        {
          "approvalReference": "123e4567-e89b-12d3-a456-426614174000",
          "platform": "whatsapp",
          "status": "pending",
          "reasonCode": "whatsapp_scam",
          "platformStatus": "whatsapp_approved",
          "channelIds": [
            null
          ]
        }
      ],
      "channelGroupIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "shortLinks": {}
}

OK