Skip to content
vocapable.Docs

One line's call flow: draft, live, history

GET
/v1/workspace/call-flows/{phone_number_id}
curl --request GET \
  --url https://api.vocapable.com/v1/workspace/call-flows/example \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
phone_number_id
required
Phone Number Id
string

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
SharedPhoneCallFlow
object
phone_number_id
required
Phone Number Id
string
phone_e164
required
Phone E164
string
revision
required
Revision
integer
draft
required
SharedPhoneFlow
object
name
Name
string
default: Business phone >= 1 characters <= 120 characters
greeting
Greeting
string
default: Thank you for calling. We will be with you shortly. >= 1 characters <= 1000 characters
waiting_message
Waiting Message
string
default: Your call is important to us. Please stay on the line. >= 1 characters <= 1000 characters
timeout_message
Timeout Message
string
default: We are unable to answer right now. Please call again later. >= 1 characters <= 1000 characters
ai_offer_message
Ai Offer Message
string
default: An AI representative is available. Press 3 to speak with it, or stay on the line for our team. >= 1 characters <= 1000 characters
answer_order
Answer Order
string
default: human_only
Allowed values: ai_first team_first human_only
ai_offer_mode
Ai Offer Mode
string
default: ask
Allowed values: ask automatic off
ai_agent_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
member_user_ids
Member User Ids
Array<string>
<= 50 items
strategy
Strategy
string
default: ring_together
Allowed values: ring_together sequential round_robin longest_idle owner_first company_owner_first
queue_ids
Queue Ids
Array<string>
<= 10 items
ring_seconds
Ring Seconds
integer
default: 20 >= 10 <= 60
max_wait_seconds
Max Wait Seconds
integer
default: 300 >= 15 <= 3600
max_callers
Max Callers
integer
default: 25 >= 1 <= 250
announcement_seconds
Announcement Seconds
integer
default: 45 >= 15 <= 120
announce_position
Announce Position
boolean
default: true
callback_enabled
Callback Enabled
boolean
default: true
voicemail_enabled
Voicemail Enabled
boolean
default: true
callback_attempts
Callback Attempts
integer
default: 2 >= 1 <= 5
music
Music
string
default: calm
Allowed values: calm bright silence
hold_music_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
voicemail_greeting
Voicemail Greeting
string
default: Please leave your name, your number and a short message after the tone. >= 1 characters <= 1000 characters
closed_message
Closed Message
string
default: Thank you for calling. We are closed right now. >= 1 characters <= 1000 characters
closed_message_before_forward
Closed Message Before Forward
boolean
default: true
overflow_chain
Overflow Chain
Array<object>
<= 3 items
SharedPhoneFallbackStep

One overflow/after-hours step. Destinations are references, never free carrier input.

forward names a number on the company’s verified-number allow-list (checked when the flow is published; the published answering policy dials only that stored number); line names another of the company’s business lines, whose own published flow then answers the caller (the forward presents the caller’s own number).

object
kind
required
Kind
string
Allowed values: voicemail ai_receptionist forward line
forward_to_e164
Any of:
string
/^\+[1-9]\d{7,14}$/
phone_number_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
after_hours_chain
After Hours Chain
Array<object>
<= 3 items
SharedPhoneFallbackStep

One overflow/after-hours step. Destinations are references, never free carrier input.

forward names a number on the company’s verified-number allow-list (checked when the flow is published; the published answering policy dials only that stored number); line names another of the company’s business lines, whose own published flow then answers the caller (the forward presents the caller’s own number).

object
kind
required
Kind
string
Allowed values: voicemail ai_receptionist forward line
forward_to_e164
Any of:
string
/^\+[1-9]\d{7,14}$/
phone_number_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
receptionist_voice_prompts
Receptionist Voice Prompts
boolean
default: true
schedule
required
AnsweringPolicyUpsertRequest

The whole answering document for one number, written in a single call.

Whole-document rather than patch: the steps form a tree whose branches reference each other by position, and a partial write is the shape in which a menu keeps pointing at a branch the same request deleted.

business_hours is the tenant’s own calendar in the tenant’s own zone, and it shares only the vocabulary of campaign_schedules.calling_windows, never its meaning: the compliance layer’s quiet hours are keyed to the callee’s jurisdiction and are untouched here. An empty map means the number is answered by open_steps at every hour; naming any day at all makes every unnamed day closed, which is the same load-bearing empty-versus-absent distinction CallingSchedule.windows_for carries.

object
timezone
required
Timezone
string
>= 1 characters <= 64 characters
business_hours
Business Hours
object
key
additional properties
Array<object>
<= 6 items
CallingWindow

One local-time window on one weekday.

