WhatsApp Templates

The WhatsApp template endpoint offers a way for you to manage your WhatsApp channel-specific templates that can be used with the Conversation API. The WhatsApp templates are a requirement to send the initial outbound messages in the WhatsApp API.

List all templates in project GA

Returns a paginated list of templates for the specified project. If no page token is supplied then the first 50 templates are returned in alphabetical order.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId

required

string

The unique ID of the project. You can find this on the Sinch Dashboard.

query Parameters

pageToken	string The page token if retrieving the next page from a previous query.
pageSize	number [ 1 .. 100 ] The page size requested.
fieldMask	Array of strings (WhatsappTemplateDtoFieldMaskPathsEnum) Field masks are a way for API callers to list the fields that a request should return. Items Enum: "whatsappId" "state" "name" "language" "category" "rejectionCode" "qualityScore" "changes" "changes.status" "changes.allowCategoryChange" "changes.details" "changes.details.components" "changes.details.components.0.type" "changes.details.components.0.format" "changes.details.components.0.text" "changes.details.components.0.example" "changes.details.components.0.example.url" "changes.details.components.0.examples" "changes.details.components.0.addSecurityRecommendation" "changes.details.components.0.codeExpirationMinutes" "changes.details.components.0.buttons" "changes.details.components.0.buttons.0.type" "changes.details.components.0.buttons.0.text" "changes.details.components.0.buttons.0.phoneNumber" "changes.details.components.0.buttons.0.url" "changes.details.components.0.buttons.0.example" "changes.details.components.0.buttons.0.otpType" "changes.details.components.0.buttons.0.autofillText" "changes.details.components.0.buttons.0.packageName" "changes.details.components.0.buttons.0.signatureHash" "changes.details.messageSendTtlSeconds" "details" "details.components" "details.components.0.type" "details.components.0.format" "details.components.0.text" "details.components.0.example" "details.components.0.example.url" "details.components.0.examples" "details.components.0.addSecurityRecommendation" "details.components.0.codeExpirationMinutes" "details.components.0.buttons" "details.components.0.buttons.0.type" "details.components.0.buttons.0.text" "details.components.0.buttons.0.phoneNumber" "details.components.0.buttons.0.url" "details.components.0.buttons.0.example" "details.components.0.buttons.0.otpType" "details.components.0.buttons.0.autofillText" "details.components.0.buttons.0.packageName" "details.components.0.buttons.0.signatureHash" "details.messageSendTtlSeconds" "analytics" "analytics.0.sent" "analytics.0.delivered" "analytics.0.read" "analytics.0.start" "analytics.0.end" "analytics.0.buttons" "analytics.0.buttons.0.type" "analytics.0.buttons.0.content" "analytics.0.buttons.0.clicks"
filterStates	Array of strings (WhatsappTemplateStatesEnum) Optionally query for sender by states. Items Enum: "APPROVED" "DISABLED" "PAUSED" "REJECTED"
filterStatuses	Array of strings (WhatsappTemplateStatusesEnum) Optionally query for sender by statuses. Items Enum: "DRAFT" "IN_PROGRESS" "REJECTED"
templateAnalyticsDateRange	string (WhatsappTemplateAnalyticsDateRangesEnum) The date range to retrieve template analytics for. Fallback to DAY if none is set. Enum: "DAY" "MONTH" "QUARTER" "WEEK"
templateName	string Optionally query for template by name. Will return all templates with names that begin with the query string.

Responses

200

List of templates

Response Schema: application/json

One of:

totalSize required	number Total size of the entries matching the search query.
pageSize required	number Requested size of the page.
required	Array of objects (WhatsappTemplateDto)
previousPageToken	string Encoded token to use in list request to fetch previous batch of entries.
nextPageToken	string Encoded token to use in list request to fetch next batch of entries.

400

BadRequest

401

Unauthorized

500

InternalServerError

get/v1/projects/{projectId}/whatsapp/templates

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

{"totalSize": 0,
"pageSize": 0,
"previousPageToken": "string",
"nextPageToken": "string",
"templates": [{"whatsappId": "string",
"state": "APPROVED",
"name": "string",
"language": "AF",
"category": "AUTHENTICATION",
"rejectionCode": "ABUSIVE_CONTENT",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"allowCategoryChange": true,
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
}
},
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
},
"analytics": [{"sent": 0,
"delivered": 0,
"read": 0,
"start": "string",
"end": "string",
"buttons": [{"type": "QUICK_REPLY",
"content": "string",
"clicks": 0
}
]
}
]
}
]
}

