feat: Voice API Updates Q4 2025 (#341)

* Implementing wait NCCO action

* Implementing transfer NCCO

* Adding support for 24K audio in connect NCCO

Author: superchilled

lib/vonage/voice/actions/connect.rb

@@ -65,7 +65,7 @@ def verify_endpoint
         raise ClientError.new("'user' must be defined") unless endpoint[:user]
       when 'websocket'
         raise ClientError.new("Expected 'uri' value to be a valid URI") unless URI.parse(endpoint[:uri]).kind_of?(URI::Generic)
-        raise ClientError.new("Expected 'content-type' parameter to be either 'audio/116;rate=16000' or 'audio/116;rate=8000") unless endpoint[:'content-type'] == 'audio/116;rate=16000' || endpoint[:'content-type'] == 'audio/116;rate=8000'
+        raise ClientError.new("Expected 'content-type' parameter to be either 'audio/l16;rate=16000', 'audio/l16;rate=8000', or 'audio/l16;rate=24000'") unless ['audio/l16;rate=16000', 'audio/l16;rate=8000', 'audio/l16;rate=24000'].include?(endpoint[:'content-type'])
       when 'sip'
         raise ClientError.new("Expected 'uri' value to be a valid URI") unless URI.parse(endpoint[:uri]).kind_of?(URI::Generic) if endpoint[:uri]
         raise ClientError.new("`uri` must not be combined with `user` and `domain`") if endpoint[:uri] && (endpoint[:user] || endpoint[:domain])

lib/vonage/voice/actions/transfer.rb

@@ -0,0 +1,83 @@
+# typed: true
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Voice::Actions::Transfer
+    attr_accessor :conversation_id, :can_hear, :can_speak, :mute
+
+    def initialize(attributes = {})
+      @conversation_id = attributes.fetch(:conversation_id)
+      @can_hear = attributes.fetch(:can_hear, nil)
+      @can_speak = attributes.fetch(:can_speak, nil)
+      @mute = attributes.fetch(:mute, nil)
+
+      after_initialize!
+    end
+
+    def after_initialize!
+      validate_conversation_id
+      validate_can_hear if self.can_hear
+      validate_can_speak if self.can_speak
+      validate_mute if self.mute != nil
+    end
+
+    def validate_conversation_id
+      conversation_id = self.conversation_id
+
+      raise ClientError.new("Expected 'conversation_id' parameter to be a string") unless conversation_id.is_a?(String)
+
+      self.conversation_id
+    end
+
+    def validate_can_hear
+      can_hear = self.can_hear
+      unless can_hear.is_a?(Array) && can_hear.all? { |item| item.is_a?(String) }
+        raise ClientError.new("Expected 'can_hear' parameter to be an array of strings")
+      end
+
+      self.can_hear
+    end
+
+    def validate_can_speak
+      can_speak = self.can_speak
+      unless can_speak.is_a?(Array) && can_speak.all? { |item| item.is_a?(String) }
+        raise ClientError.new("Expected 'can_speak' parameter to be an array of strings")
+      end
+
+      self.can_speak
+    end
+
+    def validate_mute
+      mute = self.mute
+      unless [true, false].include?(mute)
+        raise ClientError.new("Expected 'mute' parameter to be a boolean")
+      end
+
+      if self.mute && self.can_speak
+        raise ClientError.new("The 'mute' parameter is not supported if 'can_speak' is also set")
+      end
+
+      self.mute
+    end
+
+    def action
+      create_transfer!(self)
+    end
+
+    def create_transfer!(builder)
+      ncco = [
+        {
+          action: 'transfer',
+          conversation_id: builder.conversation_id,
+        }
+      ]
+
+      ncco[0].merge!(canHear: builder.can_hear) if builder.can_hear
+      ncco[0].merge!(canSpeak: builder.can_speak) if builder.can_speak
+      ncco[0].merge!(mute: builder.mute) if builder.mute != nil
+
+      ncco
+    end
+  end
+end

lib/vonage/voice/actions/wait.rb

@@ -0,0 +1,43 @@
+# typed: true
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Voice::Actions::Wait
+    attr_accessor :timeout
+
+    def initialize(attributes = {})
+      @timeout = attributes.fetch(:timeout, nil)
+
+      after_initialize!
+    end
+
+    def after_initialize!
+      validate_timeout if self.timeout
+    end
+
+    def validate_timeout
+      timeout = self.timeout
+
+      raise ClientError.new("Expected 'timeout' parameter to be a number") unless timeout.is_a?(Numeric)
+
+      self.timeout
+    end
+
+    def action
+      create_wait!(self)
+    end
+
+    def create_wait!(builder)
+      ncco = [
+        {
+          action: 'wait'
+        }
+      ]
+
+      ncco[0].merge!(timeout: builder.timeout) if builder.timeout
+
+      ncco
+    end
+  end
+end

lib/vonage/voice/ncco.rb

@@ -10,7 +10,9 @@ class Voice::Ncco
       notify: Vonage::Voice::Actions::Notify,
       record: Vonage::Voice::Actions::Record,
       stream: Vonage::Voice::Actions::Stream,
-      talk: Vonage::Voice::Actions::Talk
+      talk: Vonage::Voice::Actions::Talk,
+      wait: Vonage::Voice::Actions::Wait,
+      transfer: Vonage::Voice::Actions::Transfer    
     }
 
     class << self

