nexmo 5.8.0 → 5.9.0

data/lib/nexmo/call_dtmf.rb

@@ -6,6 +6,18 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Play DTMF tones into a call.
+    #
+    # @option params [String] :digits
+    #   The digits to send.
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#startDTMF
+    #
     def send(id, params)
       request('/v1/calls/' + id + '/dtmf', params: params, type: Put)
     end

data/lib/nexmo/call_stream.rb

@@ -6,10 +6,36 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Play an audio file into a call.
+    #
+    # @option params [required, Array<String>] :stream_url
+    #   URL of the audio file.
+    #
+    # @option params [Integer] :loop
+    #   The number of times to play the file, 0 for infinite.
+    #
+    # @option params [String] :level
+    #   Set the audio level of the stream in the range -1 >= level <= 1 with a precision of 0.1. The default value is 0.
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#startStream
+    #
     def start(id, params)
       request('/v1/calls/' + id + '/stream', params: params, type: Put)
     end
 
+    # Stop playing an audio file into a call.
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#stopStream
+    #
     def stop(id)
       request('/v1/calls/' + id + '/stream', type: Delete)
     end

data/lib/nexmo/call_talk.rb

@@ -6,10 +6,40 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Play text to speech into a call.
+    #
+    # @option params [required, String] :text
+    #   The text to read.
+    #
+    # @option params [String] :voice_name
+    #   The voice & language to use.
+    #
+    # @option params [Integer] :loop
+    #   The number of times to repeat the text the file, 0 for infinite.
+    #
+    # @option params [String] :level
+    #   The volume level that the speech is played.
+    #   This can be any value between `-1` to `1` in `0.1` increments, with `0` being the default.
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#startTalk
+    #
     def start(id, params)
       request('/v1/calls/' + id + '/talk', params: params, type: Put)
     end
 
+    # Stop text to speech in a call.
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#stopTalk
+    #
     def stop(id)
       request('/v1/calls/' + id + '/talk', type: Delete)
     end

data/lib/nexmo/calls.rb

@@ -6,54 +6,242 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create an outbound Call.
+    #
+    # @example
+    #   response = client.calls.create({
+    #     to: [{type: 'phone', number: '14843331234'}],
+    #     from: {type: 'phone', number: '14843335555'},
+    #     answer_url: ['https://example.com/answer']
+    #   })
+    #
+    # @option params [required, Array<Hash>] :to
+    #   Connect to a Phone (PSTN) number, SIP Endpoint, Websocket, or VBC extension.
+    #
+    # @option params [required, Hash] :from
+    #   Connect to a Phone (PSTN) number.
+    #
+    # @option params [Array<String>] :ncco
+    #   The Nexmo Call Control Object to use for this call.
+    #   Required unless **:answer_url** is provided.
+    #
+    # @option params [Array<String>] :answer_url
+    #   The webhook endpoint where you provide the Nexmo Call Control Object that governs this call.
+    #   Required unless **:ncco** is provided.
+    #
+    # @option params [String] :answer_method
+    #   The HTTP method used to send event information to answer_url.
+    #
+    # @option params [required, Array<String>] :event_url
+    #   The webhook endpoint where call progress events are sent to.
+    #
+    # @option params [String] :event_method
+    #   The HTTP method used to send event information to event_url.
+    #
+    # @option params [String] :machine_detection
+    #   Configure the behavior when Nexmo detects that the call is answered by voicemail.
+    #
+    # @option params [Integer] :length_timer
+    #   Set the number of seconds that elapse before Nexmo hangs up after the call state changes to in_progress.
+    #
+    # @option params [Integer] :ringing_timer
+    #   Set the number of seconds that elapse before Nexmo hangs up after the call state changes to `ringing`.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#createCall
+    #
     def create(params)
       request('/v1/calls', params: params, type: Post)
     end
 
+    # Get details of your calls.
+    #
+    # @example
+    #   response = client.calls.list
+    #   response._embedded.calls.each do |item|
+    #     puts "#{item.uuid} #{item.direction} #{item.status}"
+    #   end
+    #
+    # @option params [String] :status
+    #   Filter by call status.
+    #
+    # @option params [String] :date_start
+    #   Return the records that occurred after this point in time.
+    #
+    # @option params [String] :date_end
+    #   Return the records that occurred before this point in time.
+    #
+    # @option params [Integer] :page_size
+    #   Return this amount of records in the response.
+    #
+    # @option params [Integer] :record_index
+    #   Return calls from this index in the response.
+    #
+    # @option params [String] :order
+    #   Either `ascending` or `descending` order.
+    #
+    # @option params [String] :conversation_uuid
+    #   Return all the records associated with a specific conversation.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#getCalls
+    #
     def list(params = nil)
       request('/v1/calls', params: params)
     end
 
+    # Get detail of a specific call.
+    #
+    # @example
+    #   response = client.calls.get(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#getCall
+    #
     def get(id)
       request('/v1/calls/' + id)
     end
 
+    # Modify an in progress call.
+    #
+    # @example
+    #   response = client.calls.update(id, action: 'hangup')
+    #
+    # @option params [required, String] :action
+    #
+    # @option params [Hash] :destination
+    #   Required when **:action** is `transfer`.
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def update(id, params)
       request('/v1/calls/' + id, params: params, type: Put)
     end
 
+    # Hangup an in progress call.
+    #
+    # @example
+    #   response = client.calls.hangup(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def hangup(id)
       update(id, action: 'hangup')
     end
 
+    # Mute an in progress call.
+    #
+    # @example
+    #   response = client.calls.mute(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def mute(id)
       update(id, action: 'mute')
     end
 
