Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Chatbot Steps

Lists all steps for a flow

get

Required Permission: chatbots.steps.list

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flows.

Responses
200

List of all Steps.

application/json
errorstringOptional

Optional error message.

get/v1/chatbots/{chatbotId}/flows/{flowId}/steps
GET /v1/chatbots/{chatbotId}/flows/{flowId}/steps HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "steps": [
    {
      "id": "step123",
      "name": "Welcome Message",
      "created": "2023-01-01T12:00:00Z",
      "updated": "2023-01-01T12:30:00Z",
      "type": "message",
      "grid": {
        "x": 100,
        "y": 200
      },
      "elements": [
        {
          "type": "text",
          "content": {
            "text": {
              "text": {
                "DE": "Hallo Welt!",
                "EN-GB": "Hello World!"
              }
            },
            "buttons": {
              "buttons": [
                {
                  "text": {
                    "de": "Ja",
                    "en": "Yes"
                  },
                  "value": "flow_123/step_456",
                  "type": "redirect",
                  "payload": "BUTTON_CLICKED"
                }
              ]
            },
            "file": {
              "name": "document.pdf",
              "bucketId": "bucket789",
              "objectId": "object1011",
              "mimeType": "application/pdf",
              "sizeInByte": 102400,
              "fbaId": "fba123",
              "waaId": "waa456"
            },
            "voiceHangup": {
              "reason": "user_disconnected",
              "headers": {
                "X-Reason-Code": "1001"
              }
            },
            "voiceTransfer": {
              "target": "+1234567890",
              "reason": "agent_transfer",
              "headers": {
                "X-Transfer-ID": "abc-123"
              }
            },
            "agentHandover": {
              "reason": "escalation",
              "timeoutSeconds": 60,
              "agentId": "agent987",
              "groupId": "support_team",
              "assignmentMethod": "round_robin"
            },
            "assignVariable": {
              "variableId": "varUserQuery",
              "path": "$.data.query",
              "value": "What is your return policy?"
            },
            "updateTags": {
              "method": "add",
              "tagId": "tag_vip_customer"
            },
            "snooze": {
              "seconds": 3600
            },
            "unread": {
              "unread": true
            },
            "whatsappTemplate": {
              "templateId": "template_order_update",
              "parameters": {
                "customer_name": "John Doe",
                "order_id": "12345"
              }
            },
            "textToSpeech": {
              "text": {
                "en": "Your call is important to us."
              },
              "speech": "<speak>Hello <break time='1s'/> World!</speak>"
            },
            "callSettings": {
              "userInputSpeechDetectionTimeout": 5000,
              "dtmf": true,
              "bargeIn": true
            },
            "metaWhatsappTemplate": {
              "templateName": "order_confirmation",
              "templateId": "meta_tpl_123",
              "header": {
                "file": {
                  "name": "document.pdf",
                  "bucketId": "bucket789",
                  "objectId": "object1011",
                  "mimeType": "application/pdf",
                  "sizeInByte": 102400,
                  "fbaId": "fba123",
                  "waaId": "waa456"
                },
                "parameters": [
                  "{{1}}",
                  "User Name"
                ]
              },
              "bodyParameters": [
                "{{1}}",
                "Order Number"
              ],
              "buttons": {
                "values": [
                  "button_value_1",
                  "button_value_2"
                ]
              }
            },
            "note": {
              "note": "Follow up with customer next week."
            },
            "chatEnd": {
              "status": 3
            },
            "assignTeam": {
              "teamId": "team_sales"
            },
            "assignOperator": {
              "operatorId": "operator_john",
              "assignToLastAssigned": true
            }
          }
        }
      ],
      "intent": {
        "intentId": "t8gsDajqeJAVMZQPB5mp"
      },
      "delay": {
        "seconds": 5,
        "deleteIfConClosed": false
      },
      "split": {
        "a": 50,
        "b": 50,
        "sameRedirect": false,
        "redirects": {
          "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
          "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
        }
      },
      "condition": {
        "redirects": {
          "t": "stepTrue",
          "f": "stepFalse"
        },
        "conditions": [
          {
            "valueLeft": "{{variable.name}}",
            "operator": "==",
            "valueRight": "some_value",
            "group": 1
          }
        ]
      },
      "flow": {
        "outlets": {
          "success": {
            "stepId": "stepSuccess",
            "name": "Success"
          }
        },
        "flowId": "flowABC",
        "entryStepId": "entryStep1",
        "redirects": {
          "complete": "stepComplete"
        }
      },
      "trigger": {
        "triggerId": "gVh98q1ILzabR51miQbH",
        "event": "user_subscribed",
        "payload": "premium_plan"
      },
      "redirect": "redirectStep456",
      "userInput": "Please enter your name.",
      "userInputRequired": true,
      "context": {
        "intents": [
          {
            "name": "GreetingIntent",
            "intentId": "intent456",
            "redirect": "step789"
          }
        ],
        "fallbackRedirect": "stepFallback"
      },
      "app": {
        "appId": "appCRM",
        "moduleId": "moduleCreateLead",
        "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
      },
      "description": "This step greets the user and asks for their name.",
      "entityDetection": {
        "outputVariableId": "varDetectedEntities",
        "outputVariablePath": "$.entities",
        "prompt": "Extract entities from: {{user_input}}",
        "examples": [
          {
            "value": "I want to book a flight to London.",
            "result": "{'city': 'London'}"
          }
        ]
      },
      "userInputIsSensitive": false,
      "runPrompt": {
        "outputVariableId": "varPromptOutput",
        "outputVariablePath": "$.response",
        "prompt": "Generate a summary of the conversation.",
        "includeConversationHistory": true,
        "useRag": true,
        "includeNotes": true,
        "knowledgeGroupIds": [
          "kg1",
          "kg2"
        ],
        "ragContextMessages": 5,
        "contextMessageCount": 10
      },
      "leadAiConversation": {
        "prompt": "Help the user book a flight.",
        "context": "User wants to travel to Paris.",
        "maxIterations": 5,
        "ragContextMessages": 5,
        "includeConversationHistory": true,
        "outlets": [
          {
            "name": "BookFlight",
            "description": "Books a flight for the user.",
            "redirect": "stepBookFlight"
          }
        ],
        "tools": [
          {
            "appId": "app123",
            "moduleId": "module456",
            "description": "Searches for available flights.",
            "name": "FlightSearchTool"
          }
        ],
        "useRag": true,
        "delayMin": 10,
        "delayMax": 20,
        "delay": true,
        "knowledgeGroupIds": [
          "kg_flights",
          "kg_destinations"
        ],
        "contextMessageCount": 10
      },
      "contactData": {
        "values": "{\"email\": \"user@example.com\"}"
      },
      "aiConfig": {
        "model": 1,
        "thinkingBudget": 256,
        "seed": 42,
        "topP": 0.9,
        "temperature": 0.8
      },
      "end": {
        "payload": "thank-you",
        "closeConversation": true
      }
    }
  ],
  "error": "text"
}

