WhatsApp Template Management API

The WhatsApp Template Management API allows you to list existing WhatsApp templates, create new templates, delete templates, and upload media for template creation and message sending. Although WhatsApp templates can be managed manually via the WhatsApp Business Manager UI, the Vonage WhatsApp Template Management API now lets you manage your templates programmatically through the WhatsApp Business API.

The WhatsApp Template Management API currently lets you perform the following operations:

WhatsApp's Contacts & Locations objects can only be sent in response to an incoming message.

The WhatsApp Template Management API rate limit is 40rps.

Getting a List of Templates

Using the WhatsApp Template Management API, you can get a list of templates owned by the specified WhatsApp Business Account. The API provides some pagination and filtering functionality. For example, you can filter requests by template status, language, and name_or_content.

Creating a Template

You can create templates of various types and categories, as well as creating multiple language variations of a template. When creating templates with multiple language versions, make sure to be consistent with translations across the versions.

Make sure that your templates follow WhatsApp Message Template Guidelines. Not correctly following the guidelines can impact on templates being approved.

Note that the requirements regarding the content and composition of a template vary according to template category, with Authentication templates being the most restricted and Marketing templates the most flexible. The Meta documentation provides more information on what is allowable for different template categories.

Approval Process

Templates need to be approved by Meta before they can be used in a WhatsApp message. When created, templates initially have a status of PENDING. Once approved, they will have a status of APPROVED, and can then be used.

Media Message Templates

When creating a template with a media header, first upload the media with the template-creation upload endpoint. Use the returned header_handle only when creating or updating the template. A header_handle is not a Cloud API media ID and cannot be used when sending a message.

To send a template with a media header, upload the media with the send-time upload endpoint, then use the returned media_id in the corresponding Messages API request.

Language Variants

You can create multiple variants of a template to cater for different languages. To do this, create a template with the same name and category as an existing template, and set language property and all the text content as appropriate for the new language variant. A list of supported languages is available in the WhatsApp documentation.

Template Categories

Starting June 1st 2023, WhatsApp is introducing new conversation categories for businesses sending messages; information on these categories and their pricing can be found here. There are now three supported template categories for each of the business-initiated conversation types:

  • UTILITY: Enable the completion of a particular, agreed-upon request or transaction or provide a customer with an update about an ongoing transaction, including post-purchase notifications and regular billing statements.
  • AUTHENTICATION: Enables businesses to utilize one-time passcodes to verify users at various login stages, if necessary (e.g. account verification, account recovery, integrity challenges).
  • MARKETING: Business-initiated conversations to market a good or service to customers, such sending pertinent offers to customers who have opted in. This would also include any business-related interaction that is not an authentication or utility conversation.

All existing templates in one of these categories will be migrated to one of the new template categories: TRANSACTIONAL, MARKETING, OTP, ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE, ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE or AUTO_REPLY.

Note: an unverified WhatsApp business account can have a maximum of 250 message templates, whereas a verified business account can have a maximum of 6000 message templates. Each language variant counts as one template; for example, a message template called hello_world translated into two languages counts as a two message templates in regards to this limit.

A WhatsApp Business Account can create a maximum of 100 message templates per hour.

Deleting a Template

You can delete a template associated with a specific WhatsApp Business Account by specifying the template by name or via its ID. If a particular template has multiple language versions for the same name, all versions for that template name will be deleted.

Once deleted, the name of the (approved) template cannot be used again for 30 days.

Messages sent for a deleted template may still be delivered within 30 days if they have been sent but not yet delivered.

Updating a Template

You can update an existing template identified via its template ID. There are a few things to keep in mind when editing a template:

  1. Message templates can only be edited when in an Approved, Rejected, or Paused state.
  2. When editing a live template, templates will be eligible for auto-approval. Templates that pass formatting and Business and Commerce Policy checks will go live again immediately, without any additional action needed to continue sending messages already using those templates.
  3. When editing a Paused template, templates will be eligible for auto-approval. Templates that pass formatting checks and Business and Commerce Policy checks will be able to go live again. In order to begin sending messages using those templates, businesses will have to make an API call the Messaging API.
  4. The Update endpoint lets you change the category of the template. Once the request successfully submitted you will be able to see both the "previous_category" and updated "category" when using the List Templates endpoint.
  5. Message templates in an Approved state can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window. Messages in Rejected or Paused states can be edited an unlimited number of times.

Uploading Media for Template Creation

Use this endpoint only when creating or updating a template that has a media header. It returns a Meta resumable-upload header_handle, which you include in the template's media-header component. The handle is valid for 30 days and cannot be used to send a template, interactive, or free-form WhatsApp message.

The header_handle returned by this endpoint is not a Cloud API media ID. Do not use it as a send-time attachment ID.

Note: a timeout may occur if you attempt to upload large media files (for example, above 25 MB). In such cases, we recommend using the WhatsApp Business Manager UI to upload the files.

Example cURL Request

curl --location 'https://api.nexmo.com/v2/whatsapp-manager/media/uploads?file_type=image%2Fjpg' \
--header 'Authorization: Basic NTE1...g==' \
--form 'mediafile=@"Directory/WhatsApp_Image.jpeg"'

Uploading Media for Sending

Use this endpoint to upload media once before sending a WhatsApp media template, interactive, or free-form message. It proxies Meta's Media Upload API and returns a stable Cloud API media_id. Use this ID in the appropriate Messages API media_id field instead of a public URL.

Using a public URL causes Meta to download the media for each send and can result in intermittent 131053 media-upload errors. The header_handle from the template-creation endpoint is accepted only when creating or updating templates and is rejected at send time.

Endpoint

POST https://api.nexmo.com/v2/whatsapp-manager/numbers/{phone_number}/media?file_type=image/jpg

The request uses multipart/form-data and includes the file field. Set file_type to the media MIME type.

Example cURL Request

curl --location 'https://api.nexmo.com/v2/whatsapp-manager/numbers/447700900001/media?file_type=image%2Fjpg' \
--header 'Authorization: Basic NTE1...g==' \
--form 'file=@"c:/local/media/assets/image.jpg"'

Example Response

{
  "media_id": "1037543291543636"
}