Skip to main content
POST
/
api
/
save-flow.php
Save Flow
curl --request POST \
  --url https://api.example.com/api/save-flow.php \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": 123,
  "parent_id": {},
  "node_type": "<string>",
  "content": "<string>",
  "options": [
    {}
  ],
  "metadata": {},
  "order_position": 123,
  "_import": true,
  "json": [
    {}
  ]
}
'
{
  "success": true,
  "node_id": 123,
  "error": "<string>",
  "imported_nodes": 123
}

Overview

Creates a new flow node or updates an existing one. Also supports bulk import of flow structures via JSON.

Request

id
integer
Node ID for updates. Omit or set to null to create a new node.
parent_id
integer | null
ID of parent node. Use null for root nodes.
node_type
string
required
Type of node:
  • "message" - Bot sends a message
  • "question" - Bot asks a question
  • "menu" - Multiple choice options
  • "end" - Conversation endpoint
content
string
required
Message text, question, or prompt to display
options
array
Array of menu options (required for node_type: "menu")Each option should have:
  • label (string): Display text
  • value (string): Option value/identifier
metadata
object
Additional configuration:
  • validation (string): Validation type for questions ("text", "email", "phone", etc.)
  • required (boolean): Whether response is mandatory
  • action (string): Special action to trigger
  • Custom key-value pairs
order_position
integer
Display order among sibling nodes (defaults to next available position)

Import Mode

_import
boolean
Set to true to enable bulk import mode
json
array
Array of node objects to import (required when _import: true)

Examples

curl -X POST https://your-domain.com/api/save-flow.php \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": null,
    "node_type": "message",
    "content": "¡Bienvenido a nuestro servicio!",
    "order_position": 1
  }'

Response

Standard Mode

success
boolean
required
Indicates if the node was saved successfully
node_id
integer
ID of the created or updated node
error
string
Error description (only present on failure)

Success Response Example

{
  "success": true,
  "node_id": 42
}

Import Mode

success
boolean
required
Indicates if import was successful
imported_nodes
integer
Number of nodes successfully imported

Import Success Response

{
  "success": true,
  "imported_nodes": 15
}

Error Response Examples

Validation Error
{
  "success": false,
  "error": "node_type is required"
}
Import Error
{
  "success": false,
  "error": "Campo \"json\" requerido para importación"
}
Invalid JSON
{
  "success": false,
  "error": "JSON inválido"
}

Error Handling

Status CodeDescription
200Node saved successfully
400Invalid JSON
405Method not allowed (only POST accepted)
422Validation error (invalid node data)
500Internal server error

Validation Rules

node_type is required and must be one of: message, question, menu, end
content is required for all node types
options array is required when node_type is menu
parent_id must reference an existing node (or be null for root)
Import mode requires json field with array of nodes

Implementation Details

The endpoint:
  1. Validates request method is POST
  2. Parses and validates JSON input
  3. Checks for import mode (_import flag)
  4. For standard mode: calls FlowBuilderService->saveNode()
  5. For import mode: calls FlowBuilderService->importFromJson()
  6. Returns appropriate success/error response
  7. Logs all operations for audit trail
Source: api/save-flow.php:11-44

Notes

When updating a node, only include fields you want to change. Omitted fields retain their current values.
Importing flows does not delete existing nodes. Use the delete endpoint first if you want a complete replacement.

Use Cases

  • Flow Builder: Create/update nodes via drag-and-drop UI
  • Bulk Import: Migrate flows from another system
  • Templates: Deploy pre-built flow templates
  • Version Control: Import flows from version-controlled JSON files

Build docs developers (and LLMs) love