WhatsApp Flows

Last update: 6 hours ago by Irais Aguirre

Integration summary
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: messaging token, in the Authorization: Bearer {{wa-msg-api-token}} header (how to generate it)
Common fields: from, to (phone number or BSUID) and type (details)
type values on this page: "interactive"
Response: the same for every message (see response)

Messages that open a WhatsApp Flow. To create and manage Flows, see the Flows section. They are sent with POST /v1/messaging; headers, common fields and the response are in HTTP connection.

WhatsApp Flows

The type field must be "interactive" and the message content is sent in the flow object. See the general structure of interactive messages.

Body

Fields for WhatsApp Flows:

Name	Description	Type	Requirements
flow	Object with the WhatsApp Flow. Send only one: listMessages, replyButtons or flow (or another interactive message type).	Object	Conditional

Flow object

Name	Description	Type	Requirements
body	The message content.	String	Required
action	The action you want the user to take after reading the message.	Object	Required

Action object

Name	Description	Type	Requirements
name	Action name. The service always sends "flow".	String	Optional
parameters	Flow parameters.	Object	Required

action.parameters object

Name	Description	Type	Requirements
mode	The flow can be in one of these modes: draft published	String	Optional. Default: "published"
flow_message_version	Flow message version. The service always sends "3", whatever value you pass.	String	Optional. Always sent as "3".
flow_id	Unique Flow ID provided by WhatsApp.	String	Required.
flow_token	Token your business generates to identify the Flow session. It is returned in the Flow response.	String	Optional.
flow_cta	Call to action button text, for example, "Sign up".	String	Required Character limit: 20 characters (no emojis).
flow_action	navigate: Predefines the first screen as part of the message. data_exchange: For advanced use cases where your endpoint provides the first screen.	String	Required. Possible values: "navigate" or "data_exchange".
flow_action_payload		Object	Required if flow_action is "navigate". Otherwise, omit it.

flow_action_payload object

Name	Description	Type	Requirements
screen	ID of the screen shown first.	String	Must be an entry screen.
data	Optional input data for the Flow's first screen. If provided, it must be a non-empty object.	Map<String, Object>	Optional

Example

Complete WhatsApp Flows example (HTTP request and JSON body):

WhatsApp Flows HTTP request

curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \
-H 'Authorization: Bearer {{wa-msg-api-token}}' \
-H 'Content-Type: application/json' \
-d '{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "interactive",
    "flow": {
        "body": "Book a WhatsApp API consulting session with one of our Concepto Móvil agents to get familiar with our solutions",
        "action": {
            "name": "flow",
            "parameters": {
                "mode": "draft",
                "flow_message_version": "3",
                "flow_id": "1",
                "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
                "flow_cta": "Book now",
                "flow_action": "navigate",
                "flow_action_payload": {
                    "screen": "screen name",
                    "data": {
                        "product_name": "name",
                        "product_description": "description",
                        "product_price": 100
                    }
                }
            }
        }
    }
}'

WhatsApp Flows body

{
    "from": "5215500000001",
    "to": "5215500000002",
    "type": "interactive",
    "flow":
    {
        "body": "Book a WhatsApp API consulting session with one of our Concepto Móvil agents to get familiar with our solutions",
        "action": {
            "name": "flow",
            "parameters": {
                "mode": "draft",
                "flow_message_version": "3",
                "flow_id": "1",
                "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
                "flow_cta": "Book now",
                "flow_action": "navigate",
                "flow_action_payload": {
                    "screen": "screen name",
                    "data": {
                        "product_name": "name",
                        "product_description": "description",
                        "product_price": 100
                    }
                }
            }
        }
    }
}

Contact information request

Location request