test/vonage/test.rb

@@ -398,6 +398,10 @@ def conversation_id
       "CON-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     end
 
+    def conversation_leg_uuid
+      "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
+    end
+
     def call_id
       "CALL-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     end

test/vonage/voice/actions/connect_test.rb

@@ -30,6 +30,39 @@ def test_create_endpoint_with_app
     assert_equal expected, connect.create_endpoint(connect)
   end
 
+  def test_create_endpoint_with_websocket
+    expected = { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=8000' }
+    connect = Vonage::Voice::Actions::Connect.new(endpoint: { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=8000' })
+
+    assert_equal expected, connect.create_endpoint(connect)
+  end
+
+  def test_create_endpoint_with_websocket_with_audio_rate_8000
+    expected = { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=8000' }
+    connect = Vonage::Voice::Actions::Connect.new(endpoint: { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=8000' })
+
+    assert_equal expected, connect.create_endpoint(connect)
+  end
+
+  def test_create_endpoint_with_websocket_with_audio_rate_16000
+    expected = { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=16000' }
+    connect = Vonage::Voice::Actions::Connect.new(endpoint: { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=16000' })
+
+    assert_equal expected, connect.create_endpoint(connect)
+  end
+
+  def test_create_endpoint_with_websocket_with_audio_rate_24000
+    expected = { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=24000' }
+    connect = Vonage::Voice::Actions::Connect.new(endpoint: { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=24000' })
+
+    assert_equal expected, connect.create_endpoint(connect)
+  end
+
+  def create_endpoint_with_websocket_with_invalid_audio_rate
+    exception = assert_raises { Vonage::Voice::Actions::Connect.new(endpoint: { type: 'websocket', uri: 'wss://example.com/socket', :'content-type' => 'audio/l16;rate=32000' }) }
+    assert_match "Expected 'content-type' parameter to be either 'audio/l16;rate=16000', 'audio/l16;rate=8000', or 'audio/l16;rate=24000'", exception.message
+  end
+
   def test_create_endpoint_with_sip_uri
     expected = { type: 'sip', uri: 'sip:joe@domain.com' }
     connect = Vonage::Voice::Actions::Connect.new(endpoint: { type: 'sip', uri: 'sip:joe@domain.com' })

test/vonage/voice/actions/transfer_test.rb

@@ -0,0 +1,80 @@
+# typed: false
+
+
+class Vonage::Voice::Actions::TransferTest < Vonage::Test
+  def test_transfer_initialize
+    transfer = Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id)
+
+    assert_kind_of Vonage::Voice::Actions::Transfer, transfer
+  end
+
+  def test_create_transfer
+    expected = [{ action: 'transfer', conversation_id: conversation_id }]
+    transfer = Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id)
+
+    assert_equal expected, transfer.create_transfer!(transfer)
+  end
+
+  def test_create_transfer_with_optional_params
+    expected = [{ action: 'transfer', conversation_id: conversation_id, canHear: [conversation_leg_uuid], canSpeak: [conversation_leg_uuid] }]
+    transfer = Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_hear: [conversation_leg_uuid], can_speak: [conversation_leg_uuid])
+
+    assert_equal expected, transfer.create_transfer!(transfer)
+  end
+
+  def test_create_transfer_with_mute_option_set_to_true
+    expected = [{ action: 'transfer', conversation_id: conversation_id, mute: true }]
+    transfer = Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, mute: true)
+
+    assert_equal expected, transfer.create_transfer!(transfer)
+  end
+
+  def test_create_transfer_with_mute_option_set_to_false
+    expected = [{ action: 'transfer', conversation_id: conversation_id, mute: false }]
+    transfer = Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, mute: false)
+
+    assert_equal expected, transfer.create_transfer!(transfer)
+  end
+
+  def test_transfer_with_invalid_conversation_id
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: 123) }
+
+    assert_match "Expected 'conversation_id' parameter to be a string", exception.message
+  end
+
+  def test_transfer_with_invalid_can_hear_type
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_hear: conversation_leg_uuid) }
+
+    assert_match "Expected 'can_hear' parameter to be an array of strings", exception.message
+  end
+
+  def test_transfer_with_invalid_can_hear_contents
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_hear: [123]) }
+
+    assert_match "Expected 'can_hear' parameter to be an array of strings", exception.message
+  end
+
+  def test_transfer_with_invalid_can_speak_type
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_speak: conversation_leg_uuid) }
+
+    assert_match "Expected 'can_speak' parameter to be an array of strings", exception.message
+  end
+
+  def test_transfer_with_invalid_can_speak_contents
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_speak: [123]) }
+
+    assert_match "Expected 'can_speak' parameter to be an array of strings", exception.message
+  end
+
+  def test_transfer_with_invalid_mute_type
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, mute: 'true') }
+
+    assert_match "Expected 'mute' parameter to be a boolean", exception.message
+  end
+
+  def test_transfer_with_invalid_mute_combination
+    exception = assert_raises { Vonage::Voice::Actions::Transfer.new(conversation_id: conversation_id, can_speak: [conversation_leg_uuid], mute: true) }
+
+    assert_match "The 'mute' parameter is not supported if 'can_speak' is also set", exception.message
+  end
+end

