---
title: "Create Call Flow"
api: "POST /v1/api/call-flows"
description: "Create a new call flow with full settings."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

### Headers  
<ParamField header="x-workspace-id" type="string" required>
  Workspace identifier for the API.
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  A friendly name for this call flow (e.g., "Customer Support Flow").
</ParamField>

<ParamField body="direction" type="string" required>
  Direction of the flow. Possible values: "outbound", "bidirectional".
</ParamField>

<ParamField body="description" type="string">
  Description of the call flow (e.g. "Handles inbound support calls").
</ParamField>

<ParamField body="agent" type="string">
  ID of the agent to associate with this flow. If provided, the system looks for a pending phone number for that agent and activates it.
</ParamField>

<ParamField body="promptType" default="simple" type="string" required>
  Only "simple" type of prompt configuration is allowed now.
</ParamField>

<ParamField body="folderId" type="string">
  ID of the folder to organize this call flow.
</ParamField>

<ParamField body="isGlobal" type="boolean">
  Whether this is a global call flow. Only specific workspaces can create global flows.
</ParamField>

<ParamField body="isPreConfigured" type="boolean">
  Whether this call flow is pre-configured. Defaults to false.
</ParamField>

<ParamField body="preConfiguredWorkspaceId" type="string">
  Workspace ID for pre-configured flows.
</ParamField>

<ParamField body="welcomeMessage" type="string">
  Welcome message type. Possible values: "user_initiated", "ai_dynamic", "ai_custom". Defaults to "user_initiated".
</ParamField>

<ParamField body="customWelcomeMessage" type="string">
  Custom welcome message text when welcomeMessage is set to "ai_custom" only.
</ParamField>

<ParamField body="flowData" type="object">
  Flow-based configuration using a node/edge approach for complex call routing.

  <Expandable title="flowData">
    <ParamField body="nodes" type="array">
      Array of node objects, each representing a point in the call routing process. Each node object may include properties like `id`, `type`, and `data` for custom configurations.
    </ParamField>
    <ParamField body="edges" type="array">
      Array of edge objects, connecting the nodes defined in the `nodes` array. Each edge object can specify the source and target nodes, along with additional routing logic.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prompt" type="string">
  A system or initial prompt for the flow. This will be used to create the first prompt version.
</ParamField>


<ParamField body="isActive" type="boolean">
  Whether the flow is currently active. Defaults to true.
</ParamField>

<ParamField body="agentWebhookUrl" type="string">
  Webhook URL for agent-related events.
</ParamField>

<ParamField body="inboundWebhookUrl" type="string">
  Webhook URL for inbound call events.
</ParamField>

