Welcome message flows

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.

This guide explains how to manage welcome message flows via the API endpoint.

Create/Update

Create a new flow

To create a new welcome message flow, send a POST request to the graph.facebook.com/v21.0/PAGE_ID/welcome_message_flows endpoint.

Sample request

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"} 

Parameters

Update an existing flow

To update an existing flow, send a POST request to the graph.facebook.com/v14.0/PAGE_ID/welcome_message_flows endpoint with:

• the flow_id parameter set to the ID of the flow being updated
• optionally, the other parameters (name, welcome_message, platforms) that need to be updated

Sample request

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} 

Parameters

Read

Get a list of flows

To get a list of flows for the page, send a GET request to graph.facebook.com/v14.0/PAGE-ID/welcome_message_flows

Sample request

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
  }, 
]

Get a specific flow

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.

Sample request

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
  },
]

Parameters

Delete

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.

Sample request

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} 

Parameters

Ads Manager experience

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.

Example use

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.

Marketing API Experience

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.