Create Call Flow
Create a new call flow with full settings.
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-idstringrequiredWorkspace identifier for the API.
Request Body
namestringrequiredA friendly name for this call flow (e.g., "Customer Support Flow").
directionstringrequiredDirection of the flow: outbound, or bidirectional (answers inbound calls and can place outbound ones). inbound is also accepted and saved as bidirectional. Any other value returns 422 and the flow is not created.
descriptionstringDescription of the call flow (e.g. "Handles inbound support calls").
agentstringID 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:
400withcode: "AGENT_ID_INVALID":agentis not a 24 character id string. Pass the_iditself, not the whole agent object.400withcode: "AGENT_NOT_FOUND": no agent with that id exists in this workspace.409withcode: "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: simpleHow the flow is authored. Send simple: one prompt drives the whole call.
folderIdstringID of the folder to organize this call flow.
welcomeMessagestringA 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:
aiFirstorai_dynamic: the AI writes the greeting. Saved asaiFirst(AI Generated in the editor).customMessageorai_custom: the agent opens with the text incustomWelcomeMessage. Saved ascustomMessage(Custom Message in the editor).userFirstoruser_initiated: the agent waits for the caller to speak first. Saved asuserFirst(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.
customWelcomeMessagestringThe 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.
flowDataobjectFlow-based configuration using a node/edge approach for complex call routing.
promptstringA system or initial prompt for the flow. This will be used to create the first prompt version.
isActivebooleanWhether the flow is currently active. Defaults to true.
agentWebhookUrlstringWebhook URL for agent-related events.
inboundWebhookUrlstringWebhook URL for inbound call events.
dynamicVariableCollectionsarrayArray of dynamic variable collections for the call flow.
webhooksarrayArray of webhook configurations for the call flow.
settingsobjectMain configuration object for the call flow. Anything you leave out starts with the same default as a call flow created in the dashboard.
Errors
When a request is refused, the flow is not created.
| Status | Body | When |
|---|---|---|
400 | {"error": "Workspace ID is required."} | No x-workspace-id |
400 | {"message": "Missing required field(s): ..."} | name, direction or promptType is missing |
400 | {"message", "code", ...} | Greeting input is not valid (see welcomeMessageConfig), or an agent error listed under agent |
403 | {"message": "workspaceId in the request body does not match x-workspace-id."} | A body workspaceId names a workspace other than the header one (or one of its client workspaces you hold a role in) |
409 | {"message", "code": "AGENT_IN_USE"} | Another call flow already uses that agent |
422 | {"message": "..."} | The flow failed validation, for example an unknown direction or webhook headers sent as an object |
500 | {"message": "Error creating flow"} | Anything else |
Response Fields
201 Created with the new call flow.
_idstringThe unique identifier for the newly created call flow.
workspaceIdstringThe identifier of the workspace where the call flow has been created.
folderIdstringThe identifier of the folder where the call flow is organized.
namestringThe name given to the call flow.
directionstringThe direction configuration of the call flow; either "outbound" or "bidirectional".
descriptionstringA description of what the call flow is designed to handle.
agentstringThe 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: simpleHow the flow is authored, normally simple.
flowDataobjectThe configuration of nodes and edges that define the call routing logic within the flow.
nodesarrayDetailed configuration of the nodes within the call flow.
edgesarrayConfigurations of the edges connecting nodes within the call flow.
promptstringThe initial or system prompt used in the call flow.
currentPromptIdstringID of the current active prompt version.
promptVersionsarrayArray of prompt versions with their metadata.
_idstringUnique identifier for the prompt version.
namestringName of the prompt version.
promptstringPrompt content for this version.
metadataobjectAdditional metadata including notes.
isActivebooleanIndicates whether the call flow is currently active or inactive.
agentWebhookUrlstringWebhook URL for agent-related events.
inboundWebhookUrlstringWebhook URL for inbound call events.
dynamicVariableCollectionsarrayArray of dynamic variable collections configured for the call flow.
locationsarrayArray of location objects for visual flow positioning.
webhooksarrayArray of configured webhooks with their complete configuration.
settingsobjectThe flow's full settings, with the dashboard defaults filled in for anything not sent (about 40 keys; the example shows only some of them).
welcomeMessageConfigobjectThe 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.
InboundobjectThe greeting for calls received on the flow's phone number.
OutboundobjectThe greeting for calls the flow places and for web calls made with the Web SDK.
securityobjectSecurity settings with processed values.
hipaaCompliancebooleanHIPAA compliance status, set from securityOptOut on create.
publicAccessbooleanPublic access configuration.
createdAtstringTimestamp when the call flow was created.
updatedAtstringTimestamp when the call flow was last updated.
{
"name": "Acme Plumbing - Call Flow",
"direction": "bidirectional",
"promptType": "simple",
"welcomeMessage": "customMessage",
"customWelcomeMessage": "Thanks for calling Acme Plumbing, how can I help you?"
}{
"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."
}
}
}
}{
"_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": "Thanks for calling Acme Plumbing, how can I help you?",
"selected": "customMessage",
"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"
}{
"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\"."
]
}Last updated on