Class: VoiceML::CallsResource

Inherits:
BaseResource show all
Defined in:
lib/voiceml/resources/calls.rb

Overview

Operations on ‘/Calls` and call-scoped sub-resources (Recordings, Streams, Siprec, Transcriptions, Notifications, Events, UserDefinedMessages).

All methods accept idiomatic snake_case keyword arguments — they’re translated to Twilio’s PascalCase wire names internally.

Constant Summary collapse

CREATE_FIELDS =

Create-call form-field map (snake_case kwarg -> Twilio wire name).

{
  'To'                                    => :to,
  'From'                                  => :from,
  'Url'                                   => :url,
  'Method'                                => :method,
  'Twiml'                                 => :twiml,
  'ApplicationSid'                        => :application_sid,
  'FallbackUrl'                           => :fallback_url,
  'FallbackMethod'                        => :fallback_method,
  'StatusCallback'                        => :status_callback,
  'StatusCallbackMethod'                  => :status_callback_method,
  'StatusCallbackEvent'                   => :status_callback_event,
  'MachineDetection'                      => :machine_detection,
  'MachineDetectionTimeout'               => :machine_detection_timeout,
  'MachineDetectionSpeechThreshold'       => :machine_detection_speech_threshold,
  'MachineDetectionSpeechEndThreshold'    => :machine_detection_speech_end_threshold,
  'MachineDetectionSilenceTimeout'        => :machine_detection_silence_timeout,
  'AsyncAmdStatusCallback'                => :async_amd_status_callback,
  'AsyncAmdStatusCallbackMethod'          => :async_amd_status_callback_method,
  'Record'                                => :record,
  'RecordingStatusCallback'               => :recording_status_callback,
  'RecordingStatusCallbackMethod'         => :recording_status_callback_method,
  'RecordingStatusCallbackEvent'          => :recording_status_callback_event,
  'RecordingChannels'                     => :recording_channels,
  'RecordingTrack'                        => :recording_track,
  'Trim'                                  => :trim,
  'Timeout'                               => :timeout,
  'SendDigits'                            => :send_digits,
  'CallerId'                              => :caller_id,
  'CallReason'                            => :call_reason,
  'SipAuthUsername'                       => :sip_auth_username,
  'SipAuthPassword'                       => :sip_auth_password,
  'Byoc'                                  => :byoc,
  'AsyncAmd'                              => :async_amd,
  'CallToken'                             => :call_token
}.freeze
UPDATE_FIELDS = 
{
  'Status'                => :status,
  'Twiml'                 => :twiml,
  'Url'                   => :url,
  'Method'                => :method,
  'FallbackUrl'           => :fallback_url,
  'FallbackMethod'        => :fallback_method,
  'StatusCallback'        => :status_callback,
  'StatusCallbackMethod'  => :status_callback_method,
  'StatusCallbackEvent'   => :status_callback_event
}.freeze
LIST_FIELDS = 
{
  'To'             => :to,
  'From'           => :from,
  'Status'         => :status,
  'ParentCallSid'  => :parent_call_sid,
  'StartTime'      => :start_time,
  'StartTime<'     => :start_time_lt,
  'StartTime>'     => :start_time_gt,
  # Note: spec defines `StartTime>=` and `StartTime<=` as the literal query names.
  'StartTime>='    => :start_time_gte,
  'StartTime<='    => :start_time_lte,
  'EndTime'        => :end_time,
  'EndTime<'       => :end_time_lt,
  'EndTime>'       => :end_time_gt,
  'Page'           => :page,
  'PageSize'       => :page_size,
  'PageToken'      => :page_token
}.freeze
LIST_RECORDINGS_FIELDS = 
{
  'DateCreated'   => :date_created,
  'DateCreated<'  => :date_created_lt,
  'DateCreated>'  => :date_created_gt,
  'Page'          => :page,
  'PageSize'      => :page_size,
  'PageToken'     => :page_token
}.freeze
LIST_STUB_PAGE_FIELDS = 
{
  'Page'      => :page,
  'PageSize'  => :page_size,
  'PageToken' => :page_token
}.freeze
LIST_NOTIFICATIONS_FIELDS = 
{
  'Page'          => :page,
  'PageSize'      => :page_size,
  'PageToken'     => :page_token,
  'Log'           => :log,
  'MessageDate'   => :message_date,
  'MessageDate<'  => :message_date_lt,
  'MessageDate>'  => :message_date_gt
}.freeze
START_RECORDING_FIELDS = 
{
  'RecordingMaxDuration'           => :recording_max_duration,
  'RecordingChannels'              => :recording_channels,
  'PlayBeep'                       => :play_beep,
  'RecordingStatusCallback'        => :recording_status_callback,
  'RecordingStatusCallbackMethod'  => :recording_status_callback_method,
  'RecordingStatusCallbackEvent'   => :recording_status_callback_event
}.freeze
START_STREAM_FIELDS = 
{
  'Url'                  => :url,
  'Track'                => :track,
  'Name'                 => :name,
  'StatusCallback'       => :status_callback,
  'StatusCallbackMethod' => :status_callback_method
}.freeze
START_SIPREC_FIELDS = 
{
  'Name'                 => :name,
  'ConnectorName'        => :connector_name,
  'Track'                => :track,
  'StatusCallback'       => :status_callback,
  'StatusCallbackMethod' => :status_callback_method
}.freeze
START_TRANSCRIPTION_FIELDS = 
{
  'Name'                 => :name,
  'Track'                => :track,
  'LanguageCode'         => :language_code,
  'TranscriptionEngine'  => :transcription_engine,
  'ProfanityFilter'      => :profanity_filter,
  'PartialResults'       => :partial_results,
  'Hints'                => :hints,
  'StatusCallback'       => :status_callback,
  'StatusCallbackMethod' => :status_callback_method,
  'StatusCallbackEvents' => :status_callback_events
}.freeze
START_PAYMENT_FIELDS = 
{
  'IdempotencyKey'         => :idempotency_key,
  'StatusCallback'         => :status_callback,
  'BankAccountType'        => :bank_account_type,
  'ChargeAmount'           => :charge_amount,
  'Currency'               => :currency,
  'Description'            => :description,
  'Input'                  => :input,
  'MinPostalCodeLength'    => :min_postal_code_length,
  'Parameter'              => :parameter,
  'PaymentConnector'       => :payment_connector,
  'PaymentMethod'          => :payment_method,
  'PostalCode'             => :postal_code,
  'SecurityCode'           => :security_code,
  'Timeout'                => :timeout,
  'TokenType'              => :token_type,
  'ValidCardTypes'         => :valid_card_types,
  'RequireMatchingInputs'  => :require_matching_inputs,
  'Confirmation'           => :confirmation
}.freeze
UPDATE_PAYMENT_FIELDS = 
{
  'IdempotencyKey' => :idempotency_key,
  'StatusCallback' => :status_callback,
  'Capture'        => :capture,
  'Status'         => :status
}.freeze

Instance Method Summary collapse

Methods inherited from BaseResource

#initialize

Constructor Details

This class inherits a constructor from VoiceML::BaseResource

Instance Method Details

#create(**kwargs) ⇒ VoiceML::Call

Create a new outbound call.

Pass at most one of ‘url:` / `twiml:` / `application_sid:` (Twiml wins if multiple are set — Twilio’s documented precedence).

