Create Call Flow

POSThttps://api.trillet.ai/v1/api/call-flows

Every call flow runs on its own agent. To choose the voice and model yourself, create the agent with Create Call Agent first and pass its _id as agent. If you skip that, a default agent is created for you. There is no separate agents page in the dashboard. You edit the agent inside its call flow, and you pick it on the Phone Numbers page.

Any settings you leave out start with the same defaults as a call flow created in the dashboard, so the flow can take calls as soon as it has a phone number.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

namestringrequired

A friendly name for this call flow (e.g., "Customer Support Flow").

directionstringrequired

Direction of the flow. Possible values: "outbound", "bidirectional". Any other value, including "inbound", is saved as "bidirectional".

descriptionstring

Description of the call flow (e.g. "Handles inbound support calls").

agentstring

ID of the agent this flow uses. Create the agent first with Create Call Agent and pass the _id from that response here, as a string. The agent holds the name, voice and model the flow speaks with, and it is what you pick when you give the flow a phone number. If the agent has a pending phone number, it is activated.

The agent must be in the same workspace as the flow, and no other call flow can already use it. Otherwise the flow is not created:

400 with code: "AGENT_ID_INVALID": agent is not a 24 character id string. Pass the _id itself, not the whole agent object.
400 with code: "AGENT_NOT_FOUND": no agent with that id exists in this workspace.
409 with code: "AGENT_IN_USE": another call flow already uses that agent. Create a new agent for this flow.

If you leave this out, or send null or an empty string, a default agent is created for you and linked to the flow. It is named after the flow and uses the default model, the Astra voice in English and Speechmatics speech recognition. Its ID comes back in the agent field of the response, and you can change it later with Update Call Agent or from the call flow editor.

promptTypestringrequireddefault: simple

Only "simple" type of prompt configuration is allowed now.

folderIdstring

ID of the folder to organize this call flow.

isGlobalboolean

Whether this is a global call flow. Only specific workspaces can create global flows.

isPreConfiguredboolean

Whether this call flow is pre-configured. Defaults to false.

preConfiguredWorkspaceIdstring

Workspace ID for pre-configured flows.

welcomeMessagestring

A shortcut that gives both directions, Inbound and Outbound, the same greeting type. To set each direction separately or to use the other greeting options, send settings.welcomeMessageConfig instead. The value is case-sensitive:

aiFirst or ai_dynamic: the AI writes the greeting. Saved as aiFirst (AI Generated in the editor).
customMessage or ai_custom: the agent opens with the text in customWelcomeMessage. Saved as customMessage (Custom Message in the editor).
userFirst or user_initiated: the agent waits for the caller to speak first. Saved as userFirst (Wait for Caller in the editor).

Any other value returns 400 with code: "GREETING_TYPE_INVALID", and the flow is not created.

If you send no greeting, both directions use aiFirst. Earlier versions of this page said the default was user_initiated. It is aiFirst, and user_initiated makes the agent wait for the caller to speak first.

The shortcut is saved into settings.welcomeMessageConfig, so welcomeMessage and customWelcomeMessage are not stored and do not come back in the response. You can also send both fields inside settings. If you send a field in both places, the top-level value wins. If the request also includes settings.welcomeMessageConfig, the shortcut is ignored.

customWelcomeMessagestring

The text the agent says for a customMessage greeting, saved as customMessage in both directions. If you send non-blank text without welcomeMessage, the greeting type is set to customMessage.

When the greeting type is customMessage, this text must not be blank. Otherwise the request returns 400 with code: "GREETING_TEXT_REQUIRED", and the flow is not created.

flowDataobject

Flow-based configuration using a node/edge approach for complex call routing.

promptstring

A system or initial prompt for the flow. This will be used to create the first prompt version.

isActiveboolean

Whether the flow is currently active. Defaults to true.

agentWebhookUrlstring

Webhook URL for agent-related events.

inboundWebhookUrlstring

Webhook URL for inbound call events.

dynamicVariableCollectionsarray

Array of dynamic variable collections for the call flow.

webhooksarray

Array of webhook configurations for the call flow.

settingsobject

Main configuration object for the call flow. Anything you leave out starts with the same default as a call flow created in the dashboard.

Response Fields

_idstring

The unique identifier for the newly created call flow.

workspaceIdstring

The identifier of the workspace where the call flow has been created.

folderIdstring

The identifier of the folder where the call flow is organized.

isGlobalboolean

Whether this is a global call flow.

isPreConfiguredboolean

Whether this call flow is pre-configured.

preConfiguredWorkspaceIdstring

Workspace ID for pre-configured flows.

namestring

The name given to the call flow.

directionstring

The direction configuration of the call flow; either "outbound" or "bidirectional".

descriptionstring

A description of what the call flow is designed to handle.

agentstring

The identifier of the agent associated with this call flow. This is the agent you passed in, or the default agent created for the flow when you did not pass one.

