Workflows API

The Workflows API allows you to create, read, update, and delete workflows programmatically. You can also manage workflow executions, monitor performance, and control workflow states.

List Workflows

Retrieve a list of all workflows in your account.

Request

GET /v1/workflows

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status (`active`, `inactive`, `draft`)
`channel`	string	Filter by communication channel
`search`	string	Search workflows by name or description

Response

{
  "data": [
    {
      "id": "workflow-123",
      "name": "Customer Support Bot",
      "description": "Automated customer support workflow",
      "status": "active",
      "channel": "whatsapp",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "execution_count": 1250,
      "success_rate": 0.95
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

Get Workflow

Retrieve details of a specific workflow.

Request

GET /v1/workflows/{workflow_id}

Response

{
  "data": {
    "id": "workflow-123",
    "name": "Customer Support Bot",
    "description": "Automated customer support workflow",
    "status": "active",
    "channel": "whatsapp",
    "configuration": {
      "trigger": {
        "type": "message",
        "keywords": ["help", "support", "question"]
      },
      "nodes": [
        {
          "id": "node-1",
          "type": "message",
          "content": "Hi! How can I help you today?",
          "next": "node-2"
        },
        {
          "id": "node-2",
          "type": "ai_response",
          "knowledge_base": "support-kb",
          "next": "node-3"
        }
      ]
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z",
    "execution_count": 1250,
    "success_rate": 0.95
  }
}

Create Workflow

Create a new workflow.

Request

POST /v1/workflows

Request Body

{
  "name": "New Customer Onboarding",
  "description": "Welcome new customers and collect information",
  "channel": "whatsapp",
  "configuration": {
    "trigger": {
      "type": "message",
      "keywords": ["start", "begin", "new"]
    },
    "nodes": [
      {
        "id": "welcome",
        "type": "message",
        "content": "Welcome! Let's get you started.",
        "next": "collect_info"
      },
      {
        "id": "collect_info",
        "type": "form",
        "fields": [
          {
            "name": "name",
            "type": "text",
            "required": true,
            "label": "What's your name?"
          }
        ],
        "next": "confirmation"
      }
    ]
  }
}

Response

{
  "data": {
    "id": "workflow-456",
    "name": "New Customer Onboarding",
    "description": "Welcome new customers and collect information",
    "status": "draft",
    "channel": "whatsapp",
    "created_at": "2024-01-25T09:15:00Z",
    "updated_at": "2024-01-25T09:15:00Z",
    "execution_count": 0,
    "success_rate": null
  }
}

Update Workflow

Update an existing workflow.

Request

PUT /v1/workflows/{workflow_id}

Request Body

{
  "name": "Updated Customer Onboarding",
  "description": "Enhanced welcome flow for new customers",
  "configuration": {
    "trigger": {
      "type": "message",
      "keywords": ["start", "begin", "new", "welcome"]
    },
    "nodes": [
      {
        "id": "welcome",
        "type": "message",
        "content": "Welcome to our platform! Let's get you started.",
        "next": "collect_info"
      }
    ]
  }
}

Response

{
  "data": {
    "id": "workflow-456",
    "name": "Updated Customer Onboarding",
    "description": "Enhanced welcome flow for new customers",
    "status": "draft",
    "channel": "whatsapp",
    "created_at": "2024-01-25T09:15:00Z",
    "updated_at": "2024-01-25T10:30:00Z",
    "execution_count": 0,
    "success_rate": null
  }
}

Delete Workflow

Delete a workflow permanently.

Request

DELETE /v1/workflows/{workflow_id}

Response

{
  "message": "Workflow deleted successfully"
}

Activate Workflow

Activate a workflow to start processing messages.

Request

POST /v1/workflows/{workflow_id}/activate

Response

{
  "data": {
    "id": "workflow-123",
    "status": "active",
    "activated_at": "2024-01-25T11:00:00Z"
  }
}

Deactivate Workflow

Deactivate a workflow to stop processing messages.

Request

POST /v1/workflows/{workflow_id}/deactivate

Response

{
  "data": {
    "id": "workflow-123",
    "status": "inactive",
    "deactivated_at": "2024-01-25T12:00:00Z"
  }
}

Workflow Executions

List Executions

Get a list of workflow executions.

Request

GET /v1/workflows/{workflow_id}/executions

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status (`success`, `failed`, `running`)
`start_date`	string	Filter executions after this date (ISO 8601)
`end_date`	string	Filter executions before this date (ISO 8601)

Response

{
  "data": [
    {
      "id": "execution-789",
      "workflow_id": "workflow-123",
      "status": "success",
      "started_at": "2024-01-25T10:30:00Z",
      "completed_at": "2024-01-25T10:30:15Z",
      "duration_ms": 15000,
      "customer_id": "customer-456",
      "channel": "whatsapp",
      "input": {
        "message": "I need help with my order"
      },
      "output": {
        "response": "I'd be happy to help with your order. What's your order number?",
        "next_action": "wait_for_input"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Get Execution Details

Get detailed information about a specific execution.

Request

GET /v1/workflows/{workflow_id}/executions/{execution_id}

Response

{
  "data": {
    "id": "execution-789",
    "workflow_id": "workflow-123",
    "status": "success",
    "started_at": "2024-01-25T10:30:00Z",
    "completed_at": "2024-01-25T10:30:15Z",
    "duration_ms": 15000,
    "customer_id": "customer-456",
    "channel": "whatsapp",
    "steps": [
      {
        "node_id": "welcome",
        "type": "message",
        "status": "completed",
        "started_at": "2024-01-25T10:30:00Z",
        "completed_at": "2024-01-25T10:30:02Z",
        "duration_ms": 2000,
        "input": {
          "message": "I need help with my order"
        },
        "output": {
          "message_sent": "Hi! How can I help you today?"
        }
      },
      {
        "node_id": "ai_response",
        "type": "ai_response",
        "status": "completed",
        "started_at": "2024-01-25T10:30:02Z",
        "completed_at": "2024-01-25T10:30:15Z",
        "duration_ms": 13000,
        "input": {
          "message": "I need help with my order"
        },
        "output": {
          "response": "I'd be happy to help with your order. What's your order number?",
          "confidence": 0.95
        }
      }
    ],
    "input": {
      "message": "I need help with my order"
    },
    "output": {
      "response": "I'd be happy to help with your order. What's your order number?",
      "next_action": "wait_for_input"
    }
  }
}

Workflow Analytics

Get Workflow Metrics

Retrieve analytics data for a specific workflow.

Request

GET /v1/workflows/{workflow_id}/metrics

Parameters

Parameter	Type	Description
`start_date`	string	Start date for metrics (ISO 8601)
`end_date`	string	End date for metrics (ISO 8601)
`granularity`	string	Data granularity (`hour`, `day`, `week`, `month`)

Response

{
  "data": {
    "workflow_id": "workflow-123",
    "period": {
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z"
    },
    "metrics": {
      "total_executions": 1250,
      "successful_executions": 1187,
      "failed_executions": 63,
      "success_rate": 0.95,
      "average_duration_ms": 12000,
      "total_messages_sent": 2500,
      "total_messages_received": 1250,
      "unique_customers": 450,
      "channel_breakdown": {
        "whatsapp": 800,
        "instagram": 300,
        "voice": 150
      }
    },
    "daily_metrics": [
      {
        "date": "2024-01-01",
        "executions": 45,
        "success_rate": 0.96,
        "average_duration_ms": 11500
      }
    ]
  }
}

Error Handling

Common Error Codes

Status Code	Error Code	Description
400	`INVALID_WORKFLOW_CONFIG`	Workflow configuration is invalid
400	`MISSING_REQUIRED_FIELD`	Required field is missing
404	`WORKFLOW_NOT_FOUND`	Workflow does not exist
409	`WORKFLOW_ALREADY_EXISTS`	Workflow with this name already exists
422	`INVALID_NODE_CONFIG`	Node configuration is invalid
500	`WORKFLOW_EXECUTION_FAILED`	Workflow execution failed

Error Response Format

{
  "error": {
    "code": "INVALID_WORKFLOW_CONFIG",
    "message": "Workflow configuration is invalid",
    "details": "Node 'welcome' is missing required field 'content'",
    "field": "configuration.nodes[0].content"
  }
}

Rate Limiting

Workflow API endpoints are subject to rate limiting:

List/Get operations: 1000 requests per hour
Create/Update operations: 100 requests per hour
Delete operations: 50 requests per hour
Execution operations: 500 requests per hour

Next Steps

Explore more API endpoints:

Triggers API

Manage workflow triggers

Analytics API

Access analytics data

Webhooks API

Set up webhook integrations

Authentication

Learn about API authentication

​Workflows API

​List Workflows

​Request

​Parameters

​Response

​Get Workflow

​Request

​Response

​Create Workflow

​Request

​Request Body

​Response

​Update Workflow

​Request

​Request Body

​Response

​Delete Workflow

​Request

​Response

​Activate Workflow

​Request

​Response

​Deactivate Workflow

​Request

​Response

​Workflow Executions

​List Executions

​Request

​Parameters

​Response

​Get Execution Details

​Request

​Response

​Workflow Analytics

​Get Workflow Metrics

​Request

​Parameters

​Response

​Error Handling

​Common Error Codes

​Error Response Format

​Rate Limiting

​Next Steps

Triggers API

Analytics API

Webhooks API

Authentication

Workflows API

List Workflows

Request

Parameters

Response

Get Workflow

Request

Response

Create Workflow

Request

Request Body

Response

Update Workflow

Request

Request Body

Response

Delete Workflow

Request

Response

Activate Workflow

Request

Response

Deactivate Workflow

Request

Response

Workflow Executions

List Executions

Request

Parameters

Response

Get Execution Details

Request

Response

Workflow Analytics

Get Workflow Metrics

Request

Parameters

Response

Error Handling

Common Error Codes

Error Response Format

Rate Limiting

Next Steps