Returns:



208
209
210
211
 
# File 'lib/voiceml/resources/calls.rb', line 208

def create(**kwargs)
  data = @transport.request(:post, path('Calls'), form: form_params(CREATE_FIELDS, kwargs))
  Call.from_hash(data)
end

#delete(call_sid) ⇒ nil

Returns:

  • (nil) 


227
228
229
230
 
# File 'lib/voiceml/resources/calls.rb', line 227

def delete(call_sid)
  @transport.request(:delete, path('Calls', call_sid))
  nil
end

#delete_recording(call_sid, recording_sid) ⇒ nil

Returns:

  • (nil) 


265
266
267
268
 
# File 'lib/voiceml/resources/calls.rb', line 265

def delete_recording(call_sid, recording_sid)
  @transport.request(:delete, path('Calls', call_sid, 'Recordings', recording_sid))
  nil
end

#each(**kwargs) {|VoiceML::Call| ... } ⇒ Enumerator<VoiceML::Call>

Walk every page of /Calls and yield each Call. Returns an Enumerator when called without a block.

Yields:

Returns:



190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/voiceml/resources/calls.rb', line 190

def each(**kwargs, &block)
  return enum_for(:each, **kwargs) unless block

  page_num = kwargs.delete(:page) || 0
  loop do
    chunk = list(**kwargs, page: page_num)
    chunk.calls.each(&block)
    break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.calls.empty?
    page_num += 1
  end
end

#get(call_sid) ⇒ VoiceML::Call

Returns:



214
215
216
217
 
# File 'lib/voiceml/resources/calls.rb', line 214

def get(call_sid)
  data = @transport.request(:get, path('Calls', call_sid))
  Call.from_hash(data)
end

#get_notification(call_sid, notification_sid) ⇒ Hash

Returns:

  • (Hash) 


366
367
368
 