object
start
required
Start
string
/^([01]\d|2[0-3]):[0-5]\d$/
end
required
End
string
/^([01]\d|2[0-3]):[0-5]\d$/
holiday_dates
Holiday Dates
Array<string>
<= 60 items
open_steps
required
Open Steps
Array
>= 1 items <= 60 items
One of: discriminator: type
MenuStep

Read options, then follow the branch the caller pressed.

timeout_branch is required rather than optional, and it is also where the invalid budget lands once it is spent: a menu whose silent or fumbling caller has nowhere to go re-prompts forever, which is the single most common way a keypress tree becomes a trap.

object
type
Type
string
default: menu
Allowed value: menu
prompt
required
Prompt
string
>= 1 characters <= 1000 characters
branches
required
Branches
object
>= 1 properties <= 12 properties
timeout_seconds
Timeout Seconds
integer
default: 5 >= 1 <= 30
max_invalid_attempts
Max Invalid Attempts
integer
default: 2 >= 1 <= 5
timeout_branch
required
Timeout Branch
Array
>= 1 items <= 12 items
One of: discriminator: type
object recursive
closed_steps
Closed Steps
Array
<= 60 items
One of: discriminator: type
MenuStep

Read options, then follow the branch the caller pressed.

timeout_branch is required rather than optional, and it is also where the invalid budget lands once it is spent: a menu whose silent or fumbling caller has nowhere to go re-prompts forever, which is the single most common way a keypress tree becomes a trap.

object
type
Type
string
default: menu
Allowed value: menu
prompt
required
Prompt
string
>= 1 characters <= 1000 characters
branches
required
Branches
object
>= 1 properties <= 12 properties
timeout_seconds
Timeout Seconds
integer
default: 5 >= 1 <= 30
max_invalid_attempts
Max Invalid Attempts
integer
default: 2 >= 1 <= 5
timeout_branch
required
Timeout Branch
Array
>= 1 items <= 12 items
One of: discriminator: type
object recursive
draft_source
required
Draft Source
string
Allowed values: saved imported default
published_revision
required
Any of:
integer
published
required
Any of:
SharedPhoneFlow
object
name
Name
string
default: Business phone >= 1 characters <= 120 characters
greeting
Greeting
string
default: Thank you for calling. We will be with you shortly. >= 1 characters <= 1000 characters
waiting_message
Waiting Message
string
default: Your call is important to us. Please stay on the line. >= 1 characters <= 1000 characters
timeout_message
Timeout Message
string
default: We are unable to answer right now. Please call again later. >= 1 characters <= 1000 characters
ai_offer_message
Ai Offer Message
string
default: An AI representative is available. Press 3 to speak with it, or stay on the line for our team. >= 1 characters <= 1000 characters
answer_order
Answer Order
string
default: human_only
Allowed values: ai_first team_first human_only
ai_offer_mode
Ai Offer Mode
string
default: ask
Allowed values: ask automatic off
ai_agent_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
member_user_ids
Member User Ids
Array<string>
<= 50 items
strategy
Strategy
string
default: ring_together
Allowed values: ring_together sequential round_robin longest_idle owner_first company_owner_first
queue_ids
Queue Ids
Array<string>
<= 10 items
ring_seconds
Ring Seconds
integer
default: 20 >= 10 <= 60
max_wait_seconds
Max Wait Seconds
integer
default: 300 >= 15 <= 3600
max_callers
Max Callers
integer
default: 25 >= 1 <= 250
announcement_seconds
Announcement Seconds
integer
default: 45 >= 15 <= 120
announce_position
Announce Position
boolean
default: true
callback_enabled
Callback Enabled
boolean
default: true
voicemail_enabled
Voicemail Enabled
boolean
default: true
callback_attempts
Callback Attempts
integer
default: 2 >= 1 <= 5
music
Music
string
default: calm
Allowed values: calm bright silence
hold_music_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
voicemail_greeting
Voicemail Greeting
string
default: Please leave your name, your number and a short message after the tone. >= 1 characters <= 1000 characters
closed_message
Closed Message
string
default: Thank you for calling. We are closed right now. >= 1 characters <= 1000 characters
closed_message_before_forward
Closed Message Before Forward
boolean
default: true
overflow_chain
Overflow Chain
Array<object>
<= 3 items
SharedPhoneFallbackStep

One overflow/after-hours step. Destinations are references, never free carrier input.

forward names a number on the company’s verified-number allow-list (checked when the flow is published; the published answering policy dials only that stored number); line names another of the company’s business lines, whose own published flow then answers the caller (the forward presents the caller’s own number).

object
kind
required
Kind
string
Allowed values: voicemail ai_receptionist forward line
forward_to_e164
Any of:
string
/^\+[1-9]\d{7,14}$/
phone_number_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
after_hours_chain
After Hours Chain
Array<object>
<= 3 items
SharedPhoneFallbackStep

One overflow/after-hours step. Destinations are references, never free carrier input.

forward names a number on the company’s verified-number allow-list (checked when the flow is published; the published answering policy dials only that stored number); line names another of the company’s business lines, whose own published flow then answers the caller (the forward presents the caller’s own number).

object
kind
required
Kind
string
Allowed values: voicemail ai_receptionist forward line
forward_to_e164
Any of:
string
/^\+[1-9]\d{7,14}$/
phone_number_id
Any of:
string
>= 1 characters <= 64 characters /^[A-Za-z0-9_-]+$/
receptionist_voice_prompts
Receptionist Voice Prompts
boolean
default: true
schedule
required
AnsweringPolicyUpsertRequest

The whole answering document for one number, written in a single call.

Whole-document rather than patch: the steps form a tree whose branches reference each other by position, and a partial write is the shape in which a menu keeps pointing at a branch the same request deleted.

business_hours is the tenant’s own calendar in the tenant’s own zone, and it shares only the vocabulary of campaign_schedules.calling_windows, never its meaning: the compliance layer’s quiet hours are keyed to the callee’s jurisdiction and are untouched here. An empty map means the number is answered by open_steps at every hour; naming any day at all makes every unnamed day closed, which is the same load-bearing empty-versus-absent distinction CallingSchedule.windows_for carries.

object
timezone
required
Timezone
string
>= 1 characters <= 64 characters
business_hours
Business Hours
object
key
additional properties
Array<object>
<= 6 items
CallingWindow

One local-time window on one weekday.

object
start
required
Start
string
/^([01]\d|2[0-3]):[0-5]\d$/
end
required
End
string
/^([01]\d|2[0-3]):[0-5]\d$/
holiday_dates
Holiday Dates
Array<string>
<= 60 items
open_steps
required
Open Steps
Array
>= 1 items <= 60 items
One of: discriminator: type
MenuStep

Read options, then follow the branch the caller pressed.

timeout_branch is required rather than optional, and it is also where the invalid budget lands once it is spent: a menu whose silent or fumbling caller has nowhere to go re-prompts forever, which is the single most common way a keypress tree becomes a trap.

object
type
Type
string
default: menu
Allowed value: menu
prompt
required
Prompt
string
>= 1 characters <= 1000 characters
branches
required
Branches
object
>= 1 properties <= 12 properties
timeout_seconds
Timeout Seconds
integer
default: 5 >= 1 <= 30
max_invalid_attempts
Max Invalid Attempts
integer
default: 2 >= 1 <= 5
timeout_branch
required
Timeout Branch
Array
>= 1 items <= 12 items
One of: discriminator: type
object recursive
closed_steps
Closed Steps
Array
<= 60 items
One of: discriminator: type
MenuStep

Read options, then follow the branch the caller pressed.

timeout_branch is required rather than optional, and it is also where the invalid budget lands once it is spent: a menu whose silent or fumbling caller has nowhere to go re-prompts forever, which is the single most common way a keypress tree becomes a trap.

object
type
Type
string
default: menu
Allowed value: menu
prompt
required
Prompt
string
>= 1 characters <= 1000 characters
branches
required
Branches
object
>= 1 properties <= 12 properties
timeout_seconds
Timeout Seconds
integer
default: 5 >= 1 <= 30
max_invalid_attempts
Max Invalid Attempts
integer
default: 2 >= 1 <= 5
timeout_branch
required
Timeout Branch
Array
>= 1 items <= 12 items
One of: discriminator: type
object recursive
has_unpublished_changes
required
Has Unpublished Changes
boolean
paused
required
Paused
boolean
can_manage
required
Can Manage
boolean
problems
required
Problems
Array<object>
SharedPhoneCallFlowProblem

A reason the draft cannot be published, in words the editor can show beside a field.

object
code
required
Code
string
field
required
Field
string
detail
required
Detail
string
versions
required
Versions
Array<object>
SharedPhoneCallFlowVersion
object
revision
required
Revision
integer
published_at
required
Published At
string format: date-time
published_by
required
Any of:
string
published_by_name
required
Any of:
string
restored_from_revision
required
Any of:
integer
live
required
Live
boolean
members
required
Members
Array<object>
SharedPhoneCallFlowMember
object
user_id
required
User Id
string
name
required
Name
string
role
required
Role
string
phone_ready
required
Phone Ready
boolean
detail
required
Any of:
string
agents
required
Agents
Array<object>
SharedPhoneCallFlowAgent
object
id
required
Id
string
name
required
Name
string
published
required
Published
boolean
voice_id
required
Any of:
string
lines
required
Lines
Array<object>
SharedPhoneCallFlowLineChoice
object
phone_number_id
required
Phone Number Id
string
phone_e164
required
Phone E164
string
published
required
Published
boolean
forward_numbers
required
Forward Numbers
Array<object>
SharedPhoneCallFlowForwardChoice
object
phone_e164
required
Phone E164
string
label
required
Any of:
string
hold_music
required
Hold Music
Array<object>
SharedPhoneHoldMusicTrack
object
id
required
Id
string
name
required
Name
string
duration_ms
required
Duration Ms
integer
size_bytes
required
Size Bytes
integer
rights_attested_at
required
Rights Attested At
string format: date-time
rights_attested_by_name
required
Any of:
string
created_at
required
Created At
string format: date-time
prompts
required
Prompts
Array<object>
SharedPhoneCallFlowPrompt

Whether one spoken text plays in the receptionist voice or falls back to .

object
prompt
required
Prompt
string
Allowed values: greeting waiting timeout closed voicemail
revision
required
Revision
integer
voice_id
required
Any of:
string
synthesized
required
Synthesized
boolean
queue_admission_live
required
Queue Admission Live
boolean
answering_policy_version
required
Any of:
integer
queues
Queues
Array<object>
SharedPhoneCallFlowQueueChoice

A contact-center queue this line may route into (CC1-R1).

object
id
required
Id
string
name
required
Name
string
members
required
Members
integer
strategy
required
Strategy
string
queue_routing_enabled
Queue Routing Enabled
boolean
Example
{
  "draft": {
    "name": "Business phone",
    "greeting": "Thank you for calling. We will be with you shortly.",
    "waiting_message": "Your call is important to us. Please stay on the line.",
    "timeout_message": "We are unable to answer right now. Please call again later.",
    "ai_offer_message": "An AI representative is available. Press 3 to speak with it, or stay on the line for our team.",
    "answer_order": "ai_first",
    "ai_offer_mode": "ask",
    "strategy": "ring_together",
    "ring_seconds": 20,
    "max_wait_seconds": 300,
    "max_callers": 25,
    "announcement_seconds": 45,
    "announce_position": true,
    "callback_enabled": true,
    "voicemail_enabled": true,
    "callback_attempts": 2,
    "music": "calm",
    "voicemail_greeting": "Please leave your name, your number and a short message after the tone.",
    "closed_message": "Thank you for calling. We are closed right now.",
    "closed_message_before_forward": true,
    "overflow_chain": [
      {
        "kind": "voicemail"
      }
    ],
    "after_hours_chain": [
      {
        "kind": "voicemail"
      }
    ],
    "receptionist_voice_prompts": true,
    "schedule": {
      "open_steps": [
        {
          "type": "menu",
          "timeout_seconds": 5,
          "max_invalid_attempts": 2,
          "timeout_branch": [
            {
              "type": "ring_humans",
              "timeout_seconds": 20
            }
          ]
        }
      ],
      "closed_steps": [
        {
          "type": "menu",
          "timeout_seconds": 5,
          "max_invalid_attempts": 2,
          "timeout_branch": [
            {
              "type": "ring_humans",
              "timeout_seconds": 20
            }
          ]
        }
      ]
    }
  },
  "draft_source": "saved",
  "published": {
    "name": "Business phone",
    "greeting": "Thank you for calling. We will be with you shortly.",
    "waiting_message": "Your call is important to us. Please stay on the line.",
    "timeout_message": "We are unable to answer right now. Please call again later.",
    "ai_offer_message": "An AI representative is available. Press 3 to speak with it, or stay on the line for our team.",
    "answer_order": "ai_first",
    "ai_offer_mode": "ask",
    "strategy": "ring_together",
    "ring_seconds": 20,
    "max_wait_seconds": 300,
    "max_callers": 25,
    "announcement_seconds": 45,
    "announce_position": true,
    "callback_enabled": true,
    "voicemail_enabled": true,
    "callback_attempts": 2,
    "music": "calm",
    "voicemail_greeting": "Please leave your name, your number and a short message after the tone.",
    "closed_message": "Thank you for calling. We are closed right now.",
    "closed_message_before_forward": true,
    "overflow_chain": [
      {
        "kind": "voicemail"
      }
    ],
    "after_hours_chain": [
      {
        "kind": "voicemail"
      }
    ],
    "receptionist_voice_prompts": true,
    "schedule": {
      "open_steps": [
        {
          "type": "menu",
          "timeout_seconds": 5,
          "max_invalid_attempts": 2,
          "timeout_branch": [
            {
              "type": "ring_humans",
              "timeout_seconds": 20
            }
          ]
        }
      ],
      "closed_steps": [
        {
          "type": "menu",
          "timeout_seconds": 5,
          "max_invalid_attempts": 2,
          "timeout_branch": [
            {
              "type": "ring_humans",
              "timeout_seconds": 20
            }
          ]
        }
      ]
    }
  },
  "prompts": [
    {
      "prompt": "greeting"
    }
  ],
  "queue_routing_enabled": false
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}