Class: Vapi::TransferPlan

Inherits:
Object
  • Object
show all
Defined in:
lib/vapi_server_sdk/types/transfer_plan.rb

Constant Summary collapse

OMIT = 
Object.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mode:, message: OMIT, timeout: OMIT, sip_verb: OMIT, hold_audio_url: OMIT, transfer_complete_audio_url: OMIT, twiml: OMIT, summary_plan: OMIT, sip_headers_in_refer_to_enabled: OMIT, fallback_plan: OMIT, additional_properties: nil) ⇒ Vapi::TransferPlan

Parameters:

  • mode (Vapi::TransferPlanMode) —

    This configures how transfer is executed and the experience of the destination party receiving the call. Usage:

    • ‘blind-transfer`: The assistant forwards the call to the destination without

    any message or summary.

    • ‘blind-transfer-add-summary-to-sip-header`: The assistant forwards the call to

    the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.

    • ‘warm-transfer-say-message`: The assistant dials the destination, delivers the

    ‘message` to the destination party, connects the customer, and leaves the call.

    • ‘warm-transfer-say-summary`: The assistant dials the destination, provides a

    summary of the call to the destination party, connects the customer, and leaves the call.

    • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`: The

    assistant dials the destination, waits for the operator to speak, delivers the ‘message` to the destination party, and then connects the customer.

    • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`: The

    assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.

    • ‘warm-transfer-twiml`: The assistant dials the destination, executes the twiml

    instructions on the destination call leg, connects the customer, and leaves the call.

    • ‘warm-transfer-experimental`: The assistant puts the customer on hold, dials

    the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the ‘fallbackMessage` to the customer and optionally ends the call. @default ’blind-transfer’

  • message (Vapi::TransferPlanMessage) (defaults to: OMIT) —

    This is the message the assistant will deliver to the destination party before connecting the customer. Usage:

    • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header`,

    ‘warm-transfer-say-message`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`, or `warm-transfer-experimental`.

  • timeout (Float) (defaults to: OMIT) —

    This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary @default 60

  • sip_verb (Hash{String => Object}) (defaults to: OMIT) —

    This specifies the SIP verb to use while transferring the call.

    • ‘refer’: Uses SIP REFER to transfer the call (default)

    • ‘bye’: Ends current call with SIP BYE

    • ‘dial’: Uses SIP DIAL to transfer the call

  • hold_audio_url (String) (defaults to: OMIT) —

    This is the URL to an audio file played while the customer is on hold during transfer. Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • Used when transferring calls to play hold audio for the customer.

    • Must be a publicly accessible URL to an audio file.

    • Supported formats: MP3 and WAV.

    • If not provided, the default hold audio will be used.

  • transfer_complete_audio_url (String) (defaults to: OMIT) —

    This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like ‘beep’ to notify that the transfer is complete. Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • Used when transferring calls to play hold audio for the destination party.

    • Must be a publicly accessible URL to an audio file.

    • Supported formats: MP3 and WAV.

  • twiml (String) (defaults to: OMIT) —

    This is the TwiML instructions to execute on the destination call leg before connecting the customer. Usage:

    • Used only when ‘mode` is `warm-transfer-twiml`.

    • Supports only ‘Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs.

    • Maximum length is 4096 characters.

    Example: “‘ <Say voice=“alice” language=“en-US”>Hello, transferring a customer to you.</Say> <Pause length=“2”/> <Say>They called about billing questions.</Say> “`

  • summary_plan (Vapi::SummaryPlan) (defaults to: OMIT) —

    This is the plan for generating a summary of the call to present to the destination party. Usage:

    • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header` or

    ‘warm-transfer-say-summary` or `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` or `warm-transfer-experimental`.

  • sip_headers_in_refer_to_enabled (Boolean) (defaults to: OMIT) —

    This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params. @default false

  • fallback_plan (Vapi::TransferFallbackPlan) (defaults to: OMIT) —

    This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human). Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • If not provided when using ‘warm-transfer-experimental`, a default message

    will be used.

  • additional_properties (OpenStruct) (defaults to: nil) —

    Additional properties unmapped to the current class definition



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 206

def initialize(mode:, message: OMIT, timeout: OMIT, sip_verb: OMIT, hold_audio_url: OMIT,
               transfer_complete_audio_url: OMIT, twiml: OMIT, summary_plan: OMIT, sip_headers_in_refer_to_enabled: OMIT, fallback_plan: OMIT, additional_properties: nil)
  @mode = mode
  @message = message if message != OMIT
  @timeout = timeout if timeout != OMIT
  @sip_verb = sip_verb if sip_verb != OMIT
  @hold_audio_url = hold_audio_url if hold_audio_url != OMIT
  @transfer_complete_audio_url = transfer_complete_audio_url if transfer_complete_audio_url != OMIT
  @twiml = twiml if twiml != OMIT
  @summary_plan = summary_plan if summary_plan != OMIT
  @sip_headers_in_refer_to_enabled = sip_headers_in_refer_to_enabled if sip_headers_in_refer_to_enabled != OMIT
  @fallback_plan = fallback_plan if fallback_plan != OMIT
  @additional_properties = additional_properties
  @_field_set = {
    "mode": mode,
    "message": message,
    "timeout": timeout,
    "sipVerb": sip_verb,
    "holdAudioUrl": hold_audio_url,
    "transferCompleteAudioUrl": transfer_complete_audio_url,
    "twiml": twiml,
    "summaryPlan": summary_plan,
    "sipHeadersInReferToEnabled": sip_headers_in_refer_to_enabled,
    "fallbackPlan": fallback_plan
  }.reject do |_k, v|
    v == OMIT
  end
end

Instance Attribute Details

#additional_properties ⇒ OpenStruct (readonly)

Returns Additional properties unmapped to the current class definition.

Returns:

  • (OpenStruct) —

    Additional properties unmapped to the current class definition



110
111
112
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 110

def additional_properties
  @additional_properties
end

#fallback_plan ⇒ Vapi::TransferFallbackPlan (readonly)

Returns This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human). Usage:

  • Used only when ‘mode` is `warm-transfer-experimental`.

  • If not provided when using ‘warm-transfer-experimental`, a default message

will be used.

Returns:

  • (Vapi::TransferFallbackPlan) —

    This configures the fallback plan when the transfer fails (destination unreachable, busy, or not human). Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • If not provided when using ‘warm-transfer-experimental`, a default message

    will be used.