# File 'lib/voiceml/resources/calls.rb', line 366

def get_notification(call_sid, notification_sid)
  @transport.request(:get, path('Calls', call_sid, 'Notifications', notification_sid))
end

#get_recording(call_sid, recording_sid) ⇒ VoiceML::Recording

Returns:



250
251
252
253
254
 
# File 'lib/voiceml/resources/calls.rb', line 250

def get_recording(call_sid, recording_sid)
  Recording.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Recordings', recording_sid))
  )
end

#get_siprec(call_sid, siprec_sid) ⇒ VoiceML::SiprecSession

Returns:



311
312
313
314
315
 
# File 'lib/voiceml/resources/calls.rb', line 311

def get_siprec(call_sid, siprec_sid)
  SiprecSession.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Siprec', siprec_sid))
  )
end

#get_stream(call_sid, stream_sid) ⇒ VoiceML::Stream

Returns:



285
286
287
 
# File 'lib/voiceml/resources/calls.rb', line 285

def get_stream(call_sid, stream_sid)
  Stream.from_hash(@transport.request(:get, path('Calls', call_sid, 'Streams', stream_sid)))
end

#get_transcription(call_sid, transcription_sid) ⇒ VoiceML::CallTranscription

Returns:



341
342
343
344
345
 
# File 'lib/voiceml/resources/calls.rb', line 341

def get_transcription(call_sid, transcription_sid)
  CallTranscription.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Transcriptions', transcription_sid))
  )
end

#list(**kwargs) ⇒ VoiceML::CallList

Returns:



180
181
182
183
 
# File 'lib/voiceml/resources/calls.rb', line 180

def list(**kwargs)
  data = @transport.request(:get, path('Calls'), params: form_params(LIST_FIELDS, kwargs))
  CallList.from_hash(data)
end

#list_events(call_sid, **kwargs) ⇒ VoiceML::EventsList

Returns:



371
372
373
374
375
376
 
# File 'lib/voiceml/resources/calls.rb', line 371

def list_events(call_sid, **kwargs)
  EventsList.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Events'),
                       params: form_params(LIST_STUB_PAGE_FIELDS, kwargs))
  )
end

#list_notifications(call_sid, **kwargs) ⇒ VoiceML::NotificationsList

Returns:



358
359
360
361
362
363
 
# File 'lib/voiceml/resources/calls.rb', line 358

def list_notifications(call_sid, **kwargs)
  NotificationsList.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Notifications'),
                       params: form_params(LIST_NOTIFICATIONS_FIELDS, kwargs))
  )
end

#list_recordings(call_sid, **kwargs) ⇒ VoiceML::RecordingList

Returns:



235
236
237
238
239
240
 
# File 'lib/voiceml/resources/calls.rb', line 235

def list_recordings(call_sid, **kwargs)
  RecordingList.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Recordings'),
                       params: form_params(LIST_RECORDINGS_FIELDS, kwargs))
  )
end

#list_siprec(call_sid) ⇒ VoiceML::SiprecList

Returns:



299
300
301
 
# File 'lib/voiceml/resources/calls.rb', line 299

def list_siprec(call_sid)
  SiprecList.from_hash(@transport.request(:get, path('Calls', call_sid, 'Siprec')))
end

#list_streams(call_sid) ⇒ VoiceML::StreamList

Returns:



273
274
275
 
# File 'lib/voiceml/resources/calls.rb', line 273

def list_streams(call_sid)
  StreamList.from_hash(@transport.request(:get, path('Calls', call_sid, 'Streams')))
end

#list_transcriptions(call_sid) ⇒ VoiceML::TranscriptionList

Returns:



327
328
329
330
331
 
# File 'lib/voiceml/resources/calls.rb', line 327

def list_transcriptions(call_sid)
  TranscriptionList.from_hash(
    @transport.request(:get, path('Calls', call_sid, 'Transcriptions'))
  )
end

#send_user_defined_message(call_sid, payload = nil) ⇒ Object

‘POST /Calls/sid/UserDefinedMessages` — always raises `NotImplementedAPIError`. Mounted on the server only as a 501 stub. The SDK forwards the call so callers get a clean exception rather than discovering at runtime that the endpoint doesn’t exist.



381
382
383
384
 
# File 'lib/voiceml/resources/calls.rb', line 381

def send_user_defined_message(call_sid, payload = nil)
  @transport.request(:post, path('Calls', call_sid, 'UserDefinedMessages'),
                     form: payload)
end

#start_payment(call_sid, **kwargs) ⇒ VoiceML::CallPayment

Begin a ‘<Pay>` session on the live call. Returns the freshly-minted CallPayment. Returns 403 when the tenant is not `pay_enabled` or has no `stripe_secret_key` configured.

