WhatsApp Flows

Endpoints for managing WhatsApp Flows

Getting all Flows

get

To retrieve a list of Flows under a WhatsApp Business Account (WABA), use this request.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

Query parameters

fieldsstring[]Optional

Flow fields to return. Available: id, name, categories, validation_errors, status, json_version, data_api_version, data_channel_uri, endpoint_uri, preview, whatsapp_business_account, metric

Default: ["id","name","categories","validation_errors","status"]Example: ["id","name","preview"]

Responses

200

Successful response

application/json

countintegerOptionalExample: 1

totalintegerOptionalExample: 1

400

Wrong payload

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "flows": [
    {
      "id": "2141298723942",
      "name": "Sign Up",
      "status": "DRAFT",
      "categories": [
        "SIGN_UP",
        "SIGN_IN"
      ],
      "validation_errors": [],
      "json_version": "7.2",
      "data_api_version": "3.0",
      "data_channel_uri": "https://company.com/flow/signup/channel",
      "preview": {
        "preview_url": "https://wa.com/flow/preview/abcd1234",
        "expires_at": "2023-05-21T11:18:09+0000"
      },
      "whatsapp_business_account": {
        "id": "1087234212320",
        "name": "My Business Account",
        "currency": "USD",
        "timezone_id": "47",
        "message_template_namespace": "kljasas_38197nkbhjgv_aajskd"
      },
      "endpoint_uri": "https://company.com/flow/signup",
      "metric": {
        "data_points": [
          {
            "timestamp": "2024-01-28T08:00:00+0000",
            "data": [
              {
                "key": "timeout_error",
                "value": 5.2
              }
            ]
          }
        ],
        "name": "ENDPOINT_REQUEST_ERROR",
        "granularity": "DAY"
      }
    }
  ],
  "count": 1,
  "total": 1
}

Creating a Flow

post

New Flows are created in DRAFT status. You can then make changes to the Flow by uploading an updated JSON file.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

Body

application/json

namestringRequired

Flow name

Example: Sign Up

clone_flow_idstringOptional

ID of source Flow to clone. You must have permission to access the specified Flow.

Example: 2141298723942

endpoint_uristringOptional

The URL of the WA Flow Endpoint. Starting from Flow JSON version 3.0 this property should be specified .Do not provide this field if you are updating a Flow with Flow JSON version below 3.0.

Example: https://company.com/flow/signup

Responses

200

Successful response

application/json

idstringOptional

The unique ID of the Flow.

Example: 2141298723942

400

Wrong payload

application/json

404

Not found

application/json

post

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows

HTTPcURLJavaScriptPython

POST /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "name": "Sign Up",
  "categories": [
    "SIGN_UP",
    "SIGN_IN"
  ],
  "clone_flow_id": "2141298723942",
  "endpoint_uri": "https://company.com/flow/signup"
}

{
  "id": "2141298723942"
}

Migrate flows from one WABA to another.

post

Migrate Flows from one WhatsApp Business Account (WABA) to another. Migration doesn't move the source Flows, it creates copies of them with the same names in the destination WABA.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

Body

application/json

source_waba_account_idstringRequired

Source WhatsApp Business Account ID to copy flows from

Example: exampleWA

source_flow_namesstring[]Optional

List of source flow names to migrate. If not provided, all flows will be migrated.

Example: ["appointment-booking","lead-gen"]

Responses

200

Successful response

application/json

400

Wrong payload

application/json

403

Forbidden

application/json

404

Not found

application/json

post

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/migrate_flows

HTTPcURLJavaScriptPython

POST /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/migrate_flows HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "source_waba_account_id": "exampleWA",
  "source_flow_names": [
    "appointment-booking",
    "lead-gen"
  ]
}

{
  "migrated_flows": [
    {
      "source_name": "appointment-booking",
      "source_id": "1234214123",
      "migrated_id": "56788782342"
    }
  ],
  "failed_flows": [
    {
      "source_name": "lead-gen",
      "error_code": "4233041",
      "error_message": "Flows Migration Error: Flow with the same name exists in destination WABA."
    }
  ]
}

Getting Flow details

get

This request will return a single Flow's details.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Query parameters

fieldsstring[]Optional

Flow fields to return. Available: id, name, categories, validation_errors, status, json_version, data_api_version, data_channel_uri, endpoint_uri, preview, whatsapp_business_account, metric

Default: ["id","name","categories","validation_errors","status"]Example: ["id","name","preview"]

Responses

200

Successful response

application/json

idstringOptional

The unique ID of the Flow.

Example: 2141298723942

namestringOptional

The user-defined name of the Flow which is not visible to users

Example: Sign Up

statusstringOptional

Flow status

Example: DRAFT

json_versionstringOptional

The version specified by the developer in the Flow JSON asset uploaded.

Example: 7.2

data_api_versionstringOptional

The version of the Data API specified by the developer in the Flow JSON asset uploaded. Only for Flows with an Endpoint.

Example: 3.0

data_channel_uristringOptional

The URL of the Endpoint specified by the developer in the Flow JSON asset uploaded. Only for Flows with an Endpoint.

Example: https://company.com/flow/signup/channel

endpoint_uristringOptional

The URL of the WA Flow Endpoint specified by the developer via API or in the Builder UI.

Example: https://company.com/flow/signup

400

