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.

Requirements

You will need:

A Page access token requested by a person who can perform the MESSAGING task on the Page

The pages_messaging permission

If setting eligible_platforms to include instagram, your app will also need:

The instagram_basic permission

The instagram_manage_messages permission

Create a new flow

To create a new welcome message flow, send a POST request to the graph.facebook.com/v25.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/v25.0/<PAGE_ID>/welcome_message_flows?access_token=<ACCESS-TOKEN>"

In response, your app will receive a flow ID.

{"flow_id":"123456789"}

Parameters

Parameter	Type	Required?	Description
`name`	string	yes	Name of the flow
`welcome_message_flow`	JSON	yes	The welcome message JSON that will be sent upon clicking the ad
`eligible_platforms`	Array of strings	yes	The platforms that the welcome message can be shown on (`["instagram", "messenger"]`) Note: Each Welcome Message will be validated against the platform(s) specified and will only be accepted if the message type in the welcome message is supported on the specified platform(s).

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

A 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.

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

Parameter	Type	Required?	Description
`flow_id`	string	yes	The identifier of the flow to update
`name`	string	no	Name of the flow
`welcome_message_flow`	JSON	no	The welcome message that will be sent upon clicking the ad
`eligible_platforms`	Array of strings	no	The platforms that the flow can be applied to (`["instagram", "messenger"]`)

To make an update, at least one of the three optional parameters must be provided.

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

Parameter	Type	Required?	Description
`flow_id`	string	no	The identifier of the flow to fetch
`limit`	int	no	Maximum number of flows to fetch

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.

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.

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

Parameter	Type	Required?	Description
`flow_id`	string	yes	The identifier of the flow to delete

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.

Did you find this page helpful?