Creates a new step within a flow

post

Required Permission: chatbots.steps.create

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flows.

Body
namestringRequired

The name of the step.

Example: Initial Greeting
typestringRequired

The type of the step.

Example: message
redirectstringOptional

Optional step ID to redirect to.

Example: redirectStepABC
descriptionstringOptional

An optional description for the step.

Example: This step welcomes the user.
Responses
201

Step created successfully.

application/json
post/v1/chatbots/{chatbotId}/flows/{flowId}/steps
POST /v1/chatbots/{chatbotId}/flows/{flowId}/steps HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 4150

{
  "name": "Initial Greeting",
  "type": "message",
  "grid": {
    "x": 100,
    "y": 200
  },
  "elements": [
    {
      "type": "text",
      "content": {
        "text": {
          "text": {
            "DE": "Hallo Welt!",
            "EN-GB": "Hello World!"
          }
        },
        "buttons": {
          "buttons": [
            {
              "text": {
                "de": "Ja",
                "en": "Yes"
              },
              "value": "flow_123/step_456",
              "type": "redirect",
              "payload": "BUTTON_CLICKED"
            }
          ]
        },
        "file": {
          "name": "document.pdf",
          "bucketId": "bucket789",
          "objectId": "object1011",
          "mimeType": "application/pdf",
          "sizeInByte": 102400,
          "fbaId": "fba123",
          "waaId": "waa456"
        },
        "voiceHangup": {
          "reason": "user_disconnected",
          "headers": {
            "X-Reason-Code": "1001"
          }
        },
        "voiceTransfer": {
          "target": "+1234567890",
          "reason": "agent_transfer",
          "headers": {
            "X-Transfer-ID": "abc-123"
          }
        },
        "agentHandover": {
          "reason": "escalation",
          "timeoutSeconds": 60,
          "agentId": "agent987",
          "groupId": "support_team",
          "assignmentMethod": "round_robin"
        },
        "assignVariable": {
          "variableId": "varUserQuery",
          "path": "$.data.query",
          "value": "What is your return policy?"
        },
        "updateTags": {
          "method": "add",
          "tagId": "tag_vip_customer"
        },
        "snooze": {
          "seconds": 3600
        },
        "unread": {
          "unread": true
        },
        "whatsappTemplate": {
          "templateId": "template_order_update",
          "parameters": {
            "customer_name": "John Doe",
            "order_id": "12345"
          }
        },
        "textToSpeech": {
          "text": {
            "en": "Your call is important to us."
          },
          "speech": "<speak>Hello <break time='1s'/> World!</speak>"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 5000,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_confirmation",
          "templateId": "meta_tpl_123",
          "header": {
            "file": {
              "name": "document.pdf",
              "bucketId": "bucket789",
              "objectId": "object1011",
              "mimeType": "application/pdf",
              "sizeInByte": 102400,
              "fbaId": "fba123",
              "waaId": "waa456"
            },
            "parameters": [
              "{{1}}",
              "User Name"
            ]
          },
          "bodyParameters": [
            "{{1}}",
            "Order Number"
          ],
          "buttons": {
            "values": [
              "button_value_1",
              "button_value_2"
            ]
          }
        },
        "note": {
          "note": "Follow up with customer next week."
        },
        "chatEnd": {
          "status": 3
        },
        "assignTeam": {
          "teamId": "team_sales"
        },
        "assignOperator": {
          "operatorId": "operator_john",
          "assignToLastAssigned": true
        }
      }
    }
  ],
  "delay": {
    "seconds": 5,
    "deleteIfConClosed": false
  },
  "split": {
    "a": 50,
    "b": 50,
    "sameRedirect": false,
    "redirects": {
      "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
      "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
    }
  },
  "condition": {
    "redirects": {
      "t": "stepTrue",
      "f": "stepFalse"
    },
    "conditions": [
      {
        "valueLeft": "{{variable.name}}",
        "operator": "==",
        "valueRight": "some_value",
        "group": 1
      }
    ]
  },
  "trigger": {
    "event": "user_subscribed",
    "payload": "premium_plan"
  },
  "redirect": "redirectStepABC",
  "context": {
    "intents": [
      {
        "name": "GreetingIntent",
        "intentId": "intent456",
        "redirect": "step789"
      }
    ],
    "fallbackRedirect": "stepFallback"
  },
  "app": {
    "appId": "appCRM",
    "moduleId": "moduleCreateLead",
    "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
  },
  "entityDetection": {
    "outputVariableId": "varDetectedEntities",
    "outputVariablePath": "$.entities",
    "prompt": "Extract entities from: {{user_input}}",
    "examples": [
      {
        "value": "I want to book a flight to London.",
        "result": "{'city': 'London'}"
      }
    ]
  },
  "description": "This step welcomes the user.",
  "flow": {
    "outlets": {
      "success": {
        "stepId": "stepSuccess",
        "name": "Success"
      }
    },
    "flowId": "flowABC",
    "entryStepId": "entryStep1",
    "redirects": {
      "complete": "stepComplete"
    }
  },
  "runPrompt": {
    "outputVariableId": "varPromptOutput",
    "outputVariablePath": "$.response",
    "prompt": "Generate a summary of the conversation.",
    "includeConversationHistory": true,
    "useRag": true,
    "includeNotes": true,
    "knowledgeGroupIds": [
      "kg1",
      "kg2"
    ],
    "ragContextMessages": 5,
    "contextMessageCount": 10
  },
  "leadAiConversation": {
    "prompt": "Help the user book a flight.",
    "context": "User wants to travel to Paris.",
    "maxIterations": 5,
    "ragContextMessages": 5,
    "includeConversationHistory": true,
    "outlets": [
      {
        "name": "BookFlight",
        "description": "Books a flight for the user.",
        "redirect": "stepBookFlight"
      }
    ],
    "tools": [
      {
        "appId": "app123",
        "moduleId": "module456",
        "description": "Searches for available flights.",
        "name": "FlightSearchTool"
      }
    ],
    "useRag": true,
    "delayMin": 10,
    "delayMax": 20,
    "delay": true,
    "knowledgeGroupIds": [
      "kg_flights",
      "kg_destinations"
    ],
    "contextMessageCount": 10
  },
  "contactData": {
    "values": "{\"email\": \"user@example.com\"}"
  },
  "aiConfig": {
    "model": 1,
    "thinkingBudget": 256,
    "seed": 42,
    "topP": 0.9,
    "temperature": 0.8
  },
  "conversationData": {
    "name": "Customer request",
    "language": "DE"
  },
  "end": {
    "payload": "thank-you",
    "closeConversation": true
  }
}
{
  "step": {
    "id": "step123",
    "name": "Welcome Message",
    "created": "2023-01-01T12:00:00Z",
    "updated": "2023-01-01T12:30:00Z",
    "type": "message",
    "grid": {
      "x": 100,
      "y": 200
    },
    "elements": [
      {
        "type": "text",
        "content": {
          "text": {
            "text": {
              "DE": "Hallo Welt!",
              "EN-GB": "Hello World!"
            }
          },
          "buttons": {
            "buttons": [
              {
                "text": {
                  "de": "Ja",
                  "en": "Yes"
                },
                "value": "flow_123/step_456",
                "type": "redirect",
                "payload": "BUTTON_CLICKED"
              }
            ]
          },
          "file": {
            "name": "document.pdf",
            "bucketId": "bucket789",
            "objectId": "object1011",
            "mimeType": "application/pdf",
            "sizeInByte": 102400,
            "fbaId": "fba123",
            "waaId": "waa456"
          },
          "voiceHangup": {
            "reason": "user_disconnected",
            "headers": {
              "X-Reason-Code": "1001"
            }
          },
          "voiceTransfer": {
            "target": "+1234567890",
            "reason": "agent_transfer",
            "headers": {
              "X-Transfer-ID": "abc-123"
            }
          },
          "agentHandover": {
            "reason": "escalation",
            "timeoutSeconds": 60,
            "agentId": "agent987",
            "groupId": "support_team",
            "assignmentMethod": "round_robin"
          },
          "assignVariable": {
            "variableId": "varUserQuery",
            "path": "$.data.query",
            "value": "What is your return policy?"
          },
          "updateTags": {
            "method": "add",
            "tagId": "tag_vip_customer"
          },
          "snooze": {
            "seconds": 3600
          },
          "unread": {
            "unread": true
          },
          "whatsappTemplate": {
            "templateId": "template_order_update",
            "parameters": {
              "customer_name": "John Doe",
              "order_id": "12345"
            }
          },
          "textToSpeech": {
            "text": {
              "en": "Your call is important to us."
            },
            "speech": "<speak>Hello <break time='1s'/> World!</speak>"
          },
          "callSettings": {
            "userInputSpeechDetectionTimeout": 5000,
            "dtmf": true,
            "bargeIn": true
          },
          "metaWhatsappTemplate": {
            "templateName": "order_confirmation",
            "templateId": "meta_tpl_123",
            "header": {
              "file": {
                "name": "document.pdf",
                "bucketId": "bucket789",
                "objectId": "object1011",
                "mimeType": "application/pdf",
                "sizeInByte": 102400,
                "fbaId": "fba123",
                "waaId": "waa456"
              },
              "parameters": [
                "{{1}}",
                "User Name"
              ]
            },
            "bodyParameters": [
              "{{1}}",
              "Order Number"
            ],
            "buttons": {
              "values": [
                "button_value_1",
                "button_value_2"
              ]
            }
          },
          "note": {
            "note": "Follow up with customer next week."
          },
          "chatEnd": {
            "status": 3
          },
          "assignTeam": {
            "teamId": "team_sales"
          },
          "assignOperator": {
            "operatorId": "operator_john",
            "assignToLastAssigned": true
          }
        }
      }
    ],
    "intent": {
      "intentId": "t8gsDajqeJAVMZQPB5mp"
    },
    "delay": {
      "seconds": 5,
      "deleteIfConClosed": false
    },
    "split": {
      "a": 50,
      "b": 50,
      "sameRedirect": false,
      "redirects": {
        "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
        "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
      }
    },
    "condition": {
      "redirects": {
        "t": "stepTrue",
        "f": "stepFalse"
      },
      "conditions": [
        {
          "valueLeft": "{{variable.name}}",
          "operator": "==",
          "valueRight": "some_value",
          "group": 1
        }
      ]
    },
    "flow": {
      "outlets": {
        "success": {
          "stepId": "stepSuccess",
          "name": "Success"
        }
      },
      "flowId": "flowABC",
      "entryStepId": "entryStep1",
      "redirects": {
        "complete": "stepComplete"
      }
    },
    "trigger": {
      "triggerId": "gVh98q1ILzabR51miQbH",
      "event": "user_subscribed",
      "payload": "premium_plan"
    },
    "redirect": "redirectStep456",
    "userInput": "Please enter your name.",
    "userInputRequired": true,
    "context": {
      "intents": [
        {
          "name": "GreetingIntent",
          "intentId": "intent456",
          "redirect": "step789"
        }
      ],
      "fallbackRedirect": "stepFallback"
    },
    "app": {
      "appId": "appCRM",
      "moduleId": "moduleCreateLead",
      "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
    },
    "description": "This step greets the user and asks for their name.",
    "entityDetection": {
      "outputVariableId": "varDetectedEntities",
      "outputVariablePath": "$.entities",
      "prompt": "Extract entities from: {{user_input}}",
      "examples": [
        {
          "value": "I want to book a flight to London.",
          "result": "{'city': 'London'}"
        }
      ]
    },
    "userInputIsSensitive": false,
    "runPrompt": {
      "outputVariableId": "varPromptOutput",
      "outputVariablePath": "$.response",
      "prompt": "Generate a summary of the conversation.",
      "includeConversationHistory": true,
      "useRag": true,
      "includeNotes": true,
      "knowledgeGroupIds": [
        "kg1",
        "kg2"
      ],
      "ragContextMessages": 5,
      "contextMessageCount": 10
    },
    "leadAiConversation": {
      "prompt": "Help the user book a flight.",
      "context": "User wants to travel to Paris.",
      "maxIterations": 5,
      "ragContextMessages": 5,
      "includeConversationHistory": true,
      "outlets": [
        {
          "name": "BookFlight",
          "description": "Books a flight for the user.",
          "redirect": "stepBookFlight"
        }
      ],
      "tools": [
        {
          "appId": "app123",
          "moduleId": "module456",
          "description": "Searches for available flights.",
          "name": "FlightSearchTool"
        }
      ],
      "useRag": true,
      "delayMin": 10,
      "delayMax": 20,
      "delay": true,
      "knowledgeGroupIds": [
        "kg_flights",
        "kg_destinations"
      ],
      "contextMessageCount": 10
    },
    "contactData": {
      "values": "{\"email\": \"user@example.com\"}"
    },
    "aiConfig": {
      "model": 1,
      "thinkingBudget": 256,
      "seed": 42,
      "topP": 0.9,
      "temperature": 0.8
    },
    "end": {
      "payload": "thank-you",
      "closeConversation": true
    }
  }
}