‘idempotency_key:` is accepted and persisted for diagnostic visibility but replay-dedup is NOT enforced today.

Returns:



396
397
398
399
400
 
# File 'lib/voiceml/resources/calls.rb', line 396

def start_payment(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Payments'),
                            form: form_params(START_PAYMENT_FIELDS, kwargs))
  CallPayment.from_hash(data)
end

#start_recording(call_sid, **kwargs) ⇒ VoiceML::Recording

Returns:



243
244
245
246
247
 
# File 'lib/voiceml/resources/calls.rb', line 243

def start_recording(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Recordings'),
                            form: form_params(START_RECORDING_FIELDS, kwargs))
  Recording.from_hash(data)
end

#start_siprec(call_sid, **kwargs) ⇒ VoiceML::SiprecSession

Returns:



304
305
306
307
308
 
# File 'lib/voiceml/resources/calls.rb', line 304

def start_siprec(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Siprec'),
                            form: form_params(START_SIPREC_FIELDS, kwargs))
  SiprecSession.from_hash(data)
end

#start_stream(call_sid, **kwargs) ⇒ VoiceML::Stream

Returns:



278
279
280
281
282
 
# File 'lib/voiceml/resources/calls.rb', line 278

def start_stream(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Streams'),
                            form: form_params(START_STREAM_FIELDS, kwargs))
  Stream.from_hash(data)
end

#start_transcription(call_sid, **kwargs) ⇒ VoiceML::CallTranscription

Returns:



334
335
336
337
338
 
# File 'lib/voiceml/resources/calls.rb', line 334

def start_transcription(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Transcriptions'),
                            form: form_params(START_TRANSCRIPTION_FIELDS, kwargs))
  CallTranscription.from_hash(data)
end

#stop_siprec(call_sid, siprec_sid) ⇒ VoiceML::SiprecSession

Returns:



318
319
320
321
322
 
# File 'lib/voiceml/resources/calls.rb', line 318

def stop_siprec(call_sid, siprec_sid)
  data = @transport.request(:post, path('Calls', call_sid, 'Siprec', siprec_sid),
                            form: { 'Status' => 'stopped' })
  SiprecSession.from_hash(data)
end

#stop_stream(call_sid, stream_sid) ⇒ VoiceML::Stream

Returns:



290
291
292
293
294
 
# File 'lib/voiceml/resources/calls.rb', line 290

def stop_stream(call_sid, stream_sid)
  data = @transport.request(:post, path('Calls', call_sid, 'Streams', stream_sid),
                            form: { 'Status' => 'stopped' })
  Stream.from_hash(data)
end

#stop_transcription(call_sid, transcription_sid) ⇒ VoiceML::CallTranscription

Returns:



348
349
350
351
352
353
 
# File 'lib/voiceml/resources/calls.rb', line 348

def stop_transcription(call_sid, transcription_sid)
  data = @transport.request(:post,
                            path('Calls', call_sid, 'Transcriptions', transcription_sid),
                            form: { 'Status' => 'stopped' })
  CallTranscription.from_hash(data)
end

#update(call_sid, **kwargs) ⇒ VoiceML::Call

Returns:



220
221
222
223
224
 
# File 'lib/voiceml/resources/calls.rb', line 220

def update(call_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid),
                            form: form_params(UPDATE_FIELDS, kwargs))
  Call.from_hash(data)
end

#update_payment(call_sid, payment_sid, **kwargs) ⇒ VoiceML::CallPayment

Advance or terminate an existing Pay session. ‘status: “complete”` captures the collected fields; `status: “cancel”` aborts the session. `capture: …` tells the runtime which input the user is about to type next.

Returns:



408
409
410
411
412
 
# File 'lib/voiceml/resources/calls.rb', line 408

def update_payment(call_sid, payment_sid, **kwargs)
  data = @transport.request(:post, path('Calls', call_sid, 'Payments', payment_sid),
                            form: form_params(UPDATE_PAYMENT_FIELDS, kwargs))
  CallPayment.from_hash(data)
end

#update_recording(call_sid, recording_sid, status:) ⇒ VoiceML::Recording

Parameters:

  • status (String) —

    one of “in-progress”, “paused”, “stopped”.

Returns:



258
259
260
261
262
 
# File 'lib/voiceml/resources/calls.rb', line 258

def update_recording(call_sid, recording_sid, status:)
  data = @transport.request(:post, path('Calls', call_sid, 'Recordings', recording_sid),
                            form: { 'Status' => status })
  Recording.from_hash(data)
end