108
109
110
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 108

def fallback_plan
  @fallback_plan
end

#hold_audio_url ⇒ String (readonly)

Returns This is the URL to an audio file played while the customer is on hold during transfer. Usage:

  • Used only when ‘mode` is `warm-transfer-experimental`.

  • Used when transferring calls to play hold audio for the customer.

  • Must be a publicly accessible URL to an audio file.

  • Supported formats: MP3 and WAV.

  • If not provided, the default hold audio will be used.

Returns:

  • (String) —

    This is the URL to an audio file played while the customer is on hold during transfer. Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • Used when transferring calls to play hold audio for the customer.

    • Must be a publicly accessible URL to an audio file.

    • Supported formats: MP3 and WAV.

    • If not provided, the default hold audio will be used.



66
67
68
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 66

def hold_audio_url
  @hold_audio_url
end

#message ⇒ Vapi::TransferPlanMessage (readonly)

Returns This is the message the assistant will deliver to the destination party before connecting the customer. Usage:

  • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header`,

‘warm-transfer-say-message`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`, or `warm-transfer-experimental`.

Returns:

  • (Vapi::TransferPlanMessage) —

    This is the message the assistant will deliver to the destination party before connecting the customer. Usage:

    • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header`,

    ‘warm-transfer-say-message`, `warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`, or `warm-transfer-experimental`.



48
49
50
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 48

def message
  @message
end

#mode ⇒ Vapi::TransferPlanMode (readonly)

Returns This configures how transfer is executed and the experience of the destination party receiving the call. Usage:

  • ‘blind-transfer`: The assistant forwards the call to the destination without

any message or summary.

  • ‘blind-transfer-add-summary-to-sip-header`: The assistant forwards the call to

the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.

  • ‘warm-transfer-say-message`: The assistant dials the destination, delivers the

‘message` to the destination party, connects the customer, and leaves the call.

  • ‘warm-transfer-say-summary`: The assistant dials the destination, provides a

summary of the call to the destination party, connects the customer, and leaves the call.

  • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`: The

assistant dials the destination, waits for the operator to speak, delivers the ‘message` to the destination party, and then connects the customer.

  • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`: The

assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.

  • ‘warm-transfer-twiml`: The assistant dials the destination, executes the twiml

instructions on the destination call leg, connects the customer, and leaves the call.

  • ‘warm-transfer-experimental`: The assistant puts the customer on hold, dials