Retrieves a specific step

get

Required Permission: chatbots.steps.get

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flows.

stepIdstringRequired

The ID of the step to retrieve.

Responses
200

Details of the step.

application/json
errorstringOptional

Optional error message.

get/v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId}
GET /v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "step": {
    "id": "step123",
    "name": "Welcome Message",
    "created": "2023-01-01T12:00:00Z",
    "updated": "2023-01-01T12:30:00Z",
    "type": "message",
    "grid": {
      "x": 100,
      "y": 200
    },
    "elements": [
      {
        "type": "text",
        "content": {
          "text": {
            "text": {
              "DE": "Hallo Welt!",
              "EN-GB": "Hello World!"
            }
          },
          "buttons": {
            "buttons": [
              {
                "text": {
                  "de": "Ja",
                  "en": "Yes"
                },
                "value": "flow_123/step_456",
                "type": "redirect",
                "payload": "BUTTON_CLICKED"
              }
            ]
          },
          "file": {
            "name": "document.pdf",
            "bucketId": "bucket789",
            "objectId": "object1011",
            "mimeType": "application/pdf",
            "sizeInByte": 102400,
            "fbaId": "fba123",
            "waaId": "waa456"
          },
          "voiceHangup": {
            "reason": "user_disconnected",
            "headers": {
              "X-Reason-Code": "1001"
            }
          },
          "voiceTransfer": {
            "target": "+1234567890",
            "reason": "agent_transfer",
            "headers": {
              "X-Transfer-ID": "abc-123"
            }
          },
          "agentHandover": {
            "reason": "escalation",
            "timeoutSeconds": 60,
            "agentId": "agent987",
            "groupId": "support_team",
            "assignmentMethod": "round_robin"
          },
          "assignVariable": {
            "variableId": "varUserQuery",
            "path": "$.data.query",
            "value": "What is your return policy?"
          },
          "updateTags": {
            "method": "add",
            "tagId": "tag_vip_customer"
          },
          "snooze": {
            "seconds": 3600
          },
          "unread": {
            "unread": true
          },
          "whatsappTemplate": {
            "templateId": "template_order_update",
            "parameters": {
              "customer_name": "John Doe",
              "order_id": "12345"
            }
          },
          "textToSpeech": {
            "text": {
              "en": "Your call is important to us."
            },
            "speech": "<speak>Hello <break time='1s'/> World!</speak>"
          },
          "callSettings": {
            "userInputSpeechDetectionTimeout": 5000,
            "dtmf": true,
            "bargeIn": true
          },
          "metaWhatsappTemplate": {
            "templateName": "order_confirmation",
            "templateId": "meta_tpl_123",
            "header": {
              "file": {
                "name": "document.pdf",
                "bucketId": "bucket789",
                "objectId": "object1011",
                "mimeType": "application/pdf",
                "sizeInByte": 102400,
                "fbaId": "fba123",
                "waaId": "waa456"
              },
              "parameters": [
                "{{1}}",
                "User Name"
              ]
            },
            "bodyParameters": [
              "{{1}}",
              "Order Number"
            ],
            "buttons": {
              "values": [
                "button_value_1",
                "button_value_2"
              ]
            }
          },
          "note": {
            "note": "Follow up with customer next week."
          },
          "chatEnd": {
            "status": 3
          },
          "assignTeam": {
            "teamId": "team_sales"
          },
          "assignOperator": {
            "operatorId": "operator_john",
            "assignToLastAssigned": true
          }
        }
      }
    ],
    "intent": {
      "intentId": "t8gsDajqeJAVMZQPB5mp"
    },
    "delay": {
      "seconds": 5,
      "deleteIfConClosed": false
    },
    "split": {
      "a": 50,
      "b": 50,
      "sameRedirect": false,
      "redirects": {
        "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
        "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
      }
    },
    "condition": {
      "redirects": {
        "t": "stepTrue",
        "f": "stepFalse"
      },
      "conditions": [
        {
          "valueLeft": "{{variable.name}}",
          "operator": "==",
          "valueRight": "some_value",
          "group": 1
        }
      ]
    },
    "flow": {
      "outlets": {
        "success": {
          "stepId": "stepSuccess",
          "name": "Success"
        }
      },
      "flowId": "flowABC",
      "entryStepId": "entryStep1",
      "redirects": {
        "complete": "stepComplete"
      }
    },
    "trigger": {
      "triggerId": "gVh98q1ILzabR51miQbH",
      "event": "user_subscribed",
      "payload": "premium_plan"
    },
    "redirect": "redirectStep456",
    "userInput": "Please enter your name.",
    "userInputRequired": true,
    "context": {
      "intents": [
        {
          "name": "GreetingIntent",
          "intentId": "intent456",
          "redirect": "step789"
        }
      ],
      "fallbackRedirect": "stepFallback"
    },
    "app": {
      "appId": "appCRM",
      "moduleId": "moduleCreateLead",
      "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
    },
    "description": "This step greets the user and asks for their name.",
    "entityDetection": {
      "outputVariableId": "varDetectedEntities",
      "outputVariablePath": "$.entities",
      "prompt": "Extract entities from: {{user_input}}",
      "examples": [
        {
          "value": "I want to book a flight to London.",
          "result": "{'city': 'London'}"
        }
      ]
    },
    "userInputIsSensitive": false,
    "runPrompt": {
      "outputVariableId": "varPromptOutput",
      "outputVariablePath": "$.response",
      "prompt": "Generate a summary of the conversation.",
      "includeConversationHistory": true,
      "useRag": true,
      "includeNotes": true,
      "knowledgeGroupIds": [
        "kg1",
        "kg2"
      ],
      "ragContextMessages": 5,
      "contextMessageCount": 10
    },
    "leadAiConversation": {
      "prompt": "Help the user book a flight.",
      "context": "User wants to travel to Paris.",
      "maxIterations": 5,
      "ragContextMessages": 5,
      "includeConversationHistory": true,
      "outlets": [
        {
          "name": "BookFlight",
          "description": "Books a flight for the user.",
          "redirect": "stepBookFlight"
        }
      ],
      "tools": [
        {
          "appId": "app123",
          "moduleId": "module456",
          "description": "Searches for available flights.",
          "name": "FlightSearchTool"
        }
      ],
      "useRag": true,
      "delayMin": 10,
      "delayMax": 20,
      "delay": true,
      "knowledgeGroupIds": [
        "kg_flights",
        "kg_destinations"
      ],
      "contextMessageCount": 10
    },
    "contactData": {
      "values": "{\"email\": \"user@example.com\"}"
    },
    "aiConfig": {
      "model": 1,
      "thinkingBudget": 256,
      "seed": 42,
      "topP": 0.9,
      "temperature": 0.8
    },
    "end": {
      "payload": "thank-you",
      "closeConversation": true
    }
  },
  "error": "text"
}