<ParamField body="dynamicVariableCollections" type="array">
  Array of dynamic variable collections for the call flow.
  
  <Expandable title="dynamicVariableCollections">
    <ParamField body="id" type="string" required>
      Unique identifier for the variable collection.
    </ParamField>
    <ParamField body="name" type="string" required>
      Name of the variable collection.
    </ParamField>
    <ParamField body="variables" type="array">
      Array of key-value pairs for variables.
      <ParamField body="key" type="string">
        Variable key name.
      </ParamField>
      <ParamField body="value" type="string">
        Variable value.
      </ParamField>
    </ParamField>
    <ParamField body="isDefault" type="boolean">
      Whether this is the default variable collection. Defaults to false.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhooks" type="array">
  Array of webhook configurations for the call flow.
  
  <Expandable title="webhooks">
    <ParamField body="name" type="string" required>
      Name of the webhook.
    </ParamField>
    <ParamField body="url" type="string" required>
      Webhook URL endpoint.
    </ParamField>
    <ParamField body="method" type="string">
      HTTP method. Possible values: "GET", "POST", "PUT", "DELETE". Defaults to "POST".
    </ParamField>
    <ParamField body="headers" type="object">
      Key-value pairs for HTTP headers.
    </ParamField>
    <ParamField body="body" type="string">
      Request body content.
    </ParamField>
    <ParamField body="description" type="string">
      Description of the webhook purpose.
    </ParamField>
    <ParamField body="variablesforcallflow" type="array">
      Variables available for call flow.
      <ParamField body="name" type="string">
        Variable name.
      </ParamField>
      <ParamField body="description" type="string">
        Variable description.
      </ParamField>
    </ParamField>
    <ParamField body="responseVariables" type="array">
      Variables extracted from webhook responses.
      <ParamField body="name" type="string">
        Response variable name.
      </ParamField>
      <ParamField body="path" type="string">
        JSON path to extract the variable value.
      </ParamField>
      <ParamField body="description" type="string">
        Response variable description.
      </ParamField>
    </ParamField>
    <ParamField body="isTesting" type="boolean">
      Whether the webhook is in testing mode.
    </ParamField>
    <ParamField body="textToSpeak" type="string">
      Text to be spoken when webhook is triggered.
    </ParamField>
    <ParamField body="testResponse" type="string">
      Mock response for testing purposes.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="settings" type="object">
  Main configuration object for the call flow.

  <Expandable title="settings">
    <ParamField body="welcomeMessage" type="string">
      Welcome message type. Possible values: "user_initiated", "ai_dynamic", "ai_custom".
    </ParamField>
    <ParamField body="customWelcomeMessage" type="string">
      Custom welcome message text.
    </ParamField>
    <ParamField body="enableHumanLikeVoiceAndTone" type="boolean">
      Enable human-like voice and tone. Defaults to false.
    </ParamField>
    <ParamField body="welcomeMessageDelay" type="number">
      Delay in seconds before welcome message. Defaults to 0.
    </ParamField>
    <ParamField body="webhooks" type="object">
      Webhook URLs for different events.
      <ParamField body="agent" type="string">
        Agent webhook URL.
      </ParamField>
      <ParamField body="inbound" type="string">
        Inbound webhook URL.
      </ParamField>
    </ParamField>
    <ParamField body="customerLocation" type="string">
      Customer location for the call flow. Defaults to "new york".
    </ParamField>
    <ParamField body="transfers" type="array">
      Array of transfer configurations.
    </ParamField>
    <ParamField body="knowledgeBases" type="array">
      Array of knowledge base IDs to associate with this call flow.
    </ParamField>
    <ParamField body="utilizePriorCallsContext" type="boolean">
      Whether to utilize context from prior calls. Defaults to false.
    </ParamField>
    <ParamField body="callSettings" type="object">
      Call-specific settings.
      <ParamField body="trilletVoiceGuard" type="boolean">
        Enable Trillet voice guard. Defaults to true.
      </ParamField>
      <ParamField body="reminderMessages" type="array">
        Array of reminder message strings.
      </ParamField>
    </ParamField>
    <ParamField body="security" type="object">
      Security configuration settings.
      <ParamField body="securityOptOut" type="boolean">
        Whether to opt out of security features (affects HIPAA compliance).
      </ParamField>
      <ParamField body="publicAccess" type="boolean">
        Whether to allow public access to the call flow.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

### Response Fields

<ResponseField name="_id" type="string">
  The unique identifier for the newly created call flow.
</ResponseField>

<ResponseField name="workspaceId" type="string">
  The identifier of the workspace where the call flow has been created.
</ResponseField>

<ResponseField name="folderId" type="string">
  The identifier of the folder where the call flow is organized.
</ResponseField>

<ResponseField name="isGlobal" type="boolean">
  Whether this is a global call flow.
</ResponseField>

<ResponseField name="isPreConfigured" type="boolean">
  Whether this call flow is pre-configured.
</ResponseField>

<ResponseField name="preConfiguredWorkspaceId" type="string">
  Workspace ID for pre-configured flows.
</ResponseField>

<ResponseField name="name" type="string">
  The name given to the call flow.
</ResponseField>

<ResponseField name="direction" type="string">
  The direction configuration of the call flow; can be "inbound", "outbound", or "bidirectional".
</ResponseField>

<ResponseField name="description" type="string">
  A description of what the call flow is designed to handle.
</ResponseField>

<ResponseField name="agent" type="string">
  The identifier of the agent associated with this call flow.
</ResponseField>

<ResponseField name="promptType" default="simple" type="string">
  Only "simple" prompt types allowed now.
</ResponseField>

<ResponseField name="welcomeMessage" type="string">
  Welcome message type configuration.
</ResponseField>

<ResponseField name="customWelcomeMessage" type="string">
  Custom welcome message text if configured.
</ResponseField>

<ResponseField name="flowData" type="object">
  The configuration of nodes and edges that define the call routing logic within the flow.
  <ResponseField name="nodes" type="array">
    Detailed configuration of the nodes within the call flow.
  </ResponseField>
  <ResponseField name="edges" type="array">
    Configurations of the edges connecting nodes within the call flow.
  </ResponseField>
