messagebird-rest 1.3.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fef609127e904a092153ab2dc6e80cd6a775b7d0
-  data.tar.gz: c75c619d065f6e551e9d875098d089915da4bcd2
+SHA256:
+  metadata.gz: dd213489a7f5a7e70a7418ab2e3be5c4aa8cedfa61042121edb1c03dddd6d56a
+  data.tar.gz: 9eca63a90298b50cc4d07fb0b7ff6abc7d1ae292155e7f456df18256ae7f64e3
 SHA512:
-  metadata.gz: d5ed9a42b17dfbdfe55a6b8c2a88218b48001edb8764e748b42e5777406f5fe5d8ce9bd60ebf7801461f8211eecd46e481645c9c068ab59c1dd1ead037a5b07c
-  data.tar.gz: 8dcca59dca9154927d34ebb5dfcb4b1104427c8dc50fc9b1de7f969583a5a6d536ca3042bc41df4c7c22fd51216f0ab4fc26212b79c6196aa2e8c47344878035
+  metadata.gz: 373dae967d6e226cccb6f775666369b1cdc07491593cc1f5ed4fb6e7950c887723475360d4b3d04e50f00b609542190980a99ac3c09bbca5974f636791b86755
+  data.tar.gz: 8bc8ca63f00b5b77731ca3082497ea9cf9f8ae4738878e15d49361438adf5aa03baa2a35bc3bebec4e46a5b7c30e42cbc17be109fefee47543e0f3c3ac7410c0

data/README.md

@@ -2,9 +2,11 @@ MessageBird's REST API for Ruby
 ===============================
 This repository contains the open source Ruby client for MessageBird's REST API. Documentation can be found at: https://developers.messagebird.com/
 