promptTypestringdefault: simple

Only "simple" prompt types allowed now.

flowDataobject

The configuration of nodes and edges that define the call routing logic within the flow.

nodesarray

Detailed configuration of the nodes within the call flow.

edgesarray

Configurations of the edges connecting nodes within the call flow.

promptstring

The initial or system prompt used in the call flow.

currentPromptIdstring

ID of the current active prompt version.

promptVersionsarray

Array of prompt versions with their metadata.

_idstring

Unique identifier for the prompt version.

namestring

Name of the prompt version.

promptstring

Prompt content for this version.

metadataobject

Additional metadata including notes.

gemini_promptstring

Sanitized version of the prompt for Gemini processing.

isActiveboolean

Indicates whether the call flow is currently active or inactive.

agentWebhookUrlstring

Webhook URL for agent-related events.

inboundWebhookUrlstring

Webhook URL for inbound call events.

dynamicVariableCollectionsarray

Array of dynamic variable collections configured for the call flow.

locationsarray

Array of location objects for visual flow positioning.

webhooksarray

Array of configured webhooks with their complete configuration.

settingsobject

Configuration settings for various aspects of the call flow, including welcome messages, webhooks, knowledge bases, call settings, and security.

welcomeMessageConfigobject

The greeting for each direction. Both directions have all five fields, selected, customMessage, aiGreetingPrompt, userFirstFallbackDelaySeconds and userFirstFallbackMessage, with the default for any field you did not send.

Inboundobject

The greeting for calls received on the flow's phone number.

Outboundobject

The greeting for calls the flow places and for web calls made with the Web SDK.

securityobject

Security settings with processed values.

hipaaComplianceboolean

HIPAA compliance status (processed from securityOptOut).

publicAccessboolean

Public access configuration.

createdAtstring

Timestamp when the call flow was created.

updatedAtstring

Timestamp when the call flow was last updated.

Same greeting for every call (shortcut)

{
  "name": "Acme Plumbing - Call Flow",
  "direction": "bidirectional",
  "promptType": "simple",
  "welcomeMessage": "customMessage",
  "customWelcomeMessage": "Thanks for calling Acme Plumbing, how can I help you?"
}

Different greeting per direction

{
  "name": "Acme Plumbing - Call Flow",
  "direction": "bidirectional",
  "promptType": "simple",
  "settings": {
    "welcomeMessageConfig": {
      "Inbound": {
        "selected": "customMessage",
        "customMessage": "Thanks for calling Acme Plumbing, how can I help you?"
      },
      "Outbound": {
        "selected": "aiFirst",
        "aiGreetingPrompt": "Introduce yourself as the booking assistant for Acme Plumbing and say you are calling to confirm the customer's appointment."
      }
    }
  }
}

201 Created

{
  "_id": "676b8e123456789012345678",
  "workspaceId": "6764d172953253138a3a70f4",
  "folderId": null,
  "isGlobal": false,
  "isPreConfigured": false,
  "preConfiguredWorkspaceId": null,
  "name": "Customer Support Flow",
  "direction": "bidirectional",
  "description": "Handles inbound support calls",
  "agent": "676b8e123456789012345679",
  "promptType": "simple",
  "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": {
    "welcomeMessageConfig": {
      "Inbound": {
        "aiGreetingPrompt": "",
        "customMessage": "Thanks for calling Acme Plumbing, how can I help you?",
        "selected": "customMessage",
        "userFirstFallbackDelaySeconds": 10,
        "userFirstFallbackMessage": ""
      },
      "Outbound": {
        "aiGreetingPrompt": "",
        "customMessage": "Thanks for calling Acme Plumbing, how can I help you?",
        "selected": "customMessage",
        "userFirstFallbackDelaySeconds": 10,
        "userFirstFallbackMessage": ""
      }
    },
    "enableHumanLikeVoiceAndTone": false,
    "welcomeMessageDelay": 0,
    "webhooks": {
      "agent": "",
      "inbound": ""
    },
    "customerLocation": "new york",
    "transfers": [],
    "knowledgeBases": [],
    "utilizePriorCallsContext": false,
    "callSetting": {
      "trilletVoiceGuard": true,
      "reminderMessages": []
    },
    "security": {
      "hipaaCompliance": false,
      "publicAccess": false
    }
  },
  "createdAt": "2025-01-15T15:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z"
}

400 Greeting error

{
  "message": "welcomeMessage must be \"aiFirst\", \"customMessage\" or \"userFirst\" (the older names \"ai_dynamic\", \"ai_custom\" and \"user_initiated\" also work). Got \"custom\".",
  "code": "GREETING_TYPE_INVALID",
  "field": "welcomeMessage",
  "errors": [
    "welcomeMessage must be \"aiFirst\", \"customMessage\" or \"userFirst\" (the older names \"ai_dynamic\", \"ai_custom\" and \"user_initiated\" also work). Got \"custom\"."
  ]
}