the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the ‘fallbackMessage` to the customer and optionally ends the call. @default ’blind-transfer’.

Returns:

  • (Vapi::TransferPlanMode) —

    This configures how transfer is executed and the experience of the destination party receiving the call. Usage:

    • ‘blind-transfer`: The assistant forwards the call to the destination without

    any message or summary.

    • ‘blind-transfer-add-summary-to-sip-header`: The assistant forwards the call to

    the destination and adds a SIP header X-Transfer-Summary to the call to include the summary.

    • ‘warm-transfer-say-message`: The assistant dials the destination, delivers the

    ‘message` to the destination party, connects the customer, and leaves the call.

    • ‘warm-transfer-say-summary`: The assistant dials the destination, provides a

    summary of the call to the destination party, connects the customer, and leaves the call.

    • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-message`: The

    assistant dials the destination, waits for the operator to speak, delivers the ‘message` to the destination party, and then connects the customer.

    • ‘warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary`: The

    assistant dials the destination, waits for the operator to speak, provides a summary of the call to the destination party, and then connects the customer.

    • ‘warm-transfer-twiml`: The assistant dials the destination, executes the twiml

    instructions on the destination call leg, connects the customer, and leaves the call.

    • ‘warm-transfer-experimental`: The assistant puts the customer on hold, dials

    the destination, and if the destination answers (and is human), delivers a message or summary before connecting the customer. If the destination is unreachable or not human (e.g., with voicemail detection), the assistant delivers the ‘fallbackMessage` to the customer and optionally ends the call. @default ’blind-transfer’



40
41
42
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 40

def mode
  @mode
end

#sip_headers_in_refer_to_enabled ⇒ Boolean (readonly)

Returns This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params. @default false.

Returns:

  • (Boolean) —

    This flag includes the sipHeaders from above in the refer to sip uri as url encoded query params. @default false



101
102
103
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 101

def sip_headers_in_refer_to_enabled
  @sip_headers_in_refer_to_enabled
end

#sip_verb ⇒ Hash{String => Object} (readonly)

Returns This specifies the SIP verb to use while transferring the call.

  • ‘refer’: Uses SIP REFER to transfer the call (default)

  • ‘bye’: Ends current call with SIP BYE

  • ‘dial’: Uses SIP DIAL to transfer the call.

Returns:

  • (Hash{String => Object}) —

    This specifies the SIP verb to use while transferring the call.

    • ‘refer’: Uses SIP REFER to transfer the call (default)

    • ‘bye’: Ends current call with SIP BYE

    • ‘dial’: Uses SIP DIAL to transfer the call



57
58
59
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 57

def sip_verb
  @sip_verb
end

#summary_plan ⇒ Vapi::SummaryPlan (readonly)

Returns This is the plan for generating a summary of the call to present to the destination party. Usage:

  • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header` or

‘warm-transfer-say-summary` or `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` or `warm-transfer-experimental`.

Returns:

  • (Vapi::SummaryPlan) —

    This is the plan for generating a summary of the call to present to the destination party. Usage:

    • Used only when ‘mode` is `blind-transfer-add-summary-to-sip-header` or

    ‘warm-transfer-say-summary` or `warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary` or `warm-transfer-experimental`.



97
98
99
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 97

def summary_plan
  @summary_plan
end

#timeout ⇒ Float (readonly)

Returns This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary @default 60.

Returns:

  • (Float) —

    This is the timeout in seconds for the warm-transfer-wait-for-operator-to-speak-first-and-then-say-message/summary @default 60



52
53
54
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 52

def timeout
  @timeout
end

#transfer_complete_audio_url ⇒ String (readonly)

Returns This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like ‘beep’ to notify that the transfer is complete. Usage:

  • Used only when ‘mode` is `warm-transfer-experimental`.

  • Used when transferring calls to play hold audio for the destination party.

  • Must be a publicly accessible URL to an audio file.

  • Supported formats: MP3 and WAV.

Returns:

  • (String) —

    This is the URL to an audio file played after the warm transfer message or summary is delivered to the destination party. It can be used to play a custom sound like ‘beep’ to notify that the transfer is complete. Usage:

    • Used only when ‘mode` is `warm-transfer-experimental`.

    • Used when transferring calls to play hold audio for the destination party.

    • Must be a publicly accessible URL to an audio file.

    • Supported formats: MP3 and WAV.



76
77
78
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 76

def transfer_complete_audio_url
  @transfer_complete_audio_url
end

#twiml ⇒ String (readonly)

Returns This is the TwiML instructions to execute on the destination call leg before connecting the customer. Usage:

  • Used only when ‘mode` is `warm-transfer-twiml`.

  • Supports only ‘Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs.

  • Maximum length is 4096 characters.

Example: “‘ <Say voice=“alice” language=“en-US”>Hello, transferring a customer to you.</Say> <Pause length=“2”/> <Say>They called about billing questions.</Say> “`.

