Trillet AI logo

Update Call Flow

Update an existing call flow.

PUThttps://api.trillet.ai/v1/api/call-flows/{id}

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Path Parameters

idstringrequired

The unique ID of the call flow to update.

Request Body

namestring

New name for the flow.

descriptionstring

Updated description for the call flow (e.g., "Updated description for inbound calls").

directionstring

The direction of the call flow: outbound, or bidirectional (answers inbound calls and can place outbound ones). Any value other than outbound is saved as bidirectional.

isActiveboolean

Whether the call flow is currently active.

promptTypestring

How the flow is authored. Use simple: one prompt drives the whole call.

promptstring

The primary prompt for user interaction (used when promptType is 'simple').

welcomeMessagestring

A shortcut that gives both directions, Inbound and Outbound, the same greeting type. For updates, prefer settings.welcomeMessageConfig: it can change one direction at a time and covers every greeting option. 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 changed.

The shortcut is saved into settings.welcomeMessageConfig, so welcomeMessage and customWelcomeMessage are not stored. 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.

If the shortcut fields you send at the top level, or inside settings, all have exactly the values the flow already has in that place, they are ignored. Some older flows still return these fields, so sending a Get Call Flow response back unchanged does not change the greeting, as long as the flow has no unpublished changes from the call flow editor (see the Note below). To change it, send a different value or use settings.welcomeMessageConfig.

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. If you send welcomeMessage: "customMessage" without this field, each direction keeps the text it already has.

When a direction's greeting type is customMessage, its text must not be blank. Otherwise the request returns 400 with code: "GREETING_TEXT_REQUIRED", and the flow is not changed.

dynamicVariableCollectionsarray

Collections of dynamic variables for the call flow.

settingsobject

Configuration settings for the call flow.

webhooksarray

The flow's in-call webhooks (In-Call APIs). This array replaces the flow's whole webhook list: any webhook you leave out is deleted, and webhooks: [] removes them all. To add one webhook, get the flow with Get Call Flow, append the new entry to its webhooks, and send the full array back. Keep each existing entry's _id so it stays the same webhook.

unsetarray

Settings to remove, as dot paths that start with settings., for example ["settings.callSetting.reminderMessages"]. A merge cannot remove a key, so use this instead. A path in another form returns 400.

expectedUpdatedAtstring

Optional concurrency check. Send the updatedAt you last read. If the flow has changed since then, the update is refused with 409 and nothing is saved.

forceUpdateboolean

With expectedUpdatedAt, true saves even if the flow has changed since.

settings is merged into the stored settings: objects merge key by key, and a key you leave out keeps its value. Arrays are replaced, not merged: this applies to the top-level webhooks and dynamicVariableCollections, and to arrays inside settings such as transfers, knowledgeBases, knowledgeBaseFiles and callSetting.reminderMessages. null values are ignored.

On a node flow (promptType: "nodes"), the conversation is defined by the node graph, not by prompt. A prompt sent here is saved and returns 200, but calls on a node flow do not use it.

If the flow has unpublished changes from the call flow editor, Get Call Flow returns the draft merged over the live flow. This endpoint writes to the live flow.

A greeting set here is used from the flow's next call; nothing has to be published. If the flow has unpublished changes from the call flow editor, the editor and Get Call Flow keep showing that draft's greeting, and publishing the draft replaces the greeting you set here. Sending a Get Call Flow response back while such changes exist replaces the live greeting with the draft's, including one you set through the API.

Dashboard test calls also use the draft's greeting until the draft is published or discarded. Demo links marked Draft always use their draft's greeting. Calls received on the flow's phone number, calls the flow places and other Web SDK calls use the greeting set here.

Errors

When a request is refused, nothing is changed.

StatusBodyWhen
400{"error": "Workspace ID is required."}No x-workspace-id
400{"message", "errors"}A changed settings.callSetting value is outside the allowed values above, or the silence sequence is longer than maxCallDuration
400{"message", "code", "field", "errors"}Greeting input is not valid (see welcomeMessageConfig)
400{"message": "..."}Other settings rules: invalid transfers, custom tools, booking link, Google Calendar settings or speech-recognition keywords, or a knowledge base from another workspace
409{"code": "FLOW_ARCHIVED", "message": "This flow is archived and is read-only. Restore it to make changes."}The flow is archived. Restore it in the dashboard first
409{"message": "Flow has been updated by another user"}You sent expectedUpdatedAt and the flow changed since then
500{"message": "Error updating flow"}Unexpected server error