Deletes a step

delete

Required Permission: chatbots.steps.delete

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flows.

stepIdstringRequired

The ID of the step to delete.

Responses
200

Result of the deletion process.

application/json
deletedbooleanRequired

Indicates if the step was successfully deleted.

Example: true
errorstringOptional

Optional error message.

delete/v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId}
DELETE /v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true,
  "error": "text"
}

Updates an existing step

patch

Required Permission: chatbots.steps.edit

Resource: chatbots/:chatbotId

Authorizations
x-chatcaptain-keystringRequired
Path parameters
chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flows.

stepIdstringRequired

The ID of the step to update.

Body
namestringOptional

The new name of the step.

Example: Updated Welcome Message
redirectstringOptional

Optional step ID to redirect to.

Example: flowId/stepId
userInputstringOptional

Optional user input redirect.

Example: flowId/stepId.
userInputRequiredbooleanOptional

Whether user input is required for this step.

Example: false
descriptionstringOptional

An optional description for the step.

Example: This step updates user information.
userInputIsSensitivebooleanOptional

Whether user input in this step is sensitive.

Example: true
Responses
200

Step updated successfully.

application/json
patch/v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId}
PATCH /v1/chatbots/{chatbotId}/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 4273

{
  "name": "Updated Welcome Message",
  "grid": {
    "x": 100,
    "y": 200
  },
  "elements": [
    {
      "type": "text",
      "content": {
        "text": {
          "text": {
            "DE": "Hallo Welt!",
            "EN-GB": "Hello World!"
          }
        },
        "buttons": {
          "buttons": [
            {
              "text": {
                "de": "Ja",
                "en": "Yes"
              },
              "value": "flow_123/step_456",
              "type": "redirect",
              "payload": "BUTTON_CLICKED"
            }
          ]
        },
        "file": {
          "name": "document.pdf",
          "bucketId": "bucket789",
          "objectId": "object1011",
          "mimeType": "application/pdf",
          "sizeInByte": 102400,
          "fbaId": "fba123",
          "waaId": "waa456"
        },
        "voiceHangup": {
          "reason": "user_disconnected",
          "headers": {
            "X-Reason-Code": "1001"
          }
        },
        "voiceTransfer": {
          "target": "+1234567890",
          "reason": "agent_transfer",
          "headers": {
            "X-Transfer-ID": "abc-123"
          }
        },
        "agentHandover": {
          "reason": "escalation",
          "timeoutSeconds": 60,
          "agentId": "agent987",
          "groupId": "support_team",
          "assignmentMethod": "round_robin"
        },
        "assignVariable": {
          "variableId": "varUserQuery",
          "path": "$.data.query",
          "value": "What is your return policy?"
        },
        "updateTags": {
          "method": "add",
          "tagId": "tag_vip_customer"
        },
        "snooze": {
          "seconds": 3600
        },
        "unread": {
          "unread": true
        },
        "whatsappTemplate": {
          "templateId": "template_order_update",
          "parameters": {
            "customer_name": "John Doe",
            "order_id": "12345"
          }
        },
        "textToSpeech": {
          "text": {
            "en": "Your call is important to us."
          },
          "speech": "<speak>Hello <break time='1s'/> World!</speak>"
        },
        "callSettings": {
          "userInputSpeechDetectionTimeout": 5000,
          "dtmf": true,
          "bargeIn": true
        },
        "metaWhatsappTemplate": {
          "templateName": "order_confirmation",
          "templateId": "meta_tpl_123",
          "header": {
            "file": {
              "name": "document.pdf",
              "bucketId": "bucket789",
              "objectId": "object1011",
              "mimeType": "application/pdf",
              "sizeInByte": 102400,
              "fbaId": "fba123",
              "waaId": "waa456"
            },
            "parameters": [
              "{{1}}",
              "User Name"
            ]
          },
          "bodyParameters": [
            "{{1}}",
            "Order Number"
          ],
          "buttons": {
            "values": [
              "button_value_1",
              "button_value_2"
            ]
          }
        },
        "note": {
          "note": "Follow up with customer next week."
        },
        "chatEnd": {
          "status": 3
        },
        "assignTeam": {
          "teamId": "team_sales"
        },
        "assignOperator": {
          "operatorId": "operator_john",
          "assignToLastAssigned": true
        }
      }
    }
  ],
  "delay": {
    "seconds": 5,
    "deleteIfConClosed": false
  },
  "split": {
    "a": 50,
    "b": 50,
    "sameRedirect": false,
    "redirects": {
      "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
      "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
    }
  },
  "condition": {
    "redirects": {
      "t": "stepTrue",
      "f": "stepFalse"
    },
    "conditions": [
      {
        "valueLeft": "{{variable.name}}",
        "operator": "==",
        "valueRight": "some_value",
        "group": 1
      }
    ]
  },
  "flow": {
    "outlets": {
      "success": {
        "stepId": "stepSuccess",
        "name": "Success"
      }
    },
    "flowId": "flowABC",
    "entryStepId": "entryStep1",
    "redirects": {
      "complete": "stepComplete"
    }
  },
  "trigger": {
    "event": "user_subscribed",
    "payload": "premium_plan"
  },
  "redirect": "flowId/stepId",
  "userInput": "flowId/stepId.",
  "userInputRequired": false,
  "context": {
    "intents": [
      {
        "name": "GreetingIntent",
        "intentId": "intent456",
        "redirect": "step789"
      }
    ],
    "fallbackRedirect": "stepFallback"
  },
  "app": {
    "appId": "appCRM",
    "moduleId": "moduleCreateLead",
    "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
  },
  "entityDetection": {
    "outputVariableId": "varDetectedEntities",
    "outputVariablePath": "$.entities",
    "prompt": "Extract entities from: {{user_input}}",
    "examples": [
      {
        "value": "I want to book a flight to London.",
        "result": "{'city': 'London'}"
      }
    ]
  },
  "description": "This step updates user information.",
  "userInputIsSensitive": true,
  "runPrompt": {
    "outputVariableId": "varPromptOutput",
    "outputVariablePath": "$.response",
    "prompt": "Generate a summary of the conversation.",
    "includeConversationHistory": true,
    "useRag": true,
    "includeNotes": true,
    "knowledgeGroupIds": [
      "kg1",
      "kg2"
    ],
    "ragContextMessages": 5,
    "contextMessageCount": 10
  },
  "leadAiConversation": {
    "prompt": "Help the user book a flight.",
    "context": "User wants to travel to Paris.",
    "maxIterations": 5,
    "ragContextMessages": 5,
    "includeConversationHistory": true,
    "outlets": [
      {
        "name": "BookFlight",
        "description": "Books a flight for the user.",
        "redirect": "stepBookFlight"
      }
    ],
    "tools": [
      {
        "appId": "app123",
        "moduleId": "module456",
        "description": "Searches for available flights.",
        "name": "FlightSearchTool"
      }
    ],
    "useRag": true,
    "delayMin": 10,
    "delayMax": 20,
    "delay": true,
    "knowledgeGroupIds": [
      "kg_flights",
      "kg_destinations"
    ],
    "contextMessageCount": 10
  },
  "intent": {
    "intentId": "t8gsDajqeJAVMZQPB5mp"
  },
  "contactData": {
    "values": "{\"email\": \"user@example.com\"}"
  },
  "aiConfig": {
    "model": 1,
    "thinkingBudget": 256,
    "seed": 42,
    "topP": 0.9,
    "temperature": 0.8
  },
  "conversationData": {
    "name": "Customer request",
    "language": "DE"
  },
  "end": {
    "payload": "thank-you",
    "closeConversation": true
  }
}
{
  "step": {
    "id": "step123",
    "name": "Welcome Message",
    "created": "2023-01-01T12:00:00Z",
    "updated": "2023-01-01T12:30:00Z",
    "type": "message",
    "grid": {
      "x": 100,
      "y": 200
    },
    "elements": [
      {
        "type": "text",
        "content": {
          "text": {
            "text": {
              "DE": "Hallo Welt!",
              "EN-GB": "Hello World!"
            }
          },
          "buttons": {
            "buttons": [
              {
                "text": {
                  "de": "Ja",
                  "en": "Yes"
                },
                "value": "flow_123/step_456",
                "type": "redirect",
                "payload": "BUTTON_CLICKED"
              }
            ]
          },
          "file": {
            "name": "document.pdf",
            "bucketId": "bucket789",
            "objectId": "object1011",
            "mimeType": "application/pdf",
            "sizeInByte": 102400,
            "fbaId": "fba123",
            "waaId": "waa456"
          },
          "voiceHangup": {
            "reason": "user_disconnected",
            "headers": {
              "X-Reason-Code": "1001"
            }
          },
          "voiceTransfer": {
            "target": "+1234567890",
            "reason": "agent_transfer",
            "headers": {
              "X-Transfer-ID": "abc-123"
            }
          },
          "agentHandover": {
            "reason": "escalation",
            "timeoutSeconds": 60,
            "agentId": "agent987",
            "groupId": "support_team",
            "assignmentMethod": "round_robin"
          },
          "assignVariable": {
            "variableId": "varUserQuery",
            "path": "$.data.query",
            "value": "What is your return policy?"
          },
          "updateTags": {
            "method": "add",
            "tagId": "tag_vip_customer"
          },
          "snooze": {
            "seconds": 3600
          },
          "unread": {
            "unread": true
          },
          "whatsappTemplate": {
            "templateId": "template_order_update",
            "parameters": {
              "customer_name": "John Doe",
              "order_id": "12345"
            }
          },
          "textToSpeech": {
            "text": {
              "en": "Your call is important to us."
            },
            "speech": "<speak>Hello <break time='1s'/> World!</speak>"
          },
          "callSettings": {
            "userInputSpeechDetectionTimeout": 5000,
            "dtmf": true,
            "bargeIn": true
          },
          "metaWhatsappTemplate": {
            "templateName": "order_confirmation",
            "templateId": "meta_tpl_123",
            "header": {
              "file": {
                "name": "document.pdf",
                "bucketId": "bucket789",
                "objectId": "object1011",
                "mimeType": "application/pdf",
                "sizeInByte": 102400,
                "fbaId": "fba123",
                "waaId": "waa456"
              },
              "parameters": [
                "{{1}}",
                "User Name"
              ]
            },
            "bodyParameters": [
              "{{1}}",
              "Order Number"
            ],
            "buttons": {
              "values": [
                "button_value_1",
                "button_value_2"
              ]
            }
          },
          "note": {
            "note": "Follow up with customer next week."
          },
          "chatEnd": {
            "status": 3
          },
          "assignTeam": {
            "teamId": "team_sales"
          },
          "assignOperator": {
            "operatorId": "operator_john",
            "assignToLastAssigned": true
          }
        }
      }
    ],
    "intent": {
      "intentId": "t8gsDajqeJAVMZQPB5mp"
    },
    "delay": {
      "seconds": 5,
      "deleteIfConClosed": false
    },
    "split": {
      "a": 50,
      "b": 50,
      "sameRedirect": false,
      "redirects": {
        "a": "flow/AAIVrMmsvmfYYeR4xo69/step/vnClGd8WHu3f4KY6dVYL",
        "b": "flow/vnClGd8WHu3f4KY6dVYL/step/AAIVrMmsvmfYYeR4xo69"
      }
    },
    "condition": {
      "redirects": {
        "t": "stepTrue",
        "f": "stepFalse"
      },
      "conditions": [
        {
          "valueLeft": "{{variable.name}}",
          "operator": "==",
          "valueRight": "some_value",
          "group": 1
        }
      ]
    },
    "flow": {
      "outlets": {
        "success": {
          "stepId": "stepSuccess",
          "name": "Success"
        }
      },
      "flowId": "flowABC",
      "entryStepId": "entryStep1",
      "redirects": {
        "complete": "stepComplete"
      }
    },
    "trigger": {
      "triggerId": "gVh98q1ILzabR51miQbH",
      "event": "user_subscribed",
      "payload": "premium_plan"
    },
    "redirect": "redirectStep456",
    "userInput": "Please enter your name.",
    "userInputRequired": true,
    "context": {
      "intents": [
        {
          "name": "GreetingIntent",
          "intentId": "intent456",
          "redirect": "step789"
        }
      ],
      "fallbackRedirect": "stepFallback"
    },
    "app": {
      "appId": "appCRM",
      "moduleId": "moduleCreateLead",
      "paramsJson": "{\"leadName\": \"{{variable.name}}\"}"
    },
    "description": "This step greets the user and asks for their name.",
    "entityDetection": {
      "outputVariableId": "varDetectedEntities",
      "outputVariablePath": "$.entities",
      "prompt": "Extract entities from: {{user_input}}",
      "examples": [
        {
          "value": "I want to book a flight to London.",
          "result": "{'city': 'London'}"
        }
      ]
    },
    "userInputIsSensitive": false,
    "runPrompt": {
      "outputVariableId": "varPromptOutput",
      "outputVariablePath": "$.response",
      "prompt": "Generate a summary of the conversation.",
      "includeConversationHistory": true,
      "useRag": true,
      "includeNotes": true,
      "knowledgeGroupIds": [
        "kg1",
        "kg2"
      ],
      "ragContextMessages": 5,
      "contextMessageCount": 10
    },
    "leadAiConversation": {
      "prompt": "Help the user book a flight.",
      "context": "User wants to travel to Paris.",
      "maxIterations": 5,
      "ragContextMessages": 5,
      "includeConversationHistory": true,
      "outlets": [
        {
          "name": "BookFlight",
          "description": "Books a flight for the user.",
          "redirect": "stepBookFlight"
        }
      ],
      "tools": [
        {
          "appId": "app123",
          "moduleId": "module456",
          "description": "Searches for available flights.",
          "name": "FlightSearchTool"
        }
      ],
      "useRag": true,
      "delayMin": 10,
      "delayMax": 20,
      "delay": true,
      "knowledgeGroupIds": [
        "kg_flights",
        "kg_destinations"
      ],
      "contextMessageCount": 10
    },
    "contactData": {
      "values": "{\"email\": \"user@example.com\"}"
    },
    "aiConfig": {
      "model": 1,
      "thinkingBudget": 256,
      "seed": 42,
      "topP": 0.9,
      "temperature": 0.8
    },
    "end": {
      "payload": "thank-you",
      "closeConversation": true
    }
  }
}
PreviousChatbot ModelsNextChatbot Templates

Last updated