test/vonage/voice/actions/wait_test.rb

@@ -0,0 +1,44 @@
+# typed: false
+
+
+class Vonage::Voice::Actions::WaitTest < Vonage::Test
+  def test_wait_initialize
+    wait = Vonage::Voice::Actions::Wait.new
+
+    assert_kind_of Vonage::Voice::Actions::Wait, wait
+  end
+
+  def test_create_wait
+    expected = [{ action: 'wait' }]
+    wait = Vonage::Voice::Actions::Wait.new
+
+    assert_equal expected, wait.create_wait!(wait)
+  end
+
+  def test_create_wait_with_optional_params
+    expected = [{ action: 'wait', timeout: 10 }]
+    wait = Vonage::Voice::Actions::Wait.new(timeout: 10)
+
+    assert_equal expected, wait.create_wait!(wait)
+  end
+
+  def test_create_wait_with_timeout_as_integer
+    expected = [{ action: 'wait', timeout: 10 }]
+    wait = Vonage::Voice::Actions::Wait.new(timeout: 10)
+
+    assert_equal expected, wait.create_wait!(wait)
+  end
+
+  def test_create_wait_with_timeout_as_float
+    expected = [{ action: 'wait', timeout: 10.5 }]
+    wait = Vonage::Voice::Actions::Wait.new(timeout: 10.5)
+
+    assert_equal expected, wait.create_wait!(wait)
+  end
+
+  def test_wait_with_invalid_timeout
+    exception = assert_raises { Vonage::Voice::Actions::Wait.new(timeout: 'invalid') }
+
+    assert_match "Expected 'timeout' parameter to be a number", exception.message
+  end
+end

test/vonage/voice/ncco_test.rb

@@ -60,7 +60,17 @@ def test_ncco_with_invalid_action
     assert_match "NCCO action must be one of the valid options. Please refer to https://developer.nexmo.com/voice/voice-api/ncco-reference#ncco-actions for a complete list.", exception.message
   end
 
-  Vonage::Voice::Ncco::ACTIONS.keys.each do |method_name|
+  [
+    :connect,
+    :conversation,
+    :input,
+    :notify,
+    :record,
+    :stream,
+    :talk,
+    :wait,
+    :transfer
+  ].each do |method_name|
     define_method "test_ncco_#{method_name}_defined_class_method" do
       assert_respond_to ncco, method_name
       refute_respond_to ncco.class, method_name