+    # Unmute an in progress call.
+    #
+    # @example
+    #   response = client.calls.unmute(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def unmute(id)
       update(id, action: 'unmute')
     end
 
+    # Earmuff an in progress call.
+    #
+    # @example
+    #   response = client.calls.earmuff(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def earmuff(id)
       update(id, action: 'earmuff')
     end
 
+    # Unearmuff an in progress call.
+    #
+    # @example
+    #   response = client.calls.unearmuff(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def unearmuff(id)
       update(id, action: 'unearmuff')
     end
 
+    # Transfer an in progress call.
+    #
+    # @example
+    #   destination = {
+    #     type: 'ncco',
+    #     url: ['https://example.com/ncco.json']
+    #   }
+    #
+    #   response = client.calls.transfer(id, destination: destination)
+    #
+    # @param [String] id
+    # @param [Hash] destination
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/voice#updateCall
+    #
     def transfer(id, destination:)
       update(id, action: 'transfer', destination: destination)
     end
 
+    # @return [CallStream]
+    #
     def stream
       @stream ||= CallStream.new(@client)
     end
 
+    # @return [CallTalk]
+    #
     def talk
       @talk ||= CallTalk.new(@client)
     end
 
+    # @return [CallDTMF]
+    #
     def dtmf
       @dtmf ||= CallDTMF.new(@client)
     end

data/lib/nexmo/client.rb

@@ -36,24 +36,40 @@ module Nexmo
       @http_options = HTTP::Options.new(hash)
     end
 
+    # @return [Nexmo::Logger]
+    #
     def logger
       @logger
     end
 
+    # @return [Nexmo::Logger]
+    #
     def logger=(logger)
       @logger = Logger.new(logger)
     end
 
+    # Returns the value of attribute token, or a temporary short lived token.
+    #
+    # @return [String]
+    #
     def token
       @token || JWT.generate({application_id: application_id}, private_key)
     end
 
+    # @deprecated Use {#token=} instead.
+    #
     def auth_token=(auth_token)
       Kernel.warn "#{self.class}##{__method__} is deprecated (use #token= instead)"
 
       @token = auth_token
     end
 
+    # Returns the value of attribute api_key.
+    #
+    # @return [String]
+    #
+    # @raise [AuthenticationError]
+    #
     def api_key
       unless @api_key
         raise AuthenticationError.new('No API key provided. ' \
@@ -64,6 +80,12 @@ module Nexmo
       @api_key
     end
 
+    # Returns the value of attribute api_secret.
+    #
+    # @return [String]
+    #
+    # @raise [AuthenticationError]
+    #
     def api_secret
       unless @api_secret
         raise AuthenticationError.new('No API secret provided. ' \
@@ -74,6 +96,12 @@ module Nexmo
       @api_secret
     end
 
+    # Returns the value of attribute signature_secret.
+    #
+    # @return [String]
+    #
+    # @raise [AuthenticationError]
+    #
     def signature_secret
       unless @signature_secret
         raise AuthenticationError.new('No signature_secret provided. ' \
@@ -85,6 +113,12 @@ module Nexmo
       @signature_secret
     end
 
+    # Returns the value of attribute application_id.
+    #
+    # @return [String]
+    #
+    # @raise [AuthenticationError]
+    #
     def application_id
       unless @application_id
         raise AuthenticationError.new('No application_id provided. ' \
@@ -97,6 +131,12 @@ module Nexmo
       @application_id
     end
 
+    # Returns the value of attribute private_key.
+    #
+    # @return [String]
+    #
+    # @raise [AuthenticationError]
+    #
     def private_key
       unless @private_key
         raise AuthenticationError.new('No private_key provided. ' \
@@ -109,74 +149,110 @@ module Nexmo
       @private_key
     end
 
+    # @return [Signature]
+    #
     def signature
-      @signature ||= Signature.new(self)
+      @signature ||= Signature.new(signature_secret)
     end
 
+    # @return [Account]
+    #
     def account
       @account ||= Account.new(self)
     end
 
+    # @return [Alerts]
+    #
     def alerts
       @alerts ||= Alerts.new(self)
     end
 
+    # @return [Applications]
+    #
     def applications
       @applications ||= Applications.new(self)
     end
 
+    # @return [ApplicationsV2]
+    #
     def applications_v2
       @applications_v2 ||= ApplicationsV2.new(self)
     end
 
+    # @return [Calls]
+    #
     def calls
       @calls ||= Calls.new(self)
     end
 
+    # @return [Conversations]
+    #
     def conversations
       @conversations ||= Conversations.new(self)
     end
 
+    # @return [Conversions]
+    #
     def conversions
       @conversions ||= Conversions.new(self)
     end
 
+    # @return [Files]
+    #
     def files
       @files ||= Files.new(self)
     end
 
+    # @return [Messages]
+    #
     def messages
       @messages ||= Messages.new(self)
     end
 
+    # @return [NumberInsight]
+    #
     def number_insight
       @number_insight ||= NumberInsight.new(self)
     end
 
+    # @return [Numbers]
+    #
     def numbers
       @numbers ||= Numbers.new(self)
     end
 
+    # @return [PricingTypes]
+    #
     def pricing
       @pricing ||= PricingTypes.new(self)
     end
 
+    # @return [Redact]
+    #
     def redact
       @redact ||= Redact.new(self)
     end
 
+    # @return [Secrets]
+    #
     def secrets
       @secrets ||= Secrets.new(self)
     end
 
+    # @return [SMS]
+    #
     def sms
       @sms ||= SMS.new(self)
     end
 
+    # @return [TFA]
+    #
     def tfa
       @tfa ||= TFA.new(self)
     end
 
+    # @return [Verify]
+    #
     def verify
       @verify ||= Verify.new(self)
     end