Returns:

  • (String) —

    This is the TwiML instructions to execute on the destination call leg before connecting the customer. Usage:

    • Used only when ‘mode` is `warm-transfer-twiml`.

    • Supports only ‘Play`, `Say`, `Gather`, `Hangup` and `Pause` verbs.

    • Maximum length is 4096 characters.

    Example: “‘ <Say voice=“alice” language=“en-US”>Hello, transferring a customer to you.</Say> <Pause length=“2”/> <Say>They called about billing questions.</Say> “`



89
90
91
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 89

def twiml
  @twiml
end

Class Method Details

.from_json(json_object:) ⇒ Vapi::TransferPlan

Deserialize a JSON object to an instance of TransferPlan

Parameters:

  • json_object (String)

Returns:



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 239

def self.from_json(json_object:)
  struct = JSON.parse(json_object, object_class: OpenStruct)
  parsed_json = JSON.parse(json_object)
  mode = parsed_json["mode"]
  if parsed_json["message"].nil?
    message = nil
  else
    message = parsed_json["message"].to_json
    message = Vapi::TransferPlanMessage.from_json(json_object: message)
  end
  timeout = parsed_json["timeout"]
  sip_verb = parsed_json["sipVerb"]
  hold_audio_url = parsed_json["holdAudioUrl"]
  transfer_complete_audio_url = parsed_json["transferCompleteAudioUrl"]
  twiml = parsed_json["twiml"]
  if parsed_json["summaryPlan"].nil?
    summary_plan = nil
  else
    summary_plan = parsed_json["summaryPlan"].to_json
    summary_plan = Vapi::SummaryPlan.from_json(json_object: summary_plan)
  end
  sip_headers_in_refer_to_enabled = parsed_json["sipHeadersInReferToEnabled"]
  if parsed_json["fallbackPlan"].nil?
    fallback_plan = nil
  else
    fallback_plan = parsed_json["fallbackPlan"].to_json
    fallback_plan = Vapi::TransferFallbackPlan.from_json(json_object: fallback_plan)
  end
  new(
    mode: mode,
    message: message,
    timeout: timeout,
    sip_verb: sip_verb,
    hold_audio_url: hold_audio_url,
    transfer_complete_audio_url: transfer_complete_audio_url,
    twiml: twiml,
    summary_plan: summary_plan,
    sip_headers_in_refer_to_enabled: sip_headers_in_refer_to_enabled,
    fallback_plan: fallback_plan,
    additional_properties: struct
  )
end

.validate_raw(obj:) ⇒ Void

Leveraged for Union-type generation, validate_raw attempts to parse the given

hash and check each fields type against the current object's property
definitions.

Parameters:

  • obj (Object)

Returns:

  • (Void) 


295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 295

def self.validate_raw(obj:)
  obj.mode.is_a?(Vapi::TransferPlanMode) != false || raise("Passed value for field obj.mode is not the expected type, validation failed.")
  obj.message.nil? || Vapi::TransferPlanMessage.validate_raw(obj: obj.message)
  obj.timeout&.is_a?(Float) != false || raise("Passed value for field obj.timeout is not the expected type, validation failed.")
  obj.sip_verb&.is_a?(Hash) != false || raise("Passed value for field obj.sip_verb is not the expected type, validation failed.")
  obj.hold_audio_url&.is_a?(String) != false || raise("Passed value for field obj.hold_audio_url is not the expected type, validation failed.")
  obj.transfer_complete_audio_url&.is_a?(String) != false || raise("Passed value for field obj.transfer_complete_audio_url is not the expected type, validation failed.")
  obj.twiml&.is_a?(String) != false || raise("Passed value for field obj.twiml is not the expected type, validation failed.")
  obj.summary_plan.nil? || Vapi::SummaryPlan.validate_raw(obj: obj.summary_plan)
  obj.sip_headers_in_refer_to_enabled&.is_a?(Boolean) != false || raise("Passed value for field obj.sip_headers_in_refer_to_enabled is not the expected type, validation failed.")
  obj.fallback_plan.nil? || Vapi::TransferFallbackPlan.validate_raw(obj: obj.fallback_plan)
end

Instance Method Details

#to_json(*_args) ⇒ String

Serialize an instance of TransferPlan to a JSON object

Returns:

  • (String) 


285
286
287
 
# File 'lib/vapi_server_sdk/types/transfer_plan.rb', line 285

def to_json(*_args)
  @_field_set&.to_json
end