</ResponseField>

<ResponseField name="prompt" type="string">
  The initial or system prompt used in the call flow.
</ResponseField>

<ResponseField name="currentPromptId" type="string">
  ID of the current active prompt version.
</ResponseField>

<ResponseField name="promptVersions" type="array">
  Array of prompt versions with their metadata.
  <ResponseField name="_id" type="string">
    Unique identifier for the prompt version.
  </ResponseField>
  <ResponseField name="name" type="string">
    Name of the prompt version.
  </ResponseField>
  <ResponseField name="prompt" type="string">
    Prompt content for this version.
  </ResponseField>
  <ResponseField name="metadata" type="object">
    Additional metadata including notes.
  </ResponseField>
</ResponseField>

<ResponseField name="gemini_prompt" type="string">
  Sanitized version of the prompt for Gemini processing.
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Indicates whether the call flow is currently active or inactive.
</ResponseField>

<ResponseField name="agentWebhookUrl" type="string">
  Webhook URL for agent-related events.
</ResponseField>

<ResponseField name="inboundWebhookUrl" type="string">
  Webhook URL for inbound call events.
</ResponseField>

<ResponseField name="dynamicVariableCollections" type="array">
  Array of dynamic variable collections configured for the call flow.
</ResponseField>

<ResponseField name="locations" type="array">
  Array of location objects for visual flow positioning.
</ResponseField>

<ResponseField name="webhooks" type="array">
  Array of configured webhooks with their complete configuration.
</ResponseField>

<ResponseField name="settings" type="object">
  Configuration settings for various aspects of the call flow, including welcome messages, webhooks, knowledge bases, call settings, and security.
  <ResponseField name="security" type="object">
    Security settings with processed values.
    <ResponseField name="hipaaCompliance" type="boolean">
      HIPAA compliance status (processed from securityOptOut).
    </ResponseField>
    <ResponseField name="publicAccess" type="boolean">
      Public access configuration.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the call flow was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the call flow was last updated.
</ResponseField>


<ResponseExample>
```json
{
  "_id": "676b8e123456789012345678",
  "workspaceId": "6764d172953253138a3a70f4",
  "folderId": null,
  "isGlobal": false,
  "isPreConfigured": false,
  "preConfiguredWorkspaceId": null,
  "name": "Customer Support Flow",
  "direction": "inbound",
  "description": "Handles inbound support calls",
  "agent": "676b8e123456789012345679",
  "promptType": "simple",
  "welcomeMessage": "user_initiated",
  "customWelcomeMessage": "",
  "flowData": {
    "nodes": [
      {
        "id": "node1",
        "type": "start",
        "data": {
          "prompt": "Welcome to our support line. How can I help you?"
        }
      }
    ],
    "edges": []
  },
  "prompt": "Keep the conversation short and friendly.",
  "currentPromptId": "676b8e123456789012345680",
  "promptVersions": [
    {
      "_id": "676b8e123456789012345680",
      "name": "Prompt Version - 1/15/2025, 3:00:00 PM",
      "prompt": "Keep the conversation short and friendly.",
      "metadata": {
        "notes": ""
      },
      "createdAt": "2025-01-15T15:00:00.000Z",
      "updatedAt": "2025-01-15T15:00:00.000Z"
    }
  ],
  "gemini_prompt": "Keep the conversation short and friendly.",
  "startNodeId": null,
  "isActive": true,
  "agentWebhookUrl": "",
  "inboundWebhookUrl": "",
  "dynamicVariableCollections": [],
  "locations": [],
  "webhooks": [],
  "settings": {
    "welcomeMessage": "user_initiated",
    "customWelcomeMessage": "",
    "enableHumanLikeVoiceAndTone": false,
    "welcomeMessageDelay": 0,
    "webhooks": {
      "agent": "",
      "inbound": ""
    },
    "customerLocation": "new york",
    "transfers": [],
    "knowledgeBases": [],
    "utilizePriorCallsContext": false,
    "callSettings": {
      "trilletVoiceGuard": true,
      "reminderMessages": []
    },
    "security": {
      "hipaaCompliance": false,
      "publicAccess": false
    }
  },
  "createdAt": "2025-01-15T15:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z"
}
```
</ResponseExample>