Create a template in project GA

Creates a new template with the request data. If the status field is set to submit the template will be created immediately, otherwise it will be saved as a draft.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId

required

string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json
required

Template data

name required	string <= 512 characters ^[a-z0-9][a-z0-9_]*[a-z0-9]$
language required	string Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU"
category required	string Enum: "AUTHENTICATION" "MARKETING" "UTILITY"
required	object 'Template input details and information.' Not required for draft.
status	string Default: "SUBMIT" Create as draft or submit. Defaults to submit. Enum: "DRAFT" "SUBMIT"
saveDraftOnFailure	boolean Default: false Flag to save template as draft if submission fails. Defaults to false.
allowCategoryChange	boolean Default: false True if Meta should be allowed to change the category if they determine the category is wrong. If false, Meta might reject the template if they determine the category is wrong based on the template contents. Defaults to false.

Responses

201

Created template

Response Schema: application/json

name required	string
language required	string Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"
category required	string Enum: "AUTHENTICATION" "MARKETING" "UTILITY" "UNRECOGNIZED"
required	Array of objects (WhatsappTemplateAnalyticsDto) Template analytics.
whatsappId	string
state	string Enum: "APPROVED" "DISABLED" "PAUSED" "REJECTED"
rejectionCode	string Rejection code if template is in status 'REJECTED' Enum: "ABUSIVE_CONTENT" "INCORRECT_CATEGORY" "INVALID_FORMAT" "NONE" "SCAM" "UNRECOGNIZED"
qualityScore	string Quality score of the HSM. Enum: "QUALITY_SCORE_GREEN" "QUALITY_SCORE_RED" "QUALITY_SCORE_YELLOW" "QUALITY_SCORE_UNKNOWN" "UNRECOGNIZED"
	object Object containing changes on the template. If empty the changes has been approved and applied to the template.
	object Template details and information.

400

BadRequest

401

Unauthorized

409

Conflict

424

FailedDependency

429

TooManyRequests

500

InternalServerError

Callbacks

postWhatsApp Template received a comment

postWhatsApp Template approved

postWhatsApp Template rejected

postWhatsApp Template status updated

postWhatsApp Template deleted

postWhatsApp Template quality score updated

postWhatsApp Template category updated

postWhatsApp Template category coming update

post/v1/projects/{projectId}/whatsapp/templates

Request samples

application/json

Minimum body to create a template.

{"name": "my_template",
"category": "AUTHENTICATION",
"language": "EN",
"details": {"components": [{"type": "HEADER",
"format": "LOCATION"
},
{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
}
}

Response samples

application/json

Response when successfully creating a template.

{"name": "My WhatsApp Template",
"category": "UTILITY",
"language": "EN_US",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "HEADER",
"format": "LOCATION"
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
},
"analytics": [ ]
}
}

Callback payload samples

application/json

{"type": "WHATSAPP_TEMPLATE_COMMENT_ADDED",
"payload": {"name": "My WhatsApp Template",
"category": "UTILITY",
"language": "EN_US",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "HEADER",
"format": "LOCATION"
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
},
"analytics": [ ]
}
}
}

List all templates for a specific name GA

Returns a paginated list of templates for the specified project and name. If no page token is supplied then the first 50 templates are returned in alphabetical order.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query

query Parameters

