When creating ads that Click to Messenger or Click to Instagram Direct, you can connect a message flow from a messaging partner app. A message flow can include text, images, emoji, buttons, and other message types supported by the Messenger Send API or Instagram Messaging API.
Welcome message flows are now available for ads that Click to Instagram Direct for Instagram API with Instagram login.
This guide explains how to manage welcome message flows via the API endpoint.
To create a new welcome message flow, send a POST
request to the graph.facebook.com/
endpoint.v21.0
/PAGE_ID/welcome_message_flows
curl -X POST \
-F 'welcome_message_flow=[
{"message":
{
"text":"This is a welcome message authored in a 3P tool",
"quick_replies":[
{
"content_type":"text",
"title":"Quick reply 1",
"payload":"Payload 1"
},
{
"content_type":"text",
"title":"Quick reply 2",
"payload":"Payload 2"
},
{
"content_type":"text",
"title":"Quick reply 3",
"payload":"Payload 3"
}
]
}
}
]' \
-F 'eligible_platforms=["messenger"]' \
-F 'name="Driver sign up"' \
"https://graph.facebook.com/v21.0
/<PAGE_ID>/welcome_message_flows?access_token=<ACCESS-TOKEN>"
In response, your app will receive a flow ID.
{"flow_id":"123456789"}
Parameter | Type | Required? | Description |
---|---|---|---|
| string | yes | Name of the flow |
| JSON | yes | The welcome message JSON that will be sent upon clicking the ad |
| Array of strings | yes | The platforms that the welcome message can be shown on ( |
To update an existing flow, send a POST
request to the graph.facebook.com/v14.0/PAGE_ID/welcome_message_flows
endpoint with:
flow_id
parameter set to the ID of the flow being updatedname
, welcome_message
, platforms
) that need to be updatedA flow that is currently connected to an advertisement cannot be updated. Check the is_used_in_ad
field to determine whether a flow is connected to an advertisement.
curl -X POST\ -F 'flow_id="123456789"'\ -F 'eligible_platforms=["messenger", "instagram"]' \ -F 'name="Driver sign up - updated"' \ "https://graph.facebook.com/v14.0/{PAGE-ID}/welcome_message_flows?access_token={ACCESS-TOKEN}"
In response, your app will receive a success message or the appropriate error message.
{"success":true}
Parameter | Type | Required? | Description |
---|---|---|---|
| string | yes | The identifier of the flow to update |
| string | no | Name of the flow |
| JSON | no | The welcome message that will be sent upon clicking the ad |
| Array of strings | no | The platforms that the flow can be applied to ( |
To make an update, at least one of the three optional parameters must be provided.
To get a list of flows for the page, send a GET
request to graph.facebook.com/v14.0/PAGE-ID/welcome_message_flows
curl -X GET \ "https://graph.facebook.com/v14.0/{PAGE-ID}/welcome_message_flows?access_token={ACCESS-TOKEN}"
On success, your app will receive a list of flows created for that particular app.
[ { "id":"123456789", "name":"Driver Sign up", "welcome_message":"<JSON String>", "eligible_platforms": ["instagram", "messenger"], "last_update_time":"2023-09-01T05:20:38+0000", "is_used_in_ad": false // indicates whether or not a flow is used in an ad }, { "id":"4362", "name":"Basic Triage", "welcome_message":"<JSON String>", "eligible_platforms": ["instagram"], "last_update_time":"2023-08-25T08:21:48+0000", "is_used_in_ad": true }, { "id":"234564", "name":"Appointment Schedule", "welcome_message":"<JSON String>", "eligible_platforms": ["messenger"], "last_update_time":"2023-08-20T07:43:00+0000", "is_used_in_ad": true } ... ... ..., { "id":"6987565", "name":"Car Leads", "welcome_message":"<JSON String>", "eligible_platforms": ["instagram", "messenger"], "last_update_time":"2023-07-21T05:21:48+0000", "is_used_in_ad": false }, ]
To get a specific flow, send a GET
request to graph.facebook.com/v14.0/PAGE-ID/welcome_message_flows
with the flow_id
parameter set to the flow_id
being queried.
curl -X GET \ -F 'flow_id="123456789"' "https://graph.facebook.com/v14.0/{PAGE-ID}/welcome_message_flows?access_token={ACCESS-TOKEN}"
On success, your app will receive the flow in JSON format.
[ { "id":"123456789", "name":"Driver Sign up", "welcome_message":"<JSON String>", "eligible_platforms": ["instagram", "messenger"], "last_update_time":"2023-09-01T05:20:38+0000", "is_used_in_ad": false }, ]
Parameter | Type | Required? | Description |
---|---|---|---|
| string | no | The identifier of the flow to fetch |
| int | no | Maximum number of flows to fetch |
To delete a flow, send a DELETE
request to graph.facebook.com/v14.0/PAGE-ID/welcome_message_flows
with the flow_id
parameter set to the ID of the flow that is being deleted.
A flow that is currently connected to an advertisement cannot be deleted. Check the is_used_in_ad
field to determine whether a flow is connected to an advertisement.
curl -X DELETE \ -F 'flow_id="1234567890"' "https://graph.facebook.com/v14.0/{PAGE-ID}/welcome_message_flows?access_token={ACCESS-TOKEN}"
In response, your app will receive a success message or the appropriate error message.
{"success":true}
Parameter | Type | Required? | Description |
---|---|---|---|
| string | yes | The identifier of the flow to delete |
Once welcome message flows have been successfully submitted over the API, they will show up in Ads Manager for messaging destinations within the Engagement and Sales objectives. The flows will show up in the Partner App option within the Message Template section of the Ad Creative.
In the Message Template section of the Ad Creative, select Partner App.
Select the appropriate messaging Partner App.
Select the Welcome Message Flow that you submitted via the API.
Preview your message flow.
Once welcome message flows have been successfully submitted over the API, the flow ID can be used to configure ads through the marketing API.
In the ad creative, the flow ID can be set as follows:
{ "name": "creative", "object_story_spec": {...}, "asset_feed_spec": { "additional_data": { "partner_app_welcome_message_flow_id": "<FLOW_ID_RETURNED_FROM_POST_REQUEST>" } } }
For more information about messaging ads, please refer to Messaging Ads in the Marketing API documentation.