Creating your first Whatsapp Message Template

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

WhatsApp approved

Includes business-initiated messages to open a conversation or messages containing external links. This needs to be approved by WhatsApp. More info 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.

Step 1: Create a project

Create project

POSThttps://nest.messagebird.one/workspaces/{workspaceId}/projects

Path parameters

workspaceId*string

Body

application/json

namestring

descriptionstring

type*Touchpoints_ProjectType (enum)

enum for all the different project types Touchpoints API supports.

chatwidgetformknowledgeBasedeepLinkchannelTemplatewebsitehtmlEmailpopup

scopeTouchpoints_ProjectScope (enum)

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.

0123

suitesarray of Touchpoints_SuiteType (enum)

Response

201404409422

Created

Body

application/json

id*string (uuid)

workspaceIdstring (uuid)

namestring

descriptionstring

typeTouchpoints_ProjectType (enum)

enum for all the different project types Touchpoints API supports.

chatwidgetformknowledgeBasedeepLinkchannelTemplatewebsitehtmlEmailpopup

scopeTouchpoints_ProjectScope (enum)

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.

0123

supportedPlatformsnullable Touchpoints_PlatformList (array of enum)

localesnullable array of Touchpoints_LocaleEnum (enum)

activeResourceIdnullable string (uuid)

draftCountnumber

pendingCountnumber

activeCountnumber

inactiveCountnumber

createdAt*string (date-time)

updatedAtnullable string (date-time)

approvedTemplateChannelsIdnullable array of string (uuid)

approvedTemplateChannelGroupIdsnullable array of string (uuid)

suitesarray of Touchpoints_SuiteType (enum)

clonedFromnullable string (uuid)

The ID of the project that this project was cloned from. This field is only present if this project was cloned from another project.

Request

JavaScriptCurl

const response = await fetch('https://nest.messagebird.one/workspaces/{workspaceId}/projects', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "chatwidget"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "type": "chatwidget",
  "scope": 0,
  "supportedPlatforms": [
    "all"
  ],
  "locales": [
    "en"
  ],
  "activeResourceId": "123e4567-e89b-12d3-a456-426614174000",
  "draftCount": 0,
  "pendingCount": 0,
  "activeCount": 0,
  "inactiveCount": 0,
  "createdAt": "2024-04-29T08:19:57.532Z",
  "updatedAt": "2024-04-29T08:19:57.532Z",
  "approvedTemplateChannelsId": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "approvedTemplateChannelGroupIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "suites": [
    "marketing"
  ],
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000"
}

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"

{
  "type": "channelTemplate",
  "name": "Test channelTemplate",
  "description": "My first project"
}

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

Step 2: Add a Channel 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

POSThttps://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates

Path parameters

workspaceId*string

projectId*string

Body

application/json

descriptionstring

defaultLocalestring

assetsnullable array of Touchpoints_Asset (one of)

stylesnullable array of Touchpoints_Style (one of)

variablesnullable array of Touchpoints_Variables (object)

deploymentsnullable array of Touchpoints_Deployment (object)

genericContentnullable array of Touchpoints_GenericContent (object)

platformContentnullable array of Touchpoints_PlatformContent (object)

supportedPlatformsnullable Touchpoints_PlatformList (array of enum)

shortLinksnullable object

Other propertiesany

Response

201400404409422

Created

Body

application/json

id*string (uuid)

projectId*string (uuid)

statusenum

draftactiveinactivepending

descriptionstring

defaultLocaleTouchpoints_LocaleEnum (enum)

afsqarazbnbgcazh-CNzh-HKzh-TWhrcsdanlenen-GBen-USetfilfifrkadeelguhahehihuidgaitjaknkkrw-RWkoky-KGlolvltmkmsmlmrnbfaplpt-BRpt-PTparorusrsksleses-ARes-ESes-MXswsvtatethtrukuruzvizu

assetsarray of Touchpoints_Asset (one of)

stylesarray of Touchpoints_Style (one of)

deploymentsarray of Touchpoints_Deployment (object)

variablesarray of Touchpoints_Variables (object)

genericContentarray of Touchpoints_GenericContent (object)

platformContentarray of Touchpoints_PlatformContent (object)