pageToken	string The page token if retrieving the next page from a previous query.
pageSize	number [ 1 .. 100 ] The page size requested.
fieldMask	Array of strings (WhatsappTemplateDtoFieldMaskPathsEnum) Field masks are a way for API callers to list the fields that a request should return. Items Enum: "whatsappId" "state" "name" "language" "category" "rejectionCode" "qualityScore" "changes" "changes.status" "changes.allowCategoryChange" "changes.details" "changes.details.components" "changes.details.components.0.type" "changes.details.components.0.format" "changes.details.components.0.text" "changes.details.components.0.example" "changes.details.components.0.example.url" "changes.details.components.0.examples" "changes.details.components.0.addSecurityRecommendation" "changes.details.components.0.codeExpirationMinutes" "changes.details.components.0.buttons" "changes.details.components.0.buttons.0.type" "changes.details.components.0.buttons.0.text" "changes.details.components.0.buttons.0.phoneNumber" "changes.details.components.0.buttons.0.url" "changes.details.components.0.buttons.0.example" "changes.details.components.0.buttons.0.otpType" "changes.details.components.0.buttons.0.autofillText" "changes.details.components.0.buttons.0.packageName" "changes.details.components.0.buttons.0.signatureHash" "changes.details.messageSendTtlSeconds" "details" "details.components" "details.components.0.type" "details.components.0.format" "details.components.0.text" "details.components.0.example" "details.components.0.example.url" "details.components.0.examples" "details.components.0.addSecurityRecommendation" "details.components.0.codeExpirationMinutes" "details.components.0.buttons" "details.components.0.buttons.0.type" "details.components.0.buttons.0.text" "details.components.0.buttons.0.phoneNumber" "details.components.0.buttons.0.url" "details.components.0.buttons.0.example" "details.components.0.buttons.0.otpType" "details.components.0.buttons.0.autofillText" "details.components.0.buttons.0.packageName" "details.components.0.buttons.0.signatureHash" "details.messageSendTtlSeconds" "analytics" "analytics.0.sent" "analytics.0.delivered" "analytics.0.read" "analytics.0.start" "analytics.0.end" "analytics.0.buttons" "analytics.0.buttons.0.type" "analytics.0.buttons.0.content" "analytics.0.buttons.0.clicks"
templateAnalyticsDateRange	string (WhatsappTemplateAnalyticsDateRangesEnum) The date range to retrieve template analytics for. Fallback to DAY if none is set. Enum: "DAY" "MONTH" "QUARTER" "WEEK"

Responses

200

List of templates with the same name

Response Schema: application/json

One of:

totalSize required	number Total size of the entries matching the search query.
pageSize required	number Requested size of the page.
required	Array of objects (WhatsappTemplateDto)
previousPageToken	string Encoded token to use in list request to fetch previous batch of entries.
nextPageToken	string Encoded token to use in list request to fetch next batch of entries.

400

BadRequest

401

Unauthorized

404

NotFound

500

InternalServerError

get/v1/projects/{projectId}/whatsapp/templates/{templateName}

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

{"totalSize": 0,
"pageSize": 0,
"previousPageToken": "string",
"nextPageToken": "string",
"templates": [{"whatsappId": "string",
"state": "APPROVED",
"name": "string",
"language": "AF",
"category": "AUTHENTICATION",
"rejectionCode": "ABUSIVE_CONTENT",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"allowCategoryChange": true,
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
}
},
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
},
"analytics": [{"sent": 0,
"delivered": 0,
"read": 0,
"start": "string",
"end": "string",
"buttons": [{"type": "QUICK_REPLY",
"content": "string",
"clicks": 0
}
]
}
]
}
]
}

Delete template by name GA

Delete template that matches the name. If message templates with the same name exists in multiple languages, all those templates will also be deleted. Once deleted the name can not be used for new message templates for 30 days. Use a different name to create future templates during that time period. Messages that have been sent with the deleted template, but not yet delivered, will be attempted to be deliver for 30 days from the time of the message.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query

Responses

204

Template(s) deleted

400

BadRequest

401

Unauthorized

404

NotFound

429

TooManyRequests

500

InternalServerError

delete/v1/projects/{projectId}/whatsapp/templates/{templateName}

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

{"errorCode": "project_not_initialized",
"message": "Project not initialized for WhatsApp.",
"resolution": "Verify that the project ID is correct and that it has been onboarded for WhatsApp."
}

Get template in project GA

Returns a template for a project, with the specified name and language.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

query Parameters

fieldMask

Array of strings (WhatsappTemplateDtoFieldMaskPathsEnum)

Field masks are a way for API callers to list the fields that a request should return.

Items Enum: "whatsappId" "state" "name" "language" "category" "rejectionCode" "qualityScore" "changes" "changes.status" "changes.allowCategoryChange" "changes.details" "changes.details.components" "changes.details.components.0.type" "changes.details.components.0.format" "changes.details.components.0.text" "changes.details.components.0.example" "changes.details.components.0.example.url" "changes.details.components.0.examples" "changes.details.components.0.addSecurityRecommendation" "changes.details.components.0.codeExpirationMinutes" "changes.details.components.0.buttons" "changes.details.components.0.buttons.0.type" "changes.details.components.0.buttons.0.text" "changes.details.components.0.buttons.0.phoneNumber" "changes.details.components.0.buttons.0.url" "changes.details.components.0.buttons.0.example" "changes.details.components.0.buttons.0.otpType" "changes.details.components.0.buttons.0.autofillText" "changes.details.components.0.buttons.0.packageName" "changes.details.components.0.buttons.0.signatureHash" "changes.details.messageSendTtlSeconds" "details" "details.components" "details.components.0.type" "details.components.0.format" "details.components.0.text" "details.components.0.example" "details.components.0.example.url" "details.components.0.examples" "details.components.0.addSecurityRecommendation" "details.components.0.codeExpirationMinutes" "details.components.0.buttons" "details.components.0.buttons.0.type" "details.components.0.buttons.0.text" "details.components.0.buttons.0.phoneNumber" "details.components.0.buttons.0.url" "details.components.0.buttons.0.example" "details.components.0.buttons.0.otpType" "details.components.0.buttons.0.autofillText" "details.components.0.buttons.0.packageName" "details.components.0.buttons.0.signatureHash" "details.messageSendTtlSeconds" "analytics" "analytics.0.sent" "analytics.0.delivered" "analytics.0.read" "analytics.0.start" "analytics.0.end" "analytics.0.buttons" "analytics.0.buttons.0.type" "analytics.0.buttons.0.content" "analytics.0.buttons.0.clicks"

Responses

200

Template

Response Schema: application/json

One of:

name required	string
language required	string Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"
category required	string Enum: "AUTHENTICATION" "MARKETING" "UTILITY" "UNRECOGNIZED"
required	Array of objects (WhatsappTemplateAnalyticsDto) Template analytics.
whatsappId	string
state	string Enum: "APPROVED" "DISABLED" "PAUSED" "REJECTED"
rejectionCode	string Rejection code if template is in status 'REJECTED' Enum: "ABUSIVE_CONTENT" "INCORRECT_CATEGORY" "INVALID_FORMAT" "NONE" "SCAM" "UNRECOGNIZED"
qualityScore	string Quality score of the HSM. Enum: "QUALITY_SCORE_GREEN" "QUALITY_SCORE_RED" "QUALITY_SCORE_YELLOW" "QUALITY_SCORE_UNKNOWN" "UNRECOGNIZED"
	object Object containing changes on the template. If empty the changes has been approved and applied to the template.
	object Template details and information.

400

BadRequest

401

Unauthorized

404

NotFound

500

InternalServerError

get/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

{"whatsappId": "string",
"state": "APPROVED",
"name": "string",
"language": "AF",
"category": "AUTHENTICATION",
"rejectionCode": "ABUSIVE_CONTENT",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"allowCategoryChange": true,
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
}
},
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "string",
"example": "string"
}
],
"messageSendTtlSeconds": 0
},
"analytics": [{"sent": 0,
"delivered": 0,
"read": 0,
"start": "string",
"end": "string",
"buttons": [{"type": "QUICK_REPLY",
"content": "string",
"clicks": 0
}
]
}
]
}

Delete template draft for project GA

Delete a template draft. Please note that it is only possible to delete templates that have not yet been submitted to WhatsApp.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

Responses

204

Template draft deleted.

400

BadRequest

401

Unauthorized

404

NotFound

409

Conflict

500

InternalServerError

delete/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

{"errorCode": "project_not_initialized",
"message": "Project not initialized for WhatsApp.",
"resolution": "Verify that the project ID is correct and that it has been onboarded for WhatsApp."
}

Update a template in project GA

Updates a template DRAFT.

Note that it is not possible to update all fields for a template, if you want to update a field that is not supported you will need to delete the draft and create a new one.

Update a template REJECTED / APPROVED / PAUSED / DISABLED

It is possible to update templates that have been rejected, approved, paused or disabled, we will automatically set the status to draft when update a rejected template.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

Request Body schema: application/json
required

Supported template fields to update.

status	string Default: "DRAFT" Create as draft or submit. Defaults to draft. Enum: "DRAFT" "SUBMIT"
category	string Works if status template is DRAFT or it was rejected with INCORRECT_CATEGORY. Enum: "AUTHENTICATION" "MARKETING" "UTILITY"
allowCategoryChange	boolean Default: false Works if status template is DRAFT or it was rejected with INCORRECT_CATEGORY True if Meta should be allowed to change the category if they determine the category is wrong. If false, Meta might reject the template if they determine the category is wrong based on the template contents. Defaults to false.
	object 'Template input details and information.' Not required for draft.

Responses

200

Updated template draft.

Response Schema: application/json