Response Fields

The updated call flow, with one extra field, numberSyncFailures.

_idstring

The unique identifier of the call flow.

workspaceIdstring

The identifier of the workspace the call flow belongs to.

folderIdstring

The folder the call flow is in, or null.

namestring

The name given to the call flow.

directionstring

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.

promptTypestring

simple, nodes (a node-based flow) or flow (legacy).

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.

startNodeIdstring

ID of the starting node for flow-based configurations.

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

The flow's full settings, with the dashboard defaults filled in for anything not sent (about 40 keys; the example shows only some of them).

welcomeMessageConfigobject

The greeting for each direction, with selected, customMessage, aiGreetingPrompt, userFirstFallbackDelaySeconds and userFirstFallbackMessage. Some flows can be missing a direction, a field, or the whole object; a missing selected means aiFirst.

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.

publicAccessboolean

Public access configuration.

createdAtstring

Timestamp when the call flow was created.

updatedAtstring

Timestamp when the call flow was last updated.

numberSyncFailuresarray

Phone numbers bound to the flow whose telephony settings could not be updated after a direction change, as { phoneNumberId, phoneNumber }. Empty when everything synced.

Post-call analysis

Set the fields to extract from every call after it ends with settings.postCallAnalysis (see Request Body). Each field is saved under its name in analyzedData on Get Call. The array you send replaces the flow's whole list, so send every field you want to keep. For a full request, open the Set post-call analysis fields curl example in the request panel.

Change only the inbound greeting
{
  "settings": {
    "welcomeMessageConfig": {
      "Inbound": {
        "selected": "customMessage",
        "customMessage": "Thanks for calling Acme Plumbing, how can I help you?"
      }
    }
  }
}
Wait for the caller on inbound calls
{
  "settings": {
    "welcomeMessageConfig": {
      "Inbound": {
        "selected": "userFirst",
        "userFirstFallbackDelaySeconds": 8,
        "userFirstFallbackMessage": "Hi, you've reached Acme Plumbing. How can I help you today?"
      }
    }
  }
}
Shortcut
{
  "welcomeMessage": "customMessage",
  "customWelcomeMessage": "Thanks for calling Acme Plumbing, how can I help you?"
}
Set post-call analysis fields
curl -X PUT "https://api.trillet.ai/v1/api/call-flows/{id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "postCallAnalysis": [
        {
          "name": "appointment_booked",
          "description": "true only if the caller confirmed a date and time for the appointment",
          "type": "boolean"
        },
        {
          "name": "service_type",
          "description": "The service the caller asked about",
          "type": "selector",
          "options": ["plumbing", "hvac", "electrical", "other"]
        },
        {
          "name": "callback_number",
          "description": "The number the caller asked to be called back on, if different from the caller ID",
          "type": "text"
        }
      ]
    }
  }'
{
  "_id": "c2c2c2c2c2c2c2c2c2c2c2c2",
  "workspaceId": "c1c1c1c1c1c1c1c1c1c1c1c1",
  "folderId": null,
  "name": "Customer Support Flow",
  "direction": "bidirectional",
  "description": "Handles inbound support calls",
  "agent": "c3c3c3c3c3c3c3c3c3c3c3c3",
  "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": "c4c4c4c4c4c4c4c4c4c4c4c4",
  "promptVersions": [
    {
      "_id": "c4c4c4c4c4c4c4c4c4c4c4c4",
      "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"
    }
  ],
  "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": "",
        "selected": "aiFirst",
        "userFirstFallbackDelaySeconds": 10,
        "userFirstFallbackMessage": ""
      }
    },
    "enableHumanLikeVoiceAndTone": false,
    "welcomeMessageDelay": 0,
    "webhooks": {
      "agent": "",
      "inbound": ""
    },
    "customerLocation": "",
    "transfers": [],
    "knowledgeBases": [],
    "utilizePriorCallsContext": false,
    "callSetting": {
      "endCallOnSilence": 10,
      "silenceReminderRetries": 1,
      "endCallAfterReminder": 10,
      "maxCallDuration": 1800,
      "postCallAnalysisModel": "gemini-2.5-flash",
      "reminderMessages": []
    },
    "security": {
      "hipaaCompliance": false,
      "publicAccess": false
    }
  },
  "createdAt": "2025-01-15T15:00:00.000Z",
  "updatedAt": "2025-01-15T15:00:00.000Z",
  "numberSyncFailures": []
}

Last updated on