Skip to main content

​
Flows

Flows are execution instances of campaigns that send messages to multiple contacts. They handle rate limiting, retries, error tracking, and provide real-time statistics.

​
Create Flow

POST /flows

Creates a new flow associated with a campaign and queues it for execution.

​
Request Body

​
string
required
Channel UID to use for sending messages
​
string
required
Campaign UID to use for this flow
​
array
required
Array of contact UIDs (identity UIDs) to send messages to
​
string
Flow description
​
object

​
Response

Returns a FlowResponseDTO with flow details including status, configuration, and metadata.

​
List Flows

GET /flows

Retrieves a paginated list of flows with filtering options.

​
Query Parameters

​
string
Filter flows by associated contact/identity
​
string
Filter flows by channel
​
string
Filter by status: draft, queued, running, paused, completed, partial_completed, cancelled, failed, error, timeout
​
string
Cursor for pagination
​
number
Maximum results (default: 20, max: 100)

​
Get Flow

GET /flows/{uid}

Retrieves detailed information about a specific flow, including execution status, statistics, and metadata.
​
uid
string
required
Flow unique identifier (UUID)

​
Response

​
message
string
Success message
​
data
object

​
Update Flow

PATCH /flows/{uid}

Updates an existing flow. Status transitions must be valid.
​
uid
string
required
Flow unique identifier (UUID)

​
Request Body

​
string
New status: draft, queued, running, paused, completed, partial_completed, cancelled, failed, error, timeout
​
string
Updated description

​
Delete Flow

DELETE /flows/{uid}

Deletes a flow. Active flows (RUNNING, QUEUED) cannot be deleted.
​
uid
string
required
Flow unique identifier (UUID)

​
Flow Status

Flows progress through these statuses:
  • draft - Created but not started
  • queued - Ready to execute
  • running - Currently executing
  • paused - Temporarily paused
  • completed - Successfully finished
  • partial_completed - Finished with some failures
  • cancelled - Manually cancelled
  • failed - Execution failed
  • error - Error occurred
  • timeout - Execution timeout

​
Flow Configuration

​
Rate Limiting

  • pauseBetweenContactsMs - Base delay between messages (e.g., 5000ms = 5 seconds)
  • pauseBetweenContactsSaltMs - Random variation (e.g., 1000ms = ±1 second random)
  • Actual pause = pauseBetweenContactsMs ± random(0 to pauseBetweenContactsSaltMs)

​
Concurrency

  • maxConcurrentMessages - How many messages send simultaneously (1-10)
  • Lower = slower but safer
  • Higher = faster but may hit rate limits

​
Retries

  • maxRetries - Maximum retry attempts per message
  • retryDelayMs - Delay before retrying failed messages

​
Timeout

  • timeoutMs - Maximum time to wait for message delivery (5-10 minutes recommended)

​
Examples

​
Create Flow

curl -X POST https://api.plati.ai/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelUid": "channel-uuid-123",
    "campaignUid": "campaign-uuid-456",
    "contactUids": [
      "identity-uuid-1",
      "identity-uuid-2",
      "identity-uuid-3"
    ],
    "description": "Black Friday campaign for VIP customers",
    "configuration": {
      "maxRetries": 3,
      "pauseBetweenContactsMs": 5000,
      "pauseBetweenContactsSaltMs": 1000,
      "retryDelayMs": 5000,
      "timeoutMs": 300000,
      "maxConcurrentMessages": 1
    }
  }'

​
Get Flow Status

curl -X GET https://api.plati.ai/flows/flow-uuid-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Pause Flow

curl -X PATCH https://api.plati.ai/flows/flow-uuid-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

​
Resume Flow

curl -X PATCH https://api.plati.ai/flows/flow-uuid-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "running"
  }'

​
Monitoring Flows

Monitor flow execution in real-time:
  1. Get Flow - Check current status and statistics
  2. List Flows - Filter by status to see all running/paused flows
  3. Metadata - Review errors and failure reasons
  4. Stats - Track delivery rates and performance

​
Next Steps

Campaigns

Create campaigns for flows

Crossbow Guide

Complete Crossbow guide