No-code docs
Resources

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
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
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"]}'
{
  "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-18T22:07:06.345Z",
  "updatedAt": "2025-02-18T22:07:06.345Z",
  "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
Path parameters
workspaceIdstringrequired
Responses
curl -L \
  --url '/workspaces/{workspaceId}/projects/channel-templates/channel-groups' \
  --header 'Authorization: Bearer jwt'
{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "platformGroupName": "text",
      "platformGroupId": "text",
      "platformId": "text",
      "createdAt": "2025-02-18T22:07:06.345Z",
      "updatedAt": "2025-02-18T22:07:06.345Z",
      "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
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
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"}'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "defaultLocale": "en",
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2025-02-18T22:07:06.345Z",
  "updatedAt": "2025-02-18T22:07:06.345Z",
  "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
Path parameters
workspaceIdstringrequired
projectIdstringrequired
channelTemplateIdstringrequired
Responses
curl -L \
  --request PUT \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate' \
  --header 'Authorization: Bearer jwt'
No body

Activated

Deactivate ChannelTemplate

put

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

Authorizations
Path parameters
workspaceIdstringrequired
projectIdstringrequired
channelTemplateIdstringrequired
Responses
curl -L \
  --request PUT \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/deactivate' \
  --header 'Authorization: Bearer jwt'
No body

Deactivated

5 - Checking the status

Get ChannelTemplate

get

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

Authorizations
Path parameters
workspaceIdstringrequired
projectIdstringrequired
channelTemplateIdstringrequired
Responses
curl -L \
  --url '/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}' \
  --header 'Authorization: Bearer jwt'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "defaultLocale": "en",
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2025-02-18T22:07:06.345Z",
  "updatedAt": "2025-02-18T22:07:06.345Z",
  "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

Last updated

Was this helpful?