+[![Build Status](https://travis-ci.org/messagebird/ruby-rest-api.svg?branch=master)](https://travis-ci.org/messagebird/ruby-rest-api)
+
 Requirements
 ------------
-- [Sign up](https://www.messagebird.com/en/signup) for a free MessageBird account
+- [Sign up](https://dashboard.messagebird.com/app/en/sign-up) for a free MessageBird account
 - Create a new `access_key` in the developers sections
 - MessageBird's API client for Ruby requires Ruby >= 1.9
 
@@ -56,7 +58,7 @@ pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => '
 
 #<MessageBird::Message:0x007f8d5b883520
  @body="Hello World",
- @createdDatetime=2014-07-07 12:20:30 +0200,
+ @created_datetime=2014-07-07 12:20:30 +0200,
  @datacoding="plain",
  @direction="mt",
  @gateway=239,
@@ -66,7 +68,7 @@ pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => '
  @mclass=1,
  @originator="FromMe",
  @recipient=
-  {"totalCount"=>1,
+  {"total_count"=>1,
    "totalSentCount"=>1,
    "totalDeliveredCount"=>0,
    "totalDeliveryFailedCount"=>0,
@@ -76,9 +78,9 @@ pp client.message_create('FromMe', '31612345678', 'Hello World', :reference => '
       @status="sent",
       @statusDatetime=2014-07-07 12:20:30 +0200>]},
  @reference="MyReference",
- @scheduledDatetime=nil,
+ @scheduled_datetime=nil,
  @type="sms",
- @typeDetails={},
+ @type_details={},
  @validity=nil>
 ```
 
@@ -95,7 +97,7 @@ To perform HLR lookups we have created the **hlr_create** method, which takes a
 pp client.hlr_create('31612345678', 'MyReference')
 
 #<MessageBird::HLR:0x007f8d5b8dafc8
- @createdDatetime=2014-07-07 12:20:05 +0200,
+ @created_datetime=2014-07-07 12:20:05 +0200,
  @href="https://rest.messagebird.com/hlr/4933bed0453ba7455031712h16830892",
  @id="4933bed0453ba7455031712h16830892",
  @msisdn=31612345678,
@@ -111,28 +113,28 @@ Similar to the **message_create** and **message** methods, the **hlr_create** me
 client.hlr('4933bed0453ba7455031712h16830892')
 ```
 
-##### OTP (One-Time Password)
-You can send and verify One-Time Passwords through the MessageBird API using the **otp_generate** and **otp_verify** methods.
+##### Verify (One-Time Password)
+You can send and verify One-Time Passwords through the MessageBird API using the **verify_create** and **verify_token** methods.
 
 ```ruby
-# otp_generate requires a recipient as a required parameter, and other optional paramaters
-client.otp_generate(31612345678, {:reference => "YourReference"})
+# verify_create requires a recipient as a required parameter, and other optional paramaters
+client.verify_create(31612345678, {:reference => "YourReference"})
 
-#<MessageBird::OTP:0x007fb3c18c8148
+#<MessageBird::Verify:0x007fb3c18c8148
  @id="080b7f804555213678f14f6o24607735",
  @recipient="31612345678",
  @reference="YourReference",
  @status="sent",
  @href={"message"=>"https://rest.messagebird.com/messages/67d42f004555213679416f0b13254392"},
- @createdDatetime=2015-05-12 16:51:19 +0200,
+ @created_datetime=2015-05-12 16:51:19 +0200,
  @validUntilDatetime=2015-05-12 16:51:49 +0200>
 ```
 
-This sends a token to the recipient, which can be verified with the **otp_verify** method.
+This sends a token to the recipient, which can be verified with the **verify_token** method.
 
 ```ruby
-# otp_verify requires a recipient, a token as required parameters, and other optional paramaters
-client.otp_verify(31612345678, 123456, {:reference => "YourReference"})
+# verify_token requires the id of the verify request and a token as required parameters.
+client.verify_token('080b7f804555213678f14f6o24607735', 123456)
 ```
 
 ##### Voice Message
@@ -145,14 +147,14 @@ pp client.voice_message_create('31612345678', 'Hello World', :reference => 'MyRe
 
 #<MessageBird::VoiceMessage:0x000001030101b8
  @body="Hello World",
- @createdDatetime=2014-07-09 12:17:50 +0200,
+ @created_datetime=2014-07-09 12:17:50 +0200,
  @href=
   "https://rest.messagebird.com/voicemessages/a08e51a0353bd16cea7f298a37405850",
  @id="a08e51a0353bd16cea7f298a37405850",
  @ifMachine="continue",
  @language="en-gb",
  @recipients=
-  {"totalCount"=>1,
+  {"total_count"=>1,
    "totalSentCount"=>1,
    "totalDeliveredCount"=>0,
    "totalDeliveryFailedCount"=>0,
@@ -173,6 +175,54 @@ Similar to regular messaging and HLR lookups, there is a method available to fet
 client.voice_message('a08e51a0353bd16cea7f298a37405850')
 ```
 
+##### Numbers
+There is also a Numbers API that allow you to search for and purchase number subscriptions to use as originator in other services.
+
+```ruby
+pp client.number_search("NL", {:limit=>5})
+
+#<List:0x00007fa405130618
+ @count=5,
+ @items=
+  [#<MessageBird::Number:0x00007fa405130528
+    @country="NL",
+    @features=["voice"],
+    @locality="Rotterdam",
+    @number="31102005108",
+    @region="",
+    @type="unknown">,
+   #<MessageBird::Number:0x00007fa4051303c0
+    @country="NL",
+    @features=["voice"],
+    @locality="Rotterdam",
+    @number="31102005143",
+    @region="",
+    @type="unknown">,
+   #<MessageBird::Number:0x00007fa405130208
+    @country="NL",
+    @features=["voice"],
+    @locality="Rotterdam",
+    @number="31102005145",
+    @region="",
+    @type="unknown">,
+   #<MessageBird::Number:0x00007fa4051300c8
+    @country="NL",
+    @features=["voice"],
+    @locality="Rotterdam",
+    @number="31102005147",
+    @region="",
+    @type="unknown">,
+   #<MessageBird::Number:0x00007fa405131c48
+    @country="NL",
+    @features=["voice"],
+    @locality="Rotterdam",
+    @number="31102005148",
+    @region="",
+    @type="unknown">],
+ @limit=5,
+ @type=MessageBird::Number>
+````
+
 Documentation
 -------------
 Complete documentation, instructions, and examples are available at:

data/lib/messagebird.rb

@@ -1,15 +1,24 @@
-libdir = File.dirname(__FILE__)
-$:.unshift(libdir) unless $:.include?(libdir)
+# frozen_string_literal: true
 
-module MessageBird
-  CLIENT_VERSION = '1.3.2'
-  ENDPOINT       = 'https://rest.messagebird.com'
-end
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
+require 'messagebird/version'
 require 'messagebird/balance'
 require 'messagebird/client'
+require 'messagebird/contact'
 require 'messagebird/error'
+require 'messagebird/group_reference'
 require 'messagebird/hlr'
-require 'messagebird/otp'
+require 'messagebird/http_client'
+require 'messagebird/message_reference'
+require 'messagebird/signed_request'
+require 'messagebird/verify'
 require 'messagebird/message'
 require 'messagebird/voicemessage'
+require 'messagebird/callflow'
+require 'messagebird/voice/call'
+require 'messagebird/voice/call_leg'
+require 'messagebird/voice/call_leg_recording'
+require 'messagebird/voice/transcription'
+require 'messagebird/voice/webhook'

data/lib/messagebird/balance.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'messagebird/base'
 
 module MessageBird

data/lib/messagebird/base.rb

@@ -1,18 +1,23 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'time'
 
 module MessageBird
   class Base
-    def initialize(json)
-      json.each do |k,v|
-        begin
-          send("#{k}=", v)
-        rescue NoMethodError
-          # Silently ignore parameters that are not supported.
-        end
+    # takes each element from the given hash and apply it to ourselves through an assignment method
+    def map_hash_elements_to_self(hash)
+      hash.each do |key, value|
+        method_name = key.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase # convert came case to snake case
+        method_name += '='
+        send(method_name, value) if respond_to?(method_name)
       end
     end
 
+    def initialize(json)
+      map_hash_elements_to_self(json)
+    end
+
     def value_to_time(value)
       value ? Time.parse(value) : nil
     end

data/lib/messagebird/call_flow.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'messagebird/base'
+
+module MessageBird
+  class CallFlow < MessageBird::Base
+    attr_accessor :id, :title, :record, :default
+    attr_reader :steps, :created_at, :updated_at
+
+    def steps=(json)
+      @steps = json.map { |s| MessageBird::CallFlowStep.new(s) }
+    end
+
+    def created_at=(value)
+      @created_at = value_to_time(value)
+    end
+
+    def updated_at=(value)
+      @updated_at = value_to_time(value)
+    end
+  end
+end

data/lib/messagebird/call_flow/step.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'messagebird/base'
+
+module MessageBird
+  class CallFlowStep < MessageBird::Base
+    attr_accessor :id, :action, :options
+  end
+end

data/lib/messagebird/callflow.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'messagebird/base'
+
+module MessageBird
+  class CallFlow < MessageBird::Base
+    attr_accessor :id, :title, :record, :default
+    attr_reader :steps, :created_at, :updated_at
+
+    def initialize(json)
+      params = json.include?('data') ? json['data'].first : json
+      super(params)
+    end
+
+    def steps=(json)
+      @steps = json.map { |c| MessageBird::CallFlowStep.new(c) }
+    end
+
+    def created_at=(value)
+      @created_at = value_to_time(value)
+    end
+
+    def updated_at=(value)
+      @updated_at = value_to_time(value)
+    end
+  end
+
+  class CallFlowList < List
+    attr_accessor :perPage, :currentPage, :pageCount, :totalCount
+    PER_PAGE = 20
+    CURRENT_PAGE = 1
+
+    def data=(value)
+      self.items = value
+    end
+
+    def pagination=(value)
+      value.each do |k, v|
+        send("#{k}=", v)
+      rescue NoMethodError
+        puts 'An error occurred while listing callflows'
+      end
+    end
+  end
+
+  class CallFlowStep < MessageBird::Base
+    attr_accessor :id, :action
+
+    def options=(json)
+      @options = CallFlowStepOption.new(json)
+    end
+  end
+
+  class CallFlowStepOption < MessageBird::Base
+    attr_accessor :destination, :payload, :language, :voice, :repeat,
+                  :media, :length, :maxLength, :timeout, :finishOnKey, :transcribe,
+                  :transcribeLanguage, :record, :url, :ifMachine, :machineTimeout,
+                  :onFinish, :mask
+  end
+end

data/lib/messagebird/client.rb

@@ -1,14 +1,35 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'net/https'
 require 'uri'
 
 require 'messagebird/balance'
+require 'messagebird/contact'
+require 'messagebird/conversation'
+require 'messagebird/conversation_client'
+require 'messagebird/conversation_message'
+require 'messagebird/conversation_webhook'
 require 'messagebird/error'
+require 'messagebird/group'
 require 'messagebird/hlr'
-require 'messagebird/otp'
+require 'messagebird/http_client'
+require 'messagebird/list'
+require 'messagebird/lookup'
 require 'messagebird/message'
+require 'messagebird/number'
+require 'messagebird/number_client'
+require 'messagebird/verify'
+require 'messagebird/voice/client'
+require 'messagebird/voice/list'
+require 'messagebird/voice/webhook'
 require 'messagebird/voicemessage'
-require 'messagebird/lookup'
+require 'messagebird/voice_client'
+require 'messagebird/voice/call'
+require 'messagebird/voice/call_leg'
+require 'messagebird/voice/call_leg_recording'
+require 'messagebird/voice/transcription'
+require 'messagebird/voice/list'
 
 module MessageBird
   class ErrorException < StandardError
@@ -19,49 +40,148 @@ module MessageBird
     end
   end
 
+  class InvalidFeatureException < StandardError
+  end
+
   class Client
-    attr_reader :access_key
+    attr_reader :access_key, :http_client, :conversation_client, :voice_client
 
-    def initialize(access_key = nil)
+    def initialize(access_key = nil, http_client = nil, conversation_client = nil, voice_client = nil)
       @access_key = access_key || ENV['MESSAGEBIRD_ACCESS_KEY']
+      @http_client = http_client || HttpClient.new(@access_key)
+      @conversation_client = conversation_client || ConversationClient.new(@access_key)
+      @number_client = http_client || NumberClient.new(@access_key)
+      @voice_client = voice_client || VoiceClient.new(@access_key)
     end
 
-    def request(method, path, params={})
-      uri = URI.join(ENDPOINT, '/', path)
+    def conversation_request(method, path, params = {})
+      response_body = @conversation_client.request(method, path, params)
+      return if response_body.nil? || response_body.empty?
 
-      # Set up the HTTP object.
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl     = true
+      parse_body(response_body)
+    end
 
-      # Construct the HTTP GET or POST request.
-      request = Net::HTTP::Get.new(uri.request_uri)  if method == :get
-      request = Net::HTTP::Post.new(uri.request_uri) if method == :post
-      request['Accept']        = 'application/json'
-      request['Authorization'] = "AccessKey #{@access_key}"
-      request['User-Agent']    = "MessageBird/ApiClient/#{CLIENT_VERSION} Ruby/#{RUBY_VERSION}"
+    def number_request(method, path, params = {})
+      response_body = @number_client.request(method, path, params)
+      return if response_body.nil? || response_body.empty?
 
-      # If present, add the HTTP POST parameters.
-      request.set_form_data(params) if method == :post && !params.empty?
+      parse_body(response_body)
+    end
 
-      # Execute the request and fetch the response.
-      response = http.request(request)
+    def voice_request(method, path, params = {})
+      response_body = @voice_client.request(method, path, params)
+      return if response_body.nil? || response_body.empty?
 
-      # Parse the HTTP response.
-      case response.code.to_i
-      when 200, 201, 204, 401, 404, 405, 422
-        json = JSON.parse(response.body)
-      else
-        raise Net::HTTPServerError.new response.http_version, 'Unknown response from server', response
-      end
+      parse_body(response_body)
+    end
+
+    def request(method, path, params = {})
+      response_body = @http_client.request(method, path, params)
+      return if response_body.empty?
+
+      parse_body(response_body)
+    end
+
+    def parse_body(body)
+      json = JSON.parse(body)
 
       # If the request returned errors, create Error objects and raise.
-      if json.has_key?('errors')
-        raise ErrorException, json['errors'].map { |e| Error.new(e) }
+      if json.key?('errors')
+        raise(ErrorException, json['errors'].map { |e| Error.new(e) })
       end
 
       json
     end
 
+    ## Conversations
+    # Send a conversation message
+    def send_conversation_message(from, to, params = {})
+      ConversationMessage.new(conversation_request(
+                                :post,
+                                'send',
+                                params.merge(from: from,
+                                             to: to)
+      ))
+    end
+
+    # Start a conversation
+    def start_conversation(to, channel_id, params = {})
+      Conversation.new(conversation_request(
+                         :post,
+                         'conversations/start',
+                         params.merge(to: to,
+                                      channel_id: channel_id)
+      ))
+    end
+
+    def conversation_list(limit = -1, offset = -1)
+      query = '?'
+      if limit != -1
+        query += "limit=#{limit}&"
+      end
+
+      if offset != -1
+        query += "offset=#{offset}"
+      end
+
+      List.new(Conversation, conversation_request(:get, "conversations#{query}"))
+    end
+
+    def conversation(id)
+      Conversation.new(conversation_request(:get, "conversations/#{id}"))
+    end
+
+    def conversation_update(id, status)
+      Conversation.new(conversation_request(:patch, "conversations/#{id}", status: status))
+    end
+
+    def conversation_reply(id, params = {})
+      ConversationMessage.new(conversation_request(:post, "conversations/#{id}/messages", params))
+    end
+
+    def conversation_messages_list(id, limit = -1, offset = -1)
+      query = '?'
+      if limit != -1
+        query += "limit=#{limit}&"
+      end
+
+      if offset != -1
+        query += "offset=#{offset}"
+      end
+
+      List.new(ConversationMessage, conversation_request(:get, "conversations/#{id}/messages#{query}"))
+    end
+
+    def conversation_message(id)
+      ConversationMessage.new(conversation_request(:get, "messages/#{id}"))
+    end
+
+    def conversation_webhook_create(channel_id, url, events = [])
+      ConversationWebhook.new(conversation_request(
+                                :post,
+                                'webhooks',
+                                channel_id: channel_id,
+                                url: url,
+                                events: events
+      ))
+    end
+
+    def conversation_webhooks_list(limit = 0, offset = 0)
+      List.new(ConversationWebhook, conversation_request(:get, "webhooks?limit=#{limit}&offset=#{offset}"))
+    end
+
+    def conversation_webhook_update(id, params = {})
+      ConversationWebhook.new(conversation_request(:patch, "webhooks/#{id}", params))
+    end
+
+    def conversation_webhook(id)
+      ConversationWebhook.new(conversation_request(:get, "webhooks/#{id}"))
+    end
+
+    def conversation_webhook_delete(id)
+      conversation_request(:delete, "webhooks/#{id}")
+    end
+
     # Retrieve your balance.
     def balance
       Balance.new(request(:get, 'balance'))
@@ -69,87 +189,314 @@ module MessageBird
 
     # Retrieve the information of specific HLR.
     def hlr(id)
-      HLR.new(request(:get, "hlr/#{id.to_s}"))
+      HLR.new(request(:get, "hlr/#{id}"))
     end
 
     # Create a new HLR.
     def hlr_create(msisdn, reference)
       HLR.new(request(
-        :post,
-        'hlr',
-        :msisdn    => msisdn,
-        :reference => reference))
+                :post,
+                'hlr',
+                msisdn: msisdn,
+                reference: reference
+      ))
     end
 
-    # Generate a new One-Time-Password message
-    def otp_generate(recipient, params={})
-        OTP.new(request(
-            :post,
-            'otp/generate',
-            params.merge({
-                :recipient => recipient
-            })
-        ))
+    # Retrieve the information of specific Verify.
+    def verify(id)
+      Verify.new(request(:get, "verify/#{id}"))
     end
 
-    # Verify the One-Time-Password
-    def otp_verify(recipient, token, params={})
-        # Set the path to include all the parameters
-        # Blame Sam Wierema for not adhering to REST principles...
-        path = 'otp/verify?' + URI.encode_www_form(params.merge({
-            :recipient => recipient,
-            :token => token
-        }))
+    # Generate a new One-Time-Password message.
+    def verify_create(recipient, params = {})
+      Verify.new(request(
+                   :post,
+                   'verify',
+                   params.merge(recipient: recipient)
+      ))
+    end
+
+    # Verify the One-Time-Password.
+    def verify_token(id, token)
+      Verify.new(request(:get, "verify/#{id}?token=#{token}"))
+    end
 
-        OTP.new(request(:get, path))
+    # Delete a Verify
+    def verify_delete(id)
+      Verify.new(request(:delete, "verify/#{id}"))
     end
 
     # Retrieve the information of specific message.
     def message(id)
-      Message.new(request(:get, "messages/#{id.to_s}"))
+      Message.new(request(:get, "messages/#{id}"))
+    end
+
+    # Retrieve messages with optional paging and status filter.
+    def message_list(filter = {})
+      limit = filter[:limit] || 10
+      offset = filter[:offset] || 0
+      status = filter[:status] || ''
+
+      params = { limit: limit, offset: offset }
+      if status != ''
+        params['status'] = status
+      end
+      query = 'messages?' + URI.encode_www_form(params)
+      List.new(Message, request(:get, query))
     end
 
     # Create a new message.
-    def message_create(originator, recipients, body, params={})
+    def message_create(originator, recipients, body, params = {})
       # Convert an array of recipients to a comma-separated string.
-      recipients = recipients.join(',') if recipients.kind_of?(Array)
+      recipients = recipients.join(',') if recipients.is_a?(Array)
 
       Message.new(request(
-        :post,
-        'messages',
-        params.merge({
-          :originator => originator.to_s,
-          :body       => body.to_s,
-          :recipients => recipients })))
+                    :post,
+                    'messages',
+                    params.merge(originator: originator.to_s,
+                                 body: body.to_s,
+                                 recipients: recipients)
+      ))
     end
 
     # Retrieve the information of a specific voice message.
     def voice_message(id)
-      VoiceMessage.new(request(:get, "voicemessages/#{id.to_s}"))
+      VoiceMessage.new(request(:get, "voicemessages/#{id}"))
     end
 
     # Create a new voice message.
-    def voice_message_create(recipients, body, params={})
+    def voice_message_create(recipients, body, params = {})
       # Convert an array of recipients to a comma-separated string.
-      recipients = recipients.join(',') if recipients.kind_of?(Array)
+      recipients = recipients.join(',') if recipients.is_a?(Array)
 
       VoiceMessage.new(request(
-        :post,
-        'voicemessages',
-        params.merge({ :recipients => recipients, :body => body.to_s })))
+                         :post,
+                         'voicemessages',
+                         params.merge(recipients: recipients, body: body.to_s)
+      ))
+    end
+
+    def voice_webhook_create(url, params = {})
+      Voice::Webhook.new(voice_request(:post, 'webhooks', params.merge(url: url)))
+    end
+
+    def voice_webhooks_list(per_page = VoiceList::PER_PAGE, page = VoiceList::CURRENT_PAGE)
+      Voice::List.new(Voice::Webhook, voice_request(:get, "webhooks?perPage=#{per_page}&page=#{page}"))
+    end
+
+    def voice_webhook_update(id, params = {})
+      Voice::Webhook.new(voice_request(:put, "webhooks/#{id}", params))
+    end
+
+    def voice_webhook(id)
+      Voice::Webhook.new(voice_request(:get, "webhooks/#{id}"))
+    end
+
+    def voice_webhook_delete(id)
+      voice_request(:delete, "webhooks/#{id}")
+    end
+
+    def call_create(source, destination, call_flow = {}, webhook = {}, params = {})
+      params = params.merge(callFlow: call_flow.to_json) unless call_flow.empty?
+      params = params.merge(webhook: webhook.to_json) unless webhook.empty?
+
+      Voice::Call.new(voice_request(:post, 'calls', params.merge(source: source, destination: destination)))
+    end
+
+    def call_list(per_page = Voice::List::PER_PAGE, page = Voice::List::CURRENT_PAGE)
+      Voice::List.new(Voice::Call, voice_request(:get, "calls?perPage=#{per_page}&currentPage=#{page}"))
+    end
+
+    def call_view(id)
+      Voice::Call.new(voice_request(:get, "calls/#{id}"))
+    end
+
+    def call_delete(id)
+      voice_request(:delete, "calls/#{id}")
+    end
+
+    def call_leg_list(call_id, per_page = Voice::List::PER_PAGE, current_page = Voice::List::CURRENT_PAGE)
+      Voice::List.new(Voice::CallLeg, voice_request(:get, "calls/#{call_id}/legs?perPage=#{per_page}&currentPage=#{current_page}"))
+    end
+
+    def call_leg_recording_view(call_id, leg_id, recording_id)
+      Voice::CallLegRecording.new(voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}"))
+    end
+
+    def call_leg_recording_list(call_id, leg_id)
+      Voice::List.new(Voice::CallLegRecording, voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings"))
+    end
+
+    def call_leg_recording_delete(call_id, leg_id, recording_id)
+      voice_request(:delete, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}")
+    end
+
+    def call_leg_recording_download(recording_uri, &block)
+      @voice_client.request_block(:get, recording_uri, {}, &block)
+    end
+
+    def voice_transcription_create(call_id, leg_id, recording_id, params = {})
+      Voice::Transcription.new(voice_request(:post, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions", params))
+    end
+
+    def voice_transcriptions_list(call_id, leg_id, recording_id)
+      Voice::List.new(Voice::Transcription, voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions"))
+    end
+
+    def voice_transcription_download(call_id, leg_id, recording_id, transcription_id, &block)
+      @voice_client.request_block(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions/#{transcription_id}.txt", {}, &block)
+    end
+
+    def voice_transcription_view(call_id, leg_id, recording_id, transcription_id)
+      Voice::Transcription.new(voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions/#{transcription_id}"))
+    end
+
+    def lookup(phone_number, params = {})
+      Lookup.new(request(:get, "lookup/#{phone_number}", params))
+    end
+
+    def lookup_hlr_create(phone_number, params = {})
+      HLR.new(request(:post, "lookup/#{phone_number}/hlr", params))
+    end
+
+    def lookup_hlr(phone_number, params = {})
+      HLR.new(request(:get, "lookup/#{phone_number}/hlr", params))
+    end
+
+    def contact_create(phone_number, params = {})
+      Contact.new(request(
+                    :post,
+                    'contacts',
+                    params.merge(msisdn: phone_number.to_s)
+      ))
+    end
+
+    def contact(id)
+      Contact.new(request(:get, "contacts/#{id}"))
+    end
+
+    def contact_delete(id)
+      request(:delete, "contacts/#{id}")
+    end
+
+    def contact_update(id, params = {})
+      request(:patch, "contacts/#{id}", params)
+    end
+
+    def contact_list(limit = 0, offset = 0)
+      List.new(Contact, request(:get, "contacts?limit=#{limit}&offset=#{offset}"))
+    end
+
+    def group(id)
+      Group.new(request(:get, "groups/#{id}"))
+    end
+
+    def group_create(name)
+      Group.new(request(:post, 'groups', name: name))
+    end
+
+    def group_delete(id)
+      request(:delete, "groups/#{id}")
+    end
+
+    def group_list(limit = 0, offset = 0)
+      List.new(Group, request(:get, "groups?limit=#{limit}&offset=#{offset}"))
+    end
+
+    def group_update(id, name)
+      request(:patch, "groups/#{id}", name: name)
+    end
+
+    def group_add_contacts(group_id, contact_ids)
+      # We expect an array, but we can handle a string ID as well...
+      contact_ids = [contact_ids] if contact_ids.is_a? String
+
+      query = add_contacts_query(contact_ids)
+
+      request(:get, "groups/#{group_id}?#{query}")
+    end
+
+    def group_delete_contact(group_id, contact_id)
+      request(:delete, "groups/#{group_id}/contacts/#{contact_id}")
+    end
+
+    ## Numbers API
+    # Search for available numbers
+    def number_search(country_code, params = {})
+      List.new(Number, number_request(:get, add_querystring("available-phone-numbers/#{country_code}", params), params))
+    end
+
+    # Purchase an avaiable number
+    def number_purchase(number, country_code, billing_interval_months)
+      params = {
+        number: number,
+        countryCode: country_code,
+        billingIntervalMonths: billing_interval_months
+      }
+      Number.new(number_request(:post, 'phone-numbers', params))
+    end
+
+    # Fetch all purchaed numbers' details
+    def number_fetch_all(params = {})
+      List.new(Number, number_request(:get, add_querystring('phone-numbers', params), params))
+    end
+
+    # Fetch specific purchased number's details
+    def number_fetch(number)
+      Number.new(number_request(:get, "phone-numbers/#{number}"))
+    end
+
+    # Update a number
+    def number_update(number, tags)
+      tags = [tags] if tags.is_a? String
+      Number.new(number_request(:patch, "phone-numbers/#{number}", tags: tags))
+    end
+
+    # Cancel a number
+    def number_cancel(number)
+      number_request(:delete, "phone-numbers/#{number}")
     end
 
-    def lookup(phoneNumber, params={})
-      Lookup.new(request(:get, "lookup/#{phoneNumber}", params))
-    end 
+    def call_flow_create(title, steps, default, record, params = {})
+      params = params.merge(
+        title: title,
+        steps: steps,
+        default: default,
+        record: record
+      )
+      CallFlow.new(voice_request(:post, 'call-flows', params))
+    end
+
+    def call_flow_view(id)
+      CallFlow.new(voice_request(:get, "call-flows/#{id}"))
+    end
 
-    def lookup_hlr_create(phoneNumber, params={})
-      HLR.new(request(:post, "lookup/#{phoneNumber}/hlr", params))
+    def call_flow_list(per_page = CallFlowList::PER_PAGE, page = CallFlowList::CURRENT_PAGE)
+      CallFlowList.new(CallFlow, voice_request(:get, "call-flows?perPage=#{per_page}&page=#{page}"))
     end
 
-    def lookup_hlr(phoneNumber, params={})
-      HLR.new(request(:get, "lookup/#{phoneNumber}/hlr", params))
+    def call_flow_delete(id)
+      voice_request(:delete, "call-flows/#{id}")
     end
 
+    private # Applies to every method below this line
+
+    # Applies to every method below this line
+    def add_contacts_query(contact_ids)
+      # add_contacts_query gets a query string to add contacts to a group.
+      # We're using the alternative "/foo?_method=PUT&key=value" format to send
+      # the contact IDs as GET params. Sending these in the request body would
+      # require a painful workaround, as the client sends request bodies as
+      # JSON by default. See also:
+      # https://developers.messagebird.com/docs/alternatives.
+
+      '_method=PUT&' + contact_ids.map { |id| "ids[]=#{id}" }.join('&')
+    end
+
+    def add_querystring(path, params)
+      return path if params.empty?
+
+      "#{path}?" + params.collect { |k, v| v.is_a?(Array) ? v.collect { |sv| "#{k}=#{sv}" }.join('&') : "#{k}=#{v}" }.join('&')
+    end
   end
 end