Wrong payload

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id} HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "2141298723942",
  "name": "Sign Up",
  "status": "DRAFT",
  "categories": [
    "SIGN_UP",
    "SIGN_IN"
  ],
  "validation_errors": [],
  "json_version": "7.2",
  "data_api_version": "3.0",
  "data_channel_uri": "https://company.com/flow/signup/channel",
  "preview": {
    "preview_url": "https://wa.com/flow/preview/abcd1234",
    "expires_at": "2023-05-21T11:18:09+0000"
  },
  "whatsapp_business_account": {
    "id": "1087234212320",
    "name": "My Business Account",
    "currency": "USD",
    "timezone_id": "47",
    "message_template_namespace": "kljasas_38197nkbhjgv_aajskd"
  },
  "endpoint_uri": "https://company.com/flow/signup",
  "metric": {
    "data_points": [
      {
        "timestamp": "2024-01-28T08:00:00+0000",
        "data": [
          {
            "key": "timeout_error",
            "value": 5.2
          }
        ]
      }
    ],
    "name": "ENDPOINT_REQUEST_ERROR",
    "granularity": "DAY"
  }
}

Deleting a Flow

delete

While a Flow is in DRAFT status, it can be deleted. Use this request for that purpose.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Responses

200

Successful response

application/json

successbooleanOptional

Meta result of operation

400

Wrong payload

application/json

404

Not found

application/json

delete

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}

HTTPcURLJavaScriptPython

DELETE /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id} HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true
}

Updating a Flow

patch

After you have created your Flow, you can update the name or categories using the update request.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Body

application/json

namestringRequired

Flow name

Example: Sign Up

endpoint_uristringOptional

The URL of the WA Flow Endpoint. Starting from Flow JSON version 3.0 this property should be specified .Do not provide this field if you are updating a Flow with Flow JSON version below 3.0.

Example: https://company.com/flow/signup

Responses

200

Successful response

application/json

successbooleanOptional

Meta result of operation

400

Wrong payload

application/json

404

Not found

application/json

patch

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}

HTTPcURLJavaScriptPython

PATCH /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id} HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "name": "Sign Up",
  "categories": [
    "SIGN_UP",
    "SIGN_IN"
  ],
  "endpoint_uri": "https://company.com/flow/signup"
}

{
  "success": true
}

Getting Flow assets

get

Returns all assets attached to a specified Flow.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Responses

200

Successful response

application/json

countintegerOptionalExample: 1

totalintegerOptionalExample: 1

400

Wrong payload

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/assets

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/assets HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "assets": [
    {
      "name": "flow.json",
      "asset_type": "FLOW_JSON",
      "download_url": "https://mmg.whatsapp.net/m1/v/t24/kjh123921"
    }
  ],
  "count": 1,
  "total": 1
}

Updating a Flow's Flow JSON

post

You can update a Flow's Flow JSON by uploading a new JSON file. The new JSON file must be a valid Flow JSON file.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Body

multipart/form-data

filestring · binaryRequired

Flow asset file. Currently only flow.json file is supported.

namestringRequired

Flow asset name. Currently supported value is only 'flow.json'.

asset_typestringRequired

Flow asset type. Currently only supported value is 'FLOW_JSON'.

Responses

200

Successful response

application/json

successbooleanOptional

400

Wrong payload

application/json

404

Not found

application/json

post

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/assets

HTTPcURLJavaScriptPython

POST /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/assets HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 51

{
  "file": "binary",
  "name": "text",
  "asset_type": "text"
}

{
  "success": true,
  "validation_errors": [
    {
      "error": "PATTERN_MISMATCH",
      "error_type": "FLOW_JSON_ERROR",
      "message": "'dqyNrSd9DPuvhku6fr_pM' should only consist of alphabets and underscores.",
      "line_start": 1,
      "line_end": 1,
      "column_start": 65,
      "column_end": 88
    }
  ]
}

Publish a Flow

post

This request updates the status of the Flow to "PUBLISHED". This action is not reversible. The Flow and its assets become immutable once published. To update the Flow after that, you must create a new Flow. You specify the existing Flow ID as the clone_flow_id parameter while creating to copy the existing flow.

You can publish your Flow once you have ensured that:

• All validation errors have been fixed

• The Flow meets the design principles of WhatsApp Flows

• The Flow complies with WhatsApp Terms of Service, the WhatsApp Business Messaging Policy and, if applicable, the WhatsApp Commerce Policy

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Responses

200

Successful response

application/json

successbooleanOptional

Meta result of operation

400

Wrong payload

application/json

404

Not found

application/json

post

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/publish

HTTPcURLJavaScriptPython

POST /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/publish HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true
}

Preview a Flow

get

In order to visualize the Flows created, you can generate a web preview URL with this request. The preview URL is public and can be shared with different stakeholders to visualize the Flow. Note: Web preview URLs are only used to visualize how the screens will look - they will not be interactive. The final screens will render slightly differently for the end user.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Query parameters

invalidatebooleanOptional

invalidate=true will generate a new link.

Default: falseExample: true

Responses

200

Successful response

application/json

idstringOptional

The unique ID of the Flow.

Example: 2141298723942

400

Wrong payload

application/json

404

Not found

application/json

get

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/preview

HTTPcURLJavaScriptPython

GET /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/preview HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "2141298723942",
  "preview": {
    "preview_url": "https://wa.com/flow/preview/abcd1234",
    "expires_at": "2023-05-21T11:18:09+0000"
  }
}

Deprecate a Flow

post

Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.

Authorizations

PartnerApiKeyV2Bearer

X-API-KeystringRequired

API Key for V2 authentication. Send your Partner API key in the X-API-Key header. Preferred authentication method.

Path parameters

partner_idstringRequired

The ID of the partner.

Example: examplePA

waba_account_idstringRequired

The ID of the waba account.

Example: exampleWA

flow_external_idstringRequired

Flow id.

Example: 3221498293

Responses

200

Successful response

application/json

successbooleanOptional

Meta result of operation

400

Wrong payload

application/json

404

Not found

application/json

post

/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/deprecate

HTTPcURLJavaScriptPython

POST /api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_external_id}/deprecate HTTP/1.1
Host: hub.360dialog.io
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true
}