supportedPlatformsnullable Touchpoints_PlatformList (array of enum)

createdAt*string (date-time)

updatedAtstring (date-time)

isCloneableboolean

editorIdstring (uuid)

publisherIdstring (uuid)

The ID of the user that last published this ChannelTemplate.

shortLinksnullable object

clonedFromnullable string (uuid)

The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.

Request

JavaScriptCurl

const response = await fetch('https://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "defaultLocale": "en",
  "assets": [
    {
      "key": "logoUrl",
      "isDefault": false,
      "valueString": "text"
    }
  ],
  "styles": [
    {
      "key": "text",
      "valueString": "text",
      "isDefault": false
    }
  ],
  "deployments": [
    {
      "key": "whatsappCategory",
      "value": "text",
      "locale": "text",
      "platform": "text"
    }
  ],
  "variables": [
    {
      "key": "text",
      "description": "text",
      "type": "string",
      "format": "none",
      "sourceUrl": {
        "fullyReplaced": false,
        "value": "text"
      }
    }
  ],
  "genericContent": [
    {
      "locale": "en",
      "type": "text",
      "blocks": [
        {
          "id": "text",
          "reference": "text",
          "role": "text",
          "hidden": false,
          "type": "action",
          "action": {
            "type": "link",
            "id": "text",
            "reference": "text",
            "role": "text",
            "hidden": false,
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ]
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "channelGroupIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "blocks": [
        {
          "id": "text",
          "reference": "text",
          "role": "text",
          "hidden": false,
          "type": "action",
          "action": {
            "type": "link",
            "id": "text",
            "reference": "text",
            "role": "text",
            "hidden": false,
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ],
      "approvals": [
        {
          "approvalReference": "123e4567-e89b-12d3-a456-426614174000",
          "platformReference": "text",
          "platformAccountIdentifier": "text",
          "reasonCode": "whatsapp_scam",
          "reasonDescription": "text",
          "status": "pending",
          "platformStatus": "whatsapp_approved",
          "channelIds": [
            "123e4567-e89b-12d3-a456-426614174000"
          ],
          "channelGroupId": "123e4567-e89b-12d3-a456-426614174000",
          "platform": "whatsapp"
        }
      ]
    }
  ],
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2024-04-29T08:19:57.532Z",
  "updatedAt": "2024-04-29T08:19:57.532Z",
  "isCloneable": false,
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000"
}

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.

Request Payload

{
	"defaultLocale": "en",
	"genericContent": [],
	"platformContent": [
		{
			"platform": "whatsapp",
			"locale": "en",
			"blocks": [
				{
					"type": "text",
					"role": "body",
					"text": {
						"text": "Hey there!"
					},
					"id": "cbA0XdmkFDAbJiGfS41kK9"
				},
				{
					"type": "text",
					"role": "footer",
					"text": {
						"text": "Reply STOP to unsubscribe."
					},
					"id": "lA0CtTqaNO2zFz9p_Uoxo7"
				}
			],
			"type": "text",
			"channelGroupIds": [
				"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
			]
		}
	],
	"supportedPlatforms": [
		"whatsapp"
	],
	"deployments": [
		{
			"key": "whatsappTemplateName",
			"platform": "whatsapp",
			"value": "test"
		},
		{
			"key": "whatsappCategory",
			"platform": "whatsapp",
			"value": "MARKETING"
		},
		{
			"key": "whatsappAllowCategoryChange",
			"platform": "whatsapp",
			"value": "false"
		}
	]
}

Default Locale

This locale will be used as a fallback if the locale specified for content is not supported.

Generic Content

This content only applies to omnichannel templates, so no need to set it in this case.

Platform Content

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.

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.

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.

{
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "defaultLocale": "en",
    "status": "draft"
    ...

Step 3: Activate the template

Activate ChannelTemplate

PUThttps://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate

Path parameters

workspaceId*string

projectId*string

channelTemplateId*string

Response

200404422

Activated

Request

JavaScriptCurl

const response = await fetch('https://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}/activate', {
    method: 'PUT',
    headers: {},
});
const data = await response.json();

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.

Step 4: Checking the status

Get ChannelTemplate

GEThttps://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}

Path parameters

workspaceId*string

projectId*string

channelTemplateId*string

Response

200404422

OK

Body

application/json

id*string (uuid)

projectId*string (uuid)

statusenum

draftactiveinactivepending

descriptionstring

defaultLocaleTouchpoints_LocaleEnum (enum)

afsqarazbnbgcazh-CNzh-HKzh-TWhrcsdanlenen-GBen-USetfilfifrkadeelguhahehihuidgaitjaknkkrw-RWkoky-KGlolvltmkmsmlmrnbfaplpt-BRpt-PTparorusrsksleses-ARes-ESes-MXswsvtatethtrukuruzvizu

assetsarray of Touchpoints_Asset (one of)

stylesarray of Touchpoints_Style (one of)

deploymentsarray of Touchpoints_Deployment (object)

variablesarray of Touchpoints_Variables (object)

genericContentarray of Touchpoints_GenericContent (object)

platformContentarray of Touchpoints_PlatformContent (object)

supportedPlatformsnullable Touchpoints_PlatformList (array of enum)

createdAt*string (date-time)

updatedAtstring (date-time)

isCloneableboolean

editorIdstring (uuid)

publisherIdstring (uuid)

The ID of the user that last published this ChannelTemplate.

shortLinksnullable object

clonedFromnullable string (uuid)

The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.

Request

JavaScriptCurl

const response = await fetch('https://nest.messagebird.one/workspaces/{workspaceId}/projects/{projectId}/channel-templates/{channelTemplateId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "defaultLocale": "en",
  "assets": [
    {
      "key": "logoUrl",
      "isDefault": false,
      "valueString": "text"
    }
  ],
  "styles": [
    {
      "key": "text",
      "valueString": "text",
      "isDefault": false
    }
  ],
  "deployments": [
    {
      "key": "whatsappCategory",
      "value": "text",
      "locale": "text",
      "platform": "text"
    }
  ],
  "variables": [
    {
      "key": "text",
      "description": "text",
      "type": "string",
      "format": "none",
      "sourceUrl": {
        "fullyReplaced": false,
        "value": "text"
      }
    }
  ],
  "genericContent": [
    {
      "locale": "en",
      "type": "text",
      "blocks": [
        {
          "id": "text",
          "reference": "text",
          "role": "text",
          "hidden": false,
          "type": "action",
          "action": {
            "type": "link",
            "id": "text",
            "reference": "text",
            "role": "text",
            "hidden": false,
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ]
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "text",
      "channelIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "channelGroupIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "blocks": [
        {
          "id": "text",
          "reference": "text",
          "role": "text",
          "hidden": false,
          "type": "action",
          "action": {
            "type": "link",
            "id": "text",
            "reference": "text",
            "role": "text",
            "hidden": false,
            "link": {
              "text": "text",
              "url": "https://example.com"
            }
          }
        }
      ],
      "approvals": [
        {
          "approvalReference": "123e4567-e89b-12d3-a456-426614174000",
          "platformReference": "text",
          "platformAccountIdentifier": "text",
          "reasonCode": "whatsapp_scam",
          "reasonDescription": "text",
          "status": "pending",
          "platformStatus": "whatsapp_approved",
          "channelIds": [
            "123e4567-e89b-12d3-a456-426614174000"
          ],
          "channelGroupId": "123e4567-e89b-12d3-a456-426614174000",
          "platform": "whatsapp"
        }
      ]
    }
  ],
  "supportedPlatforms": [
    "all"
  ],
  "createdAt": "2024-04-29T08:19:57.532Z",
  "updatedAt": "2024-04-29T08:19:57.532Z",
  "isCloneable": false,
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000"
}

If for any reason the previous message template is rejected by Whatsapp you will see its status as inactive. In the body of the response you can find the reason for rejection:

"approvals": [
                {
                    "approvalReference": "42xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx285",
                    "channelId": null,
                    "status": "rejected",
                    "platformStatus": "whatsapp_rejected",
                    "reason": "SCAM",
                    "reasonCode": "whatsapp_scam",
                    "platformReference": "710xxxxxxxxxx30",
                    "channelGroupId": "f9xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxfa9",
                    "platformAccountIdentifier": "10xxxxxxxxxxxxx"
                }
            ]