Send a utility message
Important Notice
This product is currently in open Beta. Please be aware that Utility Messages utilizing the Utility Template API are only accessible to businesses and end-users located in our priority markets, which include the United States (US), Vietnam (VN), Thailand (TH), and the Philippines (PH).
This document shows you how to send a utility message.
What's a utility message?
A utility message is a message, created from a template, sent to your customers that contain order or account status updates, and appointment or event reminders, and can be personalized with a customer’s name, locale, appointment or event date, and more. A utility message template contains placeholder values such as a person’s name, order id, tracking number, and so on, that are filled in at the time the message is sent to the consumer. Your app users can create their own utility message templates or use one of Meta's utility message templates to create these messages.
How it works
There are a number of flows for your app users to send utility messages:
Use a Meta template
| Create and send a Page-owned template
| Use an existing Page-owned template
|
Note: Facebook Pages are not required to be linked to a business to send utility messages.
Before You Start
This guide assumes you have set up your webhooks server to receive notifications and subscribed to the message_template_status_update field as well as other webhook messaging fields your app user's utility messages need.
You need the following:
- The ID for the Page sending the message
- The Page-scoped ID of the customer receiving the message
- A Page access token from your app user who is sending the message
- Your app user has granted your app the
page_utility_messagingpermission
Limitations
Utility messages must not contain marketing materials. Learn more in our Marketing Messages documentation.
The Utility Messaging feature is currently available only to pages and users in the United States, Thailand, Philippines, and Vietnam.
Meta utility message templates
Meta has a number of pre-approved templates that your app users can use to send utility templates.
Step 1. Search for a template
To get a list of Meta utility message templates, send a GET request to the /message_template_library endpoint. Add additional parameters to refine your search. In the following example we are searching for English templates that include the word "order" in the name or message content.
curl -X GET "https://graph.facebook.com/v24.0/message_template_library?name_or_content=order&language=en?access_token=EAACE..."
On success your app receives a JSON response with a list of templates that match the query. The template's name value is needed to use the template for your app user's utility messages.
{
"data": [
{
"name": "order_confirmation_1",
"language": "en",
"category": "UTILITY",
"topic": "ORDER_MANAGEMENT",
"usecase": "DELIVERY_CONFIRMATION",
"industry": [
"E_COMMERCE"
],
"body": "{{1}}, your order was successfully delivered!
You can track your package and manage your order below.",
"body_params": [
"John"
],
"body_param_types": [
"TEXT"
],
"buttons": [
{
"type": "URL",
"text": "Manage order",
"url": "https://www.example.com"
}
],
"id": "7635027653257090"
},
... // List is truncated for brevity
]
}
Step 2. Clone the template
To clone a Meta utility message template to a Page's template library, send a POST request to the /<PAGE_ID>/message_templates endpoint with the following parameters:
nameset to the name of the cloned templatecategoryset toUTILITYlanguageset to the language code for this messagelibrary_template_nameset to the name of the Meta template being cloned (order_confirmation_1)
In the following example, the the cloned template requires the additional library_template_body_inputs and library_template_button_inputs parameters set to the components containing the app user's values.
curl -X POST -H "Content-Type: application/json"
-d '{
"name": "jaspers_market_order_confirmation_1",
"category": "UTILITY",
"language": "en_US",
"library_template_name”: "order_confirmation_1",
"library_template_body_inputs": [
{
"type": "body",
"text": "{{1}}, your order was successfully delivered!\n\n You can track your package and manage your order below."
}
],
"library_template_button_inputs": [
{
"type": "URL",
"text": "Manage your order",
"url": {
"base_url": "https://www.jaspersmarket.com/"
}
}
]
}' "https://graph.facebook.com/v24.0/1909458034523498/message_templates?access_token=EAACE..."
On success your app receives a JSON response with the template's ID, the approval status, and the template category.
{
"id": "102295129340398",
"status": "APPROVED",
"category": "UTILITY"
}
Step 3. Send a message
To send a utility message from a cloned Meta template, send a POST request to the /<PAGE_ID>/messages endpoint with the following parameters:
recipient.idset to the Page-scoped ID for the person your app user is sending the message tomessaging_typeset toUTILITYtemplatewith the following parameters:nameset to the name of the specific template being used to create the messagelanguage.codeset to the language code for this messagecomponentsarray with the following parameters:typeset tobodyparameters.typeset totextparameter.textset to the input needed for the template
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id":"2348927398743287"
},
"template": {
"name": "jaspers_market_order_confirmation_1",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{
"type": "body",
"text": "566701"
}
]
}
]
}
}' "https://graph.facebook.com/v24.0/1909458034523498/messages?access_token=EAACE..."
Page-owned utility message template
Your app users can create their own template for their utility messages.
Step 1. Create a Page-owned template
To create a utility message template, send a POST request to the /<PAGE_ID>/message_templates endpoint with the following required parameters:
nameset to the name of the templatelanguageset to the language of the message textcategoryset toUTILITYcomponentsset to an array of message components including an example with message values
Text-Only Templates
In the following example, we have message body text and header text. The body component and header component includes example customer information that would be used to customize the message.
curl -H 'Content-Type: application/json' \
-d '{
"name": "jaspers_market_order_delivery_update_us",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text":"{{1}} Update",
"example": {
"header_text":["Order"]
}
},
{
"type": "BODY",
"text": "Good news! Your order #{{1}} is on its way. Thank you for your order!"
"example": {
"body_text": [
[
"566701"
]
]
}
}
]
}' "https://graph.facebook.com/v24.0/102290129340398/message_templates?access_token=EAAJB..."
Text + Image Templates
You can also create templates with images. Images need to be first uploaded using the Resumable Upload API to generate the handle for the image. You can then use the handle and pass it in the Header component while creating the template.
curl -H 'Content-Type: application/json' \
-d '{
"name": "jaspers_market_order_delivery_update_us",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"text":"{{1}} Update",
"example": {
"header_handle": ["4:dGVzdF9pbWFn......."],
"header_text":["Order"]
}
},
{
"type": "BODY",
"text": "Good news! Your order #{{1}} is on its way. Thank you for your order!"
"example": {
"body_text": [
[
"566701"
]
]
}
}
]
}' "https://graph.facebook.com/v24.0/102290129340398/message_templates?access_token=EAAJB..."
On success your app receives a JSON response with the template ID, the review status, and the template category.
{
"id": "104595129340398",
"status": "APPROVED",
"category": "UTILITY"
}
Step 2. Send a message
To send a utility message using a template from your app user's template library, send a POST request to the /<PAGE_ID>/messages endpoint with the following required parameters:
recipient.idset to the Page-scoped ID for the person your app user is sending the message tomessage.templateset to a list of parameters:nameset to the name of the specific template being used to create the messagelanguageset to the language code for this templatecomponentsset to the name of the app user's template library
Add additional parameters to customize the message. In the following example, {{1}} will be replaced with the recipient's order ID.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "2348927398743287"
},
"message": {
"template": {
"name": "jaspers_market_order_delivery_update_us",
"language": {
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "this is the title"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "this is the body"
}
]
}
]
}
}
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app will receive a JSON response with the template ID, review status, and template category.
{
"recipient_id": "25381719828140932",
"message_id": "m_zm2fACsz21560tai1om-TvABABVG5smou58Xoe7OB4ekibklqP8d2WdzC-Z8j2LVG1G43QVrtVr-jwVZFg72kg"
}
Use an existing Page's template
Step 1. Search for a template
To get a list of a Page's utility message templates, send a GET request to the /<PAGE_ID>/message_templates endpoint.
Add additional parameters to find specific utility message types. In the following example we are searching for templates that include the word "delivery_confirmation" in the template name.
curl -X GET "https://graph.facebook.com/v24.0/102290129340398/message_templates?name=delivery_confirmation&access_token=EAAJB..."
On success your app receives a JSON response with a list of templates that match your query. You will need the template name value to use the template for your app user's utility messages.
{
"data": [
{
"name": "delivery_confirmation_1",
"language": "en",
"category": "UTILITY",
"topic": "ORDER_MANAGEMENT",
"usecase": "DELIVERY_CONFIRMATION",
"industry": [
"E_COMMERCE"
],
"body": "{{1}}, your order was successfully delivered!",
"body_params": [
"Mark"
],
"body_param_types": [
"TEXT"
],
"id": "7635027653257090"
},
{
"name": "delivery_confirmation_2",
...
},
]
}
Step 2. Send a message
To send a utility message using a template from your app user's template library, send a POST request to the /<PAGE_ID>/messages endpoint with the following required parameters:
recipient.idset to the Page-scoped ID for the person your app user is sending the message tomessage.templateset to a list of parameters:nameset to the name of the specific template being used to create the messagelanguageset to the language code for this templatecomponentsset to the name of the app user's template library
Add additional parameters to customize the message. In the following example, {{1}} will be replaced with the recipient's order ID.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "2348927398743287"
},
"message": {
"template": {
"name": "jaspers_market_order_delivery_update_us",
"language": {
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "this is the title"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "this is the body"
}
]
}
]
}
}
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app will receive a JSON response with the template ID, review status, and template category.
{
"recipient_id": "25381719828140932",
"message_id": "m_zm2fACsz21560tai1om-TvABABVG5smou58Xoe7OB4ekibklqP8d2WdzC-Z8j2LVG1G43QVrtVr-jwVZFg72kg"
}
Use a Template with Customizable Postback Button
Step 1. Create a template with a postback button
To create a utility message template, send a POST request to the /<PAGE_ID>/message_templates endpoint with the following required parameters:
nameset to the name of the templatelanguageset to the language of the message textcategoryset toUTILITYcomponentsset to an array of message components including an example with message values
In the following example, we have a customizable message body text and a POSTBACK button with a customizable payload.
curl -X POST -H "Content-Type: application/json" -d '{
"name": "jaspers_market_order_confirmation_update_us",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Your order is now {{1}}",
"example": {
"body_text": [
[
"Your order is now confirmed"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "POSTBACK",
"text": "Track Order",
"payload": "order_id_{{2}}"
}
]
}
]
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app receives a JSON response with the template ID, the review status, and the template category.
{
"id": "104595129340398",
"status": "APPROVED",
"category": "UTILITY"
}
Step 2. Send a message
To send a utility message using a template from your app user's template library, send a POST request to the /<PAGE_ID>/messages endpoint with the following required parameters:
recipient.idset to the Page-scoped ID for the person your app user is sending the message tomessage.templateset to a list of parameters:nameset to the name of the specific template being used to create the messagelanguageset to the language code for this templatecomponentsset to the name of the app user's template library
Add additional parameters to customize the message. In the following example, {{1}} and {{2}} will be replaced with the recipient's order ID, updating both the body text and the POSTBACK button's payload.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "25381719828140932"
},
"messaging_type": "UTILITY",
"message": {
"template": {
"name": "jaspers_market_order_confirmation_update_us",
"language": {
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "confirmed"
}
]
},
{
"type": "buttons",
"parameters": [
{
"type": "POSTBACK",
"payload": "12345"
}
]
}
]
}
}
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app will receive a JSON response with the template ID, review status, and template category.
{
"recipient_id": "25381719828140932",
"message_id": "m_zm2fACsz21560tai1om-TvABABVG5smou58Xoe7OB4ekibklqP8d2WdzC-Z8j2LVG1G43QVrtVr-jwVZFg72kg"
}
Use a Template with Customizable URL Button
Step 1. Create a template with a postback button
To create a utility message template, send a POST request to the /<PAGE_ID>/message_templates endpoint with the following required parameters:
nameset to the name of the templatelanguageset to the language of the message textcategoryset toUTILITYcomponentsset to an array of message components including an example with message values
In the following example, we have a customizable message body text and a URL button with a customizable URL.
curl -X POST -H "Content-Type: application/json" -d '{
"name": "jaspers_market_order_confirmation_update_us",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Your order is now {{1}}",
"example": {
"body_text": [
[
"Your order is now confirmed"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "URL",
"text": "Track Order",
"url": "http://www.example.com/orders/{{1}}",
"example": {
"url_suffix_example": "https://www.example.com/orders/1234"
}
}
]
}
]
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app receives a JSON response with the template ID, the review status, and the template category.
{
"id": "104595129340398",
"status": "APPROVED",
"category": "UTILITY"
}
Step 2. Send a message
To send a utility message using a template from your app user's template library, send a POST request to the /<PAGE_ID>/messages endpoint with the following required parameters:
recipient.idset to the Page-scoped ID for the person your app user is sending the message tomessage.templateset to a list of parameters:nameset to the name of the specific template being used to create the messagelanguageset to the language code for this templatecomponentsset to the name of the app user's template library
Add additional parameters to customize the message. In the following example, {{1}} in the body text will be replaced with with the word confirmed and the {{1}} in the URL of the button will be replaced with the order ID.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "25381719828140932"
},
"messaging_type": "UTILITY",
"message": {
"template": {
"name": "jaspers_market_order_confirmation_update_us",
"language": {
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "confirmed"
}
]
},
{
"type": "buttons",
"parameters": [
{
"type": "URL",
"url": "1234"
}
]
}
]
}
}
}' "https://graph.facebook.com/v21.0/1909458034523498/messages?access_token=EAACE..."
On success your app will receive a JSON response with the template ID, review status, and template category.
{
"recipient_id": "25381719828140932",
"message_id": "m_zm2fACsz21560tai1om-TvABABVG5smou58Xoe7OB4ekibklqP8d2WdzC-Z8j2LVG1G43QVrtVr-jwVZFg72kg"
}
Utility Messages in Conversation API
Utility Messages that use only a BODY component will be represented in the Conversation API the same as basic text messages whereas messages that use a HEADER and BUTTONS components will be represented the same as
generic template messages.
Example: Utility Message with Only a Body in Conversation API
curl -X GET "https://graph.facebook.com/v21.0/me/messages?access_token=EAACE..."
{
"data": [
{
"messages": {
"data": [
{
"message": "Good news! Your order #123123123 is confirmed!",
"id": "m_-9paUc9QYpm9VbVRgslJlNAcspcsz2P9LWJH6flWihChxY9ujvS623AfYOMWiHeq_fgsSh4GXjGwTPWN9Slm2Q"
},
...
}
Example: Utility Message With Header or Buttons in Conversation API
curl -X GET "https://graph.facebook.com/v21.0/me/messages?access_token=EAACE..."
{
"data": [
{
"messages": {
"data": [
{
"attachments": {
"data": [
{
"generic_template": {
"title": "Order is being shipped",
"subtitle": "Good news! Your order #123123123 is now shipped. The tracking number is #track123"
}
}
]
},
"message": "",
"id": "m_qvfnMpHYUNzLf__jekbCjdAcspcsz2P9LWJH6flWihCIJ-wkOtKKkRzUDwl0nKO-is6mGR_WeP0caoCVKTWfLw"
},
...
}
Common Template Rejection Reasons
Submissions are commonly rejected for the following reasons, so make sure you avoid these mistakes.
Parameter Formatting
- Variable parameters are missing or have mismatched curly braces. The correct format is {{1}}.
- Variable parameters contain special characters such as a #, $, or %.
- Variable parameters are not sequential. For example, {{1}}, {{2}}, {{4}}, {{5}} are defined but {{3}} does not exist.
- Template contains too many variable parameters relative to the message length. You need to decrease the number of variable parameters or increase the message length.
- The message template cannot start or end with a parameter. In essence, dangling parameters are not allowed. In this case, the template will not be able to be created.
Content and Policy Violations
- The message template contains content that violates Utility Messages policy: When you offer goods or services for sale, we consider all messages and media related to your goods or services, including any descriptions, prices, fees, taxes and/or any required legal disclosures, to constitute transactions.
- Do not request sensitive identifiers from users. For example, do not ask people to share full length individual payment card numbers, financial account numbers, National Identification numbers, or other sensitive identifiers. This also includes not requesting documents from users that might contain sensitive identifiers. Requesting partial identifiers (ex: last 4 digits of their Social Security number) is OK.
- The content contains potentially abusive or threatening content, such as threatening a customer with legal action or threatening to publicly shame them.
See Also
To learn more about the concepts, endpoints, and mentioned in this document, please visit the following guides: