Skip to content
vocapable.Docs

Move this caller to a teammate or a number

POST
/v1/workspace/calls/{call_id}/transfers
curl --request POST \
  --url https://api.vocapable.com/v1/workspace/calls/example/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "mode": "warm", "to_user_id": "example", "destination_id": "example", "notes": "example", "customer_agreed": false }'

Commit recipient custody before the once-only carrier request (PRD E5-R1..R3).

A retry finds transfer_pending and cannot originate a second recipient leg. Lost responses preserve the requested transfer; signed callbacks can bind its exact SID.

  • warm - the teammate is rung into the call; the handler hands over when they joined. An AI-handed-over or queued caller is whispered to the teammate first (E3-R6): their leg hears the brief before it joins the room.
  • blind - the customer is put on hold with the line’s hold audio, the teammate is rung, and the handler’s leg is hung up: they owe the wrap-up at once. The open transfer holds the caller until the teammate joins; a miss rings the handler back once, then apologizes and leaves a callback task (transfer_modes).
  • external - an owner-allow-listed number is rung with the business caller ID; the handler hands over when it answered, exactly like a warm transfer.
  • receptionist - the line’s AI receptionist takes the caller (E5-R2); see :func:_hand_to_receptionist and workspace_calls.receptionist.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
call_id
required
Call Id
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
WorkspaceTransferRequest

Move the caller (PRD E5-R1..R3).

warm (the default) and blind name a teammate; external names an allow-listed destination; receptionist names nobody.

object
mode
Mode
string
default: warm
Allowed values: warm blind external receptionist
to_user_id
Any of:
string
>= 1 characters <= 64 characters
destination_id
Any of:
string
>= 1 characters <= 64 characters
notes
Any of:
string
<= 5000 characters
customer_agreed
Customer Agreed
boolean

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
WorkspaceCall
object
id
required
Id
string
contact_id
required
Any of:
string
organization_id
required
Any of:
string
organization_name
required
Any of:
string
contact_name
required
Any of:
string
handler
required
Any of:
WorkspacePersonRef

A teammate named on a record: the id the server holds and the name to show.

object
user_id
required
User Id
string
name
required
Name
string
direction
required
Direction
string
Allowed values: outbound inbound handoff
phase
required
Phase
string
Allowed values: requested ringing talking transfer_pending wrap_up completed failed abandoned
muted
required
Muted
boolean
on_hold
required
On Hold
boolean
recording
required
Recording
string
Allowed values: off on
requested_at
required
Requested At
string format: date-time
answered_at
required
Any of:
string format: date-time
ended_at
required
Any of:
string format: date-time
wrapped_at
required
Any of:
string format: date-time
outcome
required
Any of:
string
Allowed values: conversation callback no_answer do_not_contact not_interested voicemail failed wrong_number
notes
required
Any of:
string
next_step
required
Any of:
string
callback_at
required
Any of:
string format: date-time
failure_reason
required
Any of:
string
transfer
required
Any of:
WorkspaceCallTransfer
object
id
required
Id
string
call_id
required
Call Id
string
from_user
required
Any of:
WorkspacePersonRef

A teammate named on a record: the id the server holds and the name to show.

object
user_id
required
User Id
string
name
required
Name
string
to_user
required
Any of:
WorkspacePersonRef

A teammate named on a record: the id the server holds and the name to show.

object
user_id
required
User Id
string
name
required
Name
string
state
required
State
string
Allowed values: requested ringing accepted completed declined timed_out failed returned
context
required
WorkspaceTransferContext
object
need
required
Any of:
string
notes
required
Any of:
string
requested_at
required
Requested At
string format: date-time
accepted_at
required
Any of:
string format: date-time
completed_at
required
Any of:
string format: date-time
ended_at
required
Any of:
string format: date-time
revision
required
Revision
integer
kind
Kind
string
default: warm
Allowed values: warm blind external park receptionist
destination
Any of:
WorkspaceTransferDestination

A number the owner allow-listed for external transfers and three-way calls (E5-R3).

object
id
required
Id
string
name
required
Name
string
phone_e164
required
Phone E164
string
revision
required
Revision
integer
payment_line
Payment Line
boolean
transferred_from_call_id
required
Any of:
string
caller_request_id
required
Any of:
string
links
required
WorkspaceCallLinks

The work a call was placed from, carried to its wrap-up (PRD E10-R1/R2).

Each link is null when there is none, and also when the record has since been deleted or is no longer one the handler may see.

object
task
required
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
opportunity
required
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
case
required
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
callback
required
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
caller_request_id
required
Any of:
string
missed
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
voicemail
Any of:
WorkspaceCallLinkRef

One piece of work a call is linked to, as the handler may see it.

object
id
required
Id
string
title
required
Title
string
state
required
State
string
revision
required
Revision
integer
revision
required
Revision
integer
channel
required
Channel
string
Allowed values: app personal_sim carrier_callback
line
required
Any of:
WorkspaceCallLine

The business line a call came from (E12-R1): the company’s own number, named.

object
id
required
Id
string
name
required
Name
string
phone_e164
required
Phone E164
string
voicemail_drop_name
Any of:
string
voicemail_drop_at
Any of:
string format: date-time
held_at
Any of:
string format: date-time
participants
Participants
Array<object>
WorkspaceCallParticipant

An extra leg of a live call (E5-R4 three-way, E5-R7 the handler’s own phone).

object
id
required
Id
string
kind
required
Kind
string
Allowed values: teammate external device
person
required
Any of:
WorkspacePersonRef

A teammate named on a record: the id the server holds and the name to show.

object
user_id
required
User Id
string
name
required
Name
string
destination_name
required
Any of:
string
destination_e164
required
Any of:
string
state
required
State
string
Allowed values: requested ringing joined left failed dropped
requested_at
required
Requested At
string format: date-time
joined_at
required
Any of:
string format: date-time
ended_at
required
Any of:
string format: date-time
transcription
WorkspaceCallTranscription

What a person is told about a call’s transcript (PRD E7-R6, E6-R8).

label is the exact sentence the clients show (“Transcribing”, “Not recorded - made from a personal phone”, …) so the web console and the app use the same words.

object
status
Status
string
default: off
Allowed values: off live ended failed
untranscribed_reason
Any of:
string
Allowed values: personal_phone consent_off disclosure_not_played feature_off carrier_unavailable not_connected
label
Label
string
default: Not transcribed
wrap_up_provenance
Wrap Up Provenance
object
key
additional properties
string
Allowed values: ai_drafted edited manual
recording_status
Any of:
WorkspaceCallRecordingStatus

The persistent recording indicator and its controls (Apple 2.5.14).

object
state
required
State
string
Allowed values: off starting recording paused stopped completed failed
label
required
Label
string
line_mode
required
Line Mode
string
Allowed values: off record_all on_demand
can_start
required
Can Start
boolean
can_pause
required
Can Pause
boolean
can_resume
required
Can Resume
boolean
can_stop
required
Can Stop
boolean
announcement_pending
required
Announcement Pending
boolean
disclosure_played_at
required
Any of:
string format: date-time
refused
required
Refused
boolean
consent_hint
required
Any of:
WorkspaceConsentHint

A UI hint about the far party’s location; NEVER suppresses the announcement.

object
kind
required
Kind
string
Allowed values: all_party_state unknown no_all_party_hint
state
required
Any of:
string
label
required
Label
string
refusal_source
Any of:
string
Allowed values: rep keypress ai_receptionist
supervision
Any of:
WorkspaceCallSupervision

A manager or owner listening to, whispering to or joined to a live call.

Shown to the REP on their own call (notice: “Priya is listening”) - supervision is never silent. ringing = the supervisor’s leg is connecting; joined = the carrier confirmed it is in the call.

object
id
required
Id
string
supervisor
required
WorkspacePersonRef

A teammate named on a record: the id the server holds and the name to show.

object
user_id
required
User Id
string
name
required
Name
string
mode
required
Mode
string
Allowed values: listen whisper barge
channel
required
Channel
string
Allowed values: app phone
state
required
State
string
Allowed values: requested ringing joined ended failed
notice
required
Notice
string
requested_at
required
Requested At
string format: date-time
joined_at
required
Any of:
string format: date-time
ended_at
required
Any of:
string format: date-time
end_reason
required
Any of:
string
revision
required
Revision
integer
answered_from
Any of:
WorkspaceCallAnsweredFrom

How an inbound caller reached the person who answered (PRD E3-R2, E3-R11).

queue: they answered the caller from the shared-phone queue (app, browser or verified phone) - ticket_id is the queue’s record of the caller. ai_handoff: they took the AI receptionist’s direct handoff - handoff_request_id is the live handoff (its brief is /call-handoffs/{id}/brief). ai_call_id is the AI receptionist’s call the caller had first, when there was one.

object
kind
required
Kind
string
Allowed values: queue ai_handoff
ticket_id
required
Any of:
string
handoff_request_id
required
Any of:
string
ai_call_id
required
Any of:
string
scheduled_ring
Any of:
WorkspaceCallScheduledRing

A due scheduled callback the server rang the person’s app for (PRD E2-R7).

label is what the ring shows once the app has read the call (“Callback: Dana, Lakeside”); the VoIP push itself carries identifiers only. The customer is dialled only after the person answers that ring.

object
task_id
required
Task Id
string
due_at
required
Due At
string format: date-time
label
required
Label
string
Example
{
  "direction": "outbound",
  "phase": "requested",
  "recording": "off",
  "outcome": "conversation",
  "transfer": {
    "state": "requested",
    "kind": "warm",
    "destination": {
      "payment_line": false
    }
  },
  "channel": "app",
  "participants": [
    {
      "kind": "teammate",
      "state": "requested"
    }
  ],
  "transcription": {
    "status": "off",
    "untranscribed_reason": "personal_phone",
    "label": "Not transcribed"
  },
  "wrap_up_provenance": {
    "additionalProperty": "ai_drafted"
  },
  "recording_status": {
    "state": "off",
    "line_mode": "off",
    "consent_hint": {
      "kind": "all_party_state"
    },
    "refusal_source": "rep"
  },
  "supervision": {
    "mode": "listen",
    "channel": "app",
    "state": "requested"
  },
  "answered_from": {
    "kind": "queue"
  }
}

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": {}
    }
  ]
}