Message Template Management
Retrieve, create, edit and delete WhatsApp message templates.
Explore guides, APIs, and resources to build with Sprout
Developer Documentation
API GatewayConnect, automate and scale WhatsApp experiences
Sprout WhatsApp API Gateway
Integrate WhatsApp messaging capabilities into external systems using a simplified REST API.
The Sprout WhatsApp API Gateway allows developers to manage WhatsApp message templates, send approved template messages, receive message-status updates and process incoming customer messages.
Main Capabilities
Send Template Messages
Send approved WhatsApp message templates to recipients.
Message Status Updates
Receive asynchronous updates when messages are sent, delivered or read.
Incoming Customer Messages
Receive customer replies and message details through webhook events.
Getting Started
- Configure the Base URL Use the Sprout WhatsApp API Gateway base URL.
- Add Authentication Include the bearer token in the authorization header.
- Identify the Required IDs Use the WABA ID, phone number ID and template ID in the relevant endpoints.
- Manage Templates Retrieve, create, edit or delete WhatsApp templates.
- Send a Template Message Send an approved template using the phone number ID.
- Receive Webhook Events Receive status updates and incoming customer messages.
Endpoint ConfigurationUse the correct host and API path for every request
Base URL
All API requests must be sent through the Sprout WhatsApp API Gateway.
Host
app.hellosprout.ai API Path
/whatsapp-gw/api Full Base URL
https://app.hellosprout.ai/whatsapp-gw/api All endpoint paths shown above must be added after
the base URL.
Secure AccessAuthenticate every request with a bearer token
Authentication
All API endpoints require bearer token authentication.
Required Headers
Authorization
Authorization: Bearer <AUTH_TOKEN> Content Type
Content-Type: application/json Example request headers
curl 'https://app.hellosprout.ai/whatsapp-gw/api/<ENDPOINT>' \
-H 'Authorization: Bearer <AUTH_TOKEN>' \
-H 'Content-Type: application/json'Core IdentifiersUnderstand the IDs used throughout the API
Identifiers and Terminology
The WhatsApp API Gateway uses the following identifiers in endpoint paths and request details.
WABA_IDWhatsApp Business Account ID
Identifies the WhatsApp Business Account that owns the templates.
PHONE_NUMBER_IDWhatsApp Business Phone Number ID
Identifies the connected business phone number used to send messages.
TEMPLATE_IDMessage Template ID
Identifies an individual WhatsApp message template.
Template LibraryRetrieve all templates connected to a WABA
List Templates
Retrieve the message templates available under a WhatsApp Business Account.
GET
/<WABA_ID>/message_templatesRequired Information
- WhatsApp Business Account ID
- Authorization bearer token
Response Information
The response may include:
Template name
Parameter format
Template components
Header details
Body text
Example parameter values
Buttons
Language
Status
Category
Template ID
Pagination cursors
Common Values
Language
en_US Status
APPROVED Category
MARKETINGPaging
Pagination information may include:
- Before cursor
- After cursor
Example Request
cURL
curl 'https://app.hellosprout.ai/whatsapp-gw/api/<WABA_ID>/message_templates' \
-H 'Authorization: Bearer <AUTH_TOKEN>'Example Response
JSON
{
"data": [
{
"name": "text_params_button",
"parameter_format": "NAMED",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "sample_text"
},
{
"type": "BODY",
"text": "O {{name}}, chosen of fortune, Emrys and Morgana do summon thee...",
"example": {
"body_text_named_params": [
{
"param_name": "name",
"example": "Arthur"
},
{
"param_name": "bell_location",
"example": "Avalon Tower"
}
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Turn Away"
},
{
"type": "PHONE_NUMBER",
"text": "Heed the Summons",
"phone_number": "+94716925097"
}
]
}
],
"language": "en_US",
"status": "APPROVED",
"category": "MARKETING",
"id": "1308035194697923"
}
],
"paging": {
"cursors": {
"before": "cursor-string",
"after": "cursor-string"
}
}
}Template CreationBuild structured WhatsApp templates
Create Template
Create a new WhatsApp message template under a WhatsApp Business Account.
POST
/<WABA_ID>/message_templatesRequest Body Fields
Name
String RequiredThe name of the template.
Category
String RequiredSupported categories:
UTILITY MARKETINGLanguage
String RequiredThe language code used by the template.
en_USParameter Format
String RequiredThe documented parameter format is:
NAMEDComponents
Array RequiredContains the template content.
Supported Template Components
Header
- Type
- Format
- Text
Body
- Message text
- Named parameters
- Example parameter values
Footer
Includes footer text
Buttons
Quick reply button
Response
The response includes:
- Template ID
- Status
- Category
A newly created template may return the status
PENDING.Example Request
JSON
{
"name": "sample_text_template",
"category": "UTILITY",
"language": "en_US",
"parameter_format": "NAMED",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Sample Header"
},
{
"type": "BODY",
"text": "Hello {{name}}, your order is ready.",
"example": {
"body_text_named_params": [
{
"param_name": "name",
"example": "John"
}
]
}
},
{
"type": "FOOTER",
"text": "Thank you"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Quick Reply Button"
}
]
}
]
}Example Response
JSON
{
"id": "987654321",
"status": "PENDING",
"category": "UTILITY"
}Template EditingUpdate existing WhatsApp templates safely
Edit Template
Edit an existing WhatsApp message template.
POST
/<TEMPLATE_ID>Eligible Template Statuses
APPROVED REJECTED PAUSEDEditable Properties
- Category
- Components
- Time-to-live
Important Editing Rules
- Individual template components cannot be edited separately.
- All components are replaced by the components included in the edit request.
- The category of an approved template cannot be edited.
- Approved templates can be edited up to 10 times within a 30-day period.
- Approved templates can be edited once within a 24-hour period.
- Rejected or paused templates can be edited an unlimited number of times.
- After editing an approved or paused template, it will automatically be approved unless it fails template review.
Response
- Success status
- Template ID
- Template name
- Template category
Example Request
JSON
{
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "A Proclamation of Hidden Sorcery"
},
{
"type": "BODY",
"text": "Sample Edited Text."
}
]
}Example Response
JSON
{
"success": true,
"id": "889288737024431",
"name": "text_only",
"category": "MARKETING"
}Template RemovalDelete WhatsApp templates using their ID and name
Delete Template
Delete a WhatsApp message template using its ID and name.
DELETE
<WABA_ID>/message_templates?hsm_id=<TEMPLATE_ID>&name=<TEMPLATE_NAME>Required Query Information
hsm_idMessage Template ID
The unique ID of the message template.
nameTemplate Name
The name assigned to the message template.
Required Information
- WhatsApp Business Account ID
- Template ID
- Template name
- Authorization bearer token
Successful Response
success: true Example Request
cURL
curl -X DELETE \
'https://app.hellosprout.ai/whatsapp-gw/api/<WABA_ID>/message_templates?hsm_id=<TEMPLATE_ID>&name=<TEMPLATE_NAME>' \
-H 'Authorization: Bearer <AUTH_TOKEN>'Example Response
JSON
{
"success": true
}Message DeliverySend approved templates to recipients
Send Template Message
Send a WhatsApp template message using the connected WhatsApp business phone number.
POST
/<PHONE_NUMBER_ID>/messagesRequest Body Fields
messaging_product
String RequiredMust be:
whatsappto
String RequiredThe recipient number in E.164 format.
type
String RequiredMust be:
templatetemplate
Object RequiredContains the template configuration.
Template Configuration
Name The approved template name.
Language
en_US Components Contains the dynamic values required by the template.
Named Parameters
The documented body parameter includes:
- Type
- Parameter name
- Text value
Named parameters allow the template to insert customer-specific content.
Response
- Messaging product: the messaging platform used.
- Contacts: the original recipient input and WhatsApp ID.
- Messages: the message ID and message status.
The example message status is
accepted.Example Payload
JSON
{
"messaging_product": "whatsapp",
"to": "+94712345678",
"type": "template",
"template": {
"name": "sample_text_template",
"language": {
"code": "en_US"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"parameter_name": "name",
"text": "John"
},
{
"type": "text",
"parameter_name": "name",
"text": "sample_text"
}
]
}
]
}
}Example Response
JSON
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+94716935097",
"wa_id": "94716935097"
}
],
"messages": [
{
"id": "wamid.HBgLOTQ3MTY5MzUwOTcVAgARGBI4NkVDOTIzRjdCREFDNDRBRDUA",
"message_status": "accepted"
}
]
}Event TrackingFollow message progress through webhook events
Message Status Updates
The gateway sends asynchronous webhook updates for WhatsApp message events.
Documented Events
Sent
Delivered
Read
Rejected
Each webhook payload uses the whatsapp_business_account object and includes an entry array containing message-related changes.
Select an event from the sidebar to view the information contained
in its documented payload.
Sent Webhook Event
The sent event is generated when a WhatsApp message reaches the sent status.
Status value
sentPayload Information
- Object type:
whatsapp_business_account - WhatsApp Business Account entry ID
- Messaging product
- Display phone number
- Phone number ID
- Message ID
- Status
- Timestamp
- Recipient phone number
- Billable value
- Pricing model
- Message category
- Pricing type
- Webhook field:
messages
Documented Pricing Values
Pricing model
PMP Category
marketing Type
regularExample Webhook Payload
Sent webhook payload
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "1435343061523969",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<MESSAGE_ID>",
"status": "sent",
"timestamp": "1770893055",
"recipient_id": "<RECIPIENT_PHONE_NUMBER>",
"pricing": {
"billable": true,
"pricing_model": "PMP",
"category": "marketing",
"type": "regular"
}
}
]
},
"field": "messages"
}
]
}
]
}Delivered Webhook Event
The delivered event is generated when a WhatsApp message reaches the delivered status.
Status value
deliveredPayload Information
- Object type:
whatsapp_business_account - WhatsApp Business Account entry ID
- Messaging product
- Display phone number
- Phone number ID
- Message ID
- Status
- Timestamp
- Recipient phone number
- Billable value
- Pricing model
- Message category
- Pricing type
- Webhook field:
messages
Documented Pricing Values
Pricing model
PMP Category
marketing Type
regularExample Webhook Payload
Delivered webhook payload
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "1435343061523969",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<MESSAGE_ID>",
"status": "delivered",
"timestamp": "1770893055",
"recipient_id": "<RECIPIENT_PHONE_NUMBER>",
"pricing": {
"billable": true,
"pricing_model": "PMP",
"category": "marketing",
"type": "regular"
}
}
]
},
"field": "messages"
}
]
}
]
}Read Webhook Event
The read event is generated when a WhatsApp message reaches the read status.
Status value
readPayload Information
- Object type:
whatsapp_business_account - WhatsApp Business Account entry ID
- Messaging product
- Display phone number
- Phone number ID
- Message ID
- Status
- Timestamp
- Recipient phone number
- Billable value
- Pricing model
- Message category
- Pricing type
- Webhook field:
messages
Documented Pricing Values
Pricing model
PMP Category
marketing Type
regularExample Webhook Payload
Read webhook payload
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "1435343061523969",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"statuses": [
{
"id": "<MESSAGE_ID>",
"status": "read",
"timestamp": "1770892507",
"recipient_id": "<RECIPIENT_PHONE_NUMBER>",
"pricing": {
"billable": true,
"pricing_model": "PMP",
"category": "marketing",
"type": "regular"
}
}
]
},
"field": "messages"
}
]
}
]
}Rejected Webhook Event
The source document includes a webhook example titled Rejected.
Payload Information
- Object type:
whatsapp_business_account - WhatsApp Business Account entry ID
- Messaging product
- Display phone number
- Phone number ID
- Contact profile name
- Contact WhatsApp ID
- Message context
- Context sender
- Context message ID
- Sender phone number
- Incoming message ID
- Timestamp
- Text body
- Message type
- Webhook field:
messages
Documented Example Values
Message type
text Text body
HiExample Webhook Payload
Incoming text message payload shown under Rejected
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "1435343061523969",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "<DISPLAY_PHONE_NUMBER>",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<REPLIED_CONTACT_NAME>"
},
"wa_id": "<RECIPIENT_PHONE_NUMBER>"
}
],
"messages": [
{
"context": {
"from": "<DISPLAY_PHONE_NUMBER>",
"id": "<CONTEXT_MESSAGE_ID>"
},
"from": "<RECIPIENT_PHONE_NUMBER>",
"id": "<INCOMING_MESSAGE_ID>",
"timestamp": "1770892557",
"text": {
"body": "Hi"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}Developer SandboxPrepare and test your integration safely
Sandbox Account Access
Request access to the Sprout sandbox environment to view and manage WhatsApp message templates.
Before Requesting Access
A WhatsApp number must be integrated before you can access the portal and manage message templates.
Request Sandbox AccessTemplate PortalOpen the portal to manage WhatsApp templates
Portal Login
Access the Sprout template portal to view and manage WhatsApp message templates.
Login URL
https://app.hellosprout.ai/promotion/templates Your WhatsApp number must be integrated before you can access the
portal.
Open Template Portal