Skip to main content
POST
/
api
/
simulate-flow.php
Simulate Flow
curl --request POST \
  --url https://api.example.com/api/simulate-flow.php \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "reset": true
}
'
{
  "success": true,
  "type": "<string>",
  "response": "<string>",
  "reset": true
}

Overview

Simulates a conversation through the flow-based bot without sending actual WhatsApp messages. This endpoint maintains session state for testing multi-step conversations.
Each simulation session is identified by your PHP session ID. Multiple browser tabs will share the same simulation session.

Request

message
string
required
User message to process through the flow
reset
boolean
Set to true to clear the simulation session and start over
curl -X POST https://your-domain.com/api/simulate-flow.php \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello"
  }'

Response

Message Response

success
boolean
required
Indicates if the simulation was successful
type
string
required
Type of response:
  • "message" - Bot sent a text message
  • "menu" - Bot presented a menu with options
  • "question" - Bot asked a question
  • "end" - Conversation ended
  • "error" - Invalid input or flow error
response
string
required
Bot’s response text

Reset Response

success
boolean
required
Indicates if reset was successful
reset
boolean
required
Confirms session was reset (always true)

Examples

Complete Conversation Simulation

{
  "message": "Hi"
}

Reset Example

Request
{
  "reset": true
}
Response
{
  "success": true,
  "reset": true
}

Error Example

Request (missing field)
{
  "message": ""
}
Response
{
  "success": false,
  "error": "Campo \"message\" requerido"
}

Error Handling

Status CodeDescription
200Simulation processed successfully
400Missing or invalid message field
405Method not allowed (only POST accepted)
500Internal server error

Session Management

The simulation uses a synthetic phone number format for tracking:
SIM_{md5_of_session_id}
Session data is stored in the classic_flow_sessions table:
  • Current node position in flow
  • User responses
  • Conversation context

Session Lifecycle

  1. First message: Creates new simulation session at root node
  2. Subsequent messages: Continues from current position
  3. Reset: Deletes session data, next message starts fresh
  4. Browser restart: New PHP session = new simulation session

Implementation Details

The endpoint:
  1. Validates request method is POST
  2. Checks for required message field (unless resetting)
  3. Generates simulation phone number from session ID
  4. Handles reset by deleting session data
  5. Calls ClassicBotService->processMessage() for normal messages
  6. Maintains session state between requests
  7. Returns bot response with type classification
Source: api/simulate-flow.php:11-46

Use Cases

Flow Testing UI

class FlowSimulator {
  async send(message) {
    const response = await fetch('/api/simulate-flow.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message })
    });
    return response.json();
  }
  
  async reset() {
    await fetch('/api/simulate-flow.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ reset: true })
    });
  }
}

// Usage
const sim = new FlowSimulator();
const response1 = await sim.send('Hello');
console.log(response1.response);

await sim.reset();
const response2 = await sim.send('Hello'); // Starts over

Automated Flow Testing

async function testFlow(steps) {
  const sim = new FlowSimulator();
  await sim.reset();
  
  const results = [];
  for (const step of steps) {
    const response = await sim.send(step.input);
    results.push({
      input: step.input,
      expected: step.expected,
      actual: response.response,
      passed: response.response.includes(step.expected)
    });
  }
  
  return results;
}

// Test case
const testResults = await testFlow([
  { input: 'Hi', expected: 'Bienvenido' },
  { input: 'continue', expected: 'elige una opción' },
  { input: '1', expected: 'nombre completo' }
]);

Best Practices

Reset between tests: Always reset before starting a new test scenario
Test all paths: Simulate every possible conversation path
Validate responses: Check response type and content match expectations
Test edge cases: Try invalid inputs, empty messages, unexpected options
Simulation sessions are isolated from production WhatsApp conversations. You can test freely without affecting real users.

Build docs developers (and LLMs) love