name required	string
language required	string Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"
category required	string Enum: "AUTHENTICATION" "MARKETING" "UTILITY" "UNRECOGNIZED"
required	Array of objects (WhatsappTemplateAnalyticsDto) Template analytics.
whatsappId	string
state	string Enum: "APPROVED" "DISABLED" "PAUSED" "REJECTED"
rejectionCode	string Rejection code if template is in status 'REJECTED' Enum: "ABUSIVE_CONTENT" "INCORRECT_CATEGORY" "INVALID_FORMAT" "NONE" "SCAM" "UNRECOGNIZED"
qualityScore	string Quality score of the HSM. Enum: "QUALITY_SCORE_GREEN" "QUALITY_SCORE_RED" "QUALITY_SCORE_YELLOW" "QUALITY_SCORE_UNKNOWN" "UNRECOGNIZED"
	object Object containing changes on the template. If empty the changes has been approved and applied to the template.
	object Template details and information.

400

BadRequest

401

Unauthorized

404

NotFound

409

Conflict

424

FailedDependency

429

TooManyRequests

500

InternalServerError

Callbacks

postWhatsApp Template received a comment

postWhatsApp Template approved

postWhatsApp Template rejected

postWhatsApp Template status updated

postWhatsApp Template deleted

postWhatsApp Template quality score updated

postWhatsApp Template category updated

postWhatsApp Template category coming update

patch/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}

Request samples

application/json

Example body request to update a template.

{"details": {"components": [{"type": "HEADER",
"format": "LOCATION"
},
{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
}
}

Response samples

application/json

Response when successfully update a template.

{"whatsappId": "123456",
"name": "My WhatsApp Template",
"state": "APPROVED",
"category": "UTILITY",
"language": "EN_US",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "HEADER",
"format": "LOCATION"
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
}
},
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
}
],
"messageSendTtlSeconds": 60
},
"analytics": [ ]
}

Callback payload samples

application/json

{"type": "WHATSAPP_TEMPLATE_COMMENT_ADDED",
"payload": {"name": "My WhatsApp Template",
"category": "UTILITY",
"language": "EN_US",
"qualityScore": "QUALITY_SCORE_GREEN",
"changes": {"status": "DRAFT",
"details": {"components": [{"type": "HEADER",
"format": "TEXT",
"text": "Save {{1}}% on your next purchase!",
"example": "20"
},
{"type": "HEADER",
"format": "DOCUMENT",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "HEADER",
"format": "LOCATION"
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
],
"addSecurityRecommendation": true
},
{"type": "FOOTER",
"text": "To track your order please click the 'Track Your Order' button",
"codeExpirationMinutes": 5
},
{"type": "BUTTONS",
"buttons": [{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
},
{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "OTP",
"otpType": "COPY_CODE",
"text": "Example text."
}
]
},
{"type": "CAROUSEL",
"cards": [{"components": [{"type": "HEADER",
"format": "IMAGE",
"example": {"url": "https://example.com/photos/1.png"
}
},
{"type": "BODY",
"text": "Good morning {{1}}, your package has arrived.",
"examples": ["Mr. Smith"
]
},
{"type": "BUTTONS",
"buttons": [{"type": "URL",
"text": "Example test",
"url": "https://www.my-website.com?name={{1}}",
"example": "https://www.my-website.com?name=john"
},
{"type": "QUICK_REPLY",
"text": "Track Your Order"
},
{"type": "PHONE_NUMBER",
"text": "Example text.",
"phoneNumber": "+48 777 777777"
}
]
}
]
}
]
}
],
"messageSendTtlSeconds": 60
}
},
"analytics": [ ]
}
}

Lists activities on project template GA

Paginated list of activities for a template. Ordered from the most recent one to the oldest one.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

query Parameters

pageToken	string The page token if retrieving the next page from a previous query.
pageSize	number [ 1 .. 100 ] The page size requested.

Responses

200

Recent activities on template.

Response Schema: application/json

totalSize required	number Total size of the entries matching the search query.
pageSize required	number Requested size of the page.
required	Array of objects (WhatsappTemplateNotificationDto)
previousPageToken	string Encoded token to use in list request to fetch previous batch of entries.
nextPageToken	string Encoded token to use in list request to fetch next batch of entries.

400

BadRequest

401

Unauthorized

404

NotFound

500

InternalServerError

get/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}/activities

Request samples

Node.js
C#
Java
Python
curl

Response samples

application/json

Response for all template activities.

{"totalSize": 2,
"pageSize": 50,
"notifications": [{"type": "CREATED",
"created": "2023-01-19T13:11:08.204Z",
"author": "Provisioning API user"
},
{"type": "COMMENT_ADDED",
"created": "2023-01-19T13:11:08.204Z",
"comment": "Example comment",
"author": "Provisioning API user"
}
]
}

Creates a comment for a template GA

Creates a comment for a template.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

Request Body schema: application/json
required

Comment data

comment

required

string [ 1 .. 65535 ] characters

Responses

201

Created comment for a template.

Response Schema: application/json

type required	string Value: "CREATED"
comment required	string
created	string

400

BadRequest

401

Unauthorized

404

NotFound

500

InternalServerError

post/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}/comments

Request samples

application/json

Example body request to create a comment.

{"comment": "Example comment."
}

Response samples

application/json

Response when successfully creating a comment.

{"type": "CREATED",
"comment": "Example comment",
"created": "2023-01-19T13:11:08.204Z"
}

Compare two templates GA

Compare two templates.

SecurityBasic or OAuth2.0

Request

path Parameters

projectId required	string The unique ID of the project. You can find this on the Sinch Dashboard.
templateName required	string The name of the template to query
languageCode required	string (WhatsappTemplateLanguagesEnum) The language code of the specific template. Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"

Request Body schema: application/json
required

Compare data

required	Array of objects (WhatsappInputTemplateCompareIdentifierDto) = 1 items List of templates
timeframe	string Default: "7" Timeframes are limited to 7, 30, 60 and 90 day lookbacks from the time of the request Enum: "30" "60" "7" "90"
endTimestamp	number <timestamp> Default: 1743420093561 End of timeframe

Responses

200

Compared template response.

Response Schema: application/json

required

Array of objects (WhatsappTemplateCompareIdentifierDto)

List of templates

Array

name required	string Template name
language required	string Template language Enum: "AF" "AR" "AZ" "BG" "BN" "CA" "CS" "DA" "DE" "EL" "EN" "EN_GB" "EN_US" "ES" "ES_AR" "ES_ES" "ES_MX" "ET" "FA" "FI" "FIL" "FR" "GA" "GU" "HA" "HE" "HI" "HR" "HU" "ID" "IT" "JA" "KA" "KK" "KN" "KO" "KY_KG" "LO" "LT" "LV" "MK" "ML" "MR" "MS" "NB" "NL" "PA" "PL" "PT_BR" "PT_PT" "RO" "RU" "RW_RW" "SK" "SL" "SQ" "SR" "SV" "SW" "TA" "TE" "TH" "TR" "UK" "UR" "UZ" "VI" "ZH_CN" "ZH_HK" "ZH_TW" "ZU" "UNRECOGNIZED"
blockOrder required	number Order of block rate
messageSends required	number Message send number
topBlockReason required	string Block reason Enum: "NO_LONGER_NEEDED" "NO_REASON" "NO_REASON_GIVEN" "NO_SIGN_UP" "OFFENSIVE_MESSAGES" "OTHER" "OTP_DID_NOT_REQUEST" "SPAM" "UNKNOWN_BLOCK_REASON" "UNRECOGNIZED"

400

BadRequest

401

Unauthorized

404

NotFound

409

Conflict

500

InternalServerError

post/v1/projects/{projectId}/whatsapp/templates/{templateName}/languages/{languageCode}/compare

Request samples

application/json

Example body request compare templates.

{"templates": [{"templateName": "templateName2",
"templateLanguage": "PL"
}
],
"timeframe": "60",
"endTimestamp": 1694612898734
}

Response samples

application/json

Response when successfully compared templates.

{"templates": [{"name": "templateName1",
"language": "EN",
"blockOrder": 1,
"messageSends": 1000,
"topBlockReason": "NO_REASON"
},
{"name": "templateName1",
"language": "PL",
"blockOrder": 2,
"messageSends": 2000,
"topBlockReason": "NO_REASON_GIVEN"
}
]
}

Security Privacy Legal & Compliance Cookie Statement

WhatsApp Templates

List all templates in project GA

path Parameters

query Parameters

Response Schema: application/json

Create a template in project GA

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

List all templates for a specific name GA

path Parameters

query Parameters

Response Schema: application/json

Delete template by name GA

path Parameters

Get template in project GA

path Parameters

query Parameters

Response Schema: application/json

Delete template draft for project GA

path Parameters

Update a template in project GA

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Lists activities on project template GA

path Parameters

query Parameters

Response Schema: application/json

Creates a comment for a template GA

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Compare two templates GA

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required