[Summary view] [Print] [Text view]

   1  =================
   2   Phone Numbers
   3  =================
   4  
   5  Purchasing phone numbers is a two step process. 
   6  
   7  Searching For a Number
   8  ----------------------
   9  
  10  First, we need to search for an available phone number. Use the
  11  :php:meth:`Services_Twilio_Rest_AvailablePhoneNumbers::getList` method of the
  12  :php:class:`Services_Twilio_Rest_AvailablePhoneNumbers` list resource.
  13  
  14  .. code-block:: php
  15  
  16      $accountSid = 'AC1234567890abcdef1234567890a';
  17      $authToken = 'abcdef1234567890abcdefabcde9';
  18  
  19      $client = new Services_Twilio($accountSid, $authToken);
  20      $numbers = $client->account->available_phone_numbers->getList('US', 'TollFree');
  21      foreach($numbers->available_phone_numbers as $number) {
  22          echo 'Number: ' + $number->phone_number + "\n";
  23      }
  24      
  25  You can also pass in parameters to search for phone numbers in a certain area
  26  code, or which contain a certain pattern.
  27  
  28  .. code-block:: php
  29  
  30      $accountSid = 'AC1234567890abcdef1234567890a';
  31      $authToken = 'abcdef1234567890abcdefabcde9';
  32  
  33      $client = new Services_Twilio($accountSid, $authToken);
  34  
  35      // Full parameter documentation at http://www.twilio.com/docs/api/rest/available-phone-numbers#local
  36      $params = array('AreaCode' => '925', 'Contains' => 'hi');
  37      $numbers = $client->account->available_phone_numbers->getList('US', 'Local', $params);
  38      foreach($numbers->available_phone_numbers as $number) {
  39          echo 'Number: ' + $number->phone_number + "\n";
  40      }
  41  
  42  You can also use the type subresources to search for a given type.
  43  
  44  Available types include:
  45  - `local`
  46  - `toll_free`
  47  - `mobile`
  48  
  49  .. code-block:: php
  50  
  51      // Local
  52      $numbers = $client->account->available_phone_numbers->local;
  53      foreach($numbers as $number) {
  54          echo 'Number: ' + $number->phone_number + "\n";
  55      }
  56  
  57      // TollFree
  58      $numbers = $client->account->available_phone_numbers->toll_free;
  59      foreach($numbers as $number) {
  60          echo 'Number: ' + $number->phone_number + "\n";
  61      }
  62  
  63      // Mobile
  64      $numbers = $client->account->available_phone_numbers->mobile;
  65      foreach($numbers as $number) {
  66          echo 'Number: ' + $number->phone_number + "\n";
  67      }
  68  
  69  
  70  Buying a Number
  71  ---------------
  72  
  73  Once you have a phone number, purchase it by creating a new
  74  :php:class:`Services_Twilio_Rest_IncomingPhoneNumber` instance.
  75  
  76  .. code-block:: php
  77  
  78      $accountSid = 'AC1234567890abcdef1234567890a';
  79      $authToken = 'abcdef1234567890abcdefabcde9';
  80  
  81      $client = new Services_Twilio($accountSid, $authToken);
  82  
  83      $phoneNumber = '+44XXXYYYZZZZ';
  84      $purchasedNumber = $client->account->incoming_phone_numbers->create(array('PhoneNumber' => $phoneNumber));
  85  
  86      echo $purchasedNumber->sid;
  87      
  88  Tying the two together, you can search for a number, and then purchase it.
  89  
  90  .. code-block:: php
  91  
  92      $accountSid = 'AC1234567890abcdef1234567890a';
  93      $authToken = 'abcdef1234567890abcdefabcde9';
  94  
  95      $client = new Services_Twilio($accountSid, $authToken);
  96  
  97      // Full parameter documentation at http://www.twilio.com/docs/api/rest/available-phone-numbers#local
  98      $params = array('AreaCode' => '800', 'Contains' => 'hi');
  99  
 100      $numbers = $client->account->available_phone_numbers->getList('CA', 'TollFree', $params);
 101      $firstNumber = $numbers->available_phone_numbers[0]->phone_number;
 102      $purchasedNumber = $client->account->incoming_phone_numbers->create(array('PhoneNumber' => $firstNumber));
 103  
 104      echo $purchasedNumber->sid;
 105  
 106  You can also purchase a random number with a given area code (US/Canada only):
 107  
 108  .. code-block:: php
 109  
 110      $accountSid = 'AC1234567890abcdef1234567890a';
 111      $authToken = 'abcdef1234567890abcdefabcde9';
 112  
 113      $client = new Services_Twilio($accountSid, $authToken);
 114      $purchasedNumber = $client->account->incoming_phone_numbers->create(array('AreaCode' => '925'));
 115  
 116      echo $purchasedNumber->sid;
 117  
 118  Retrieving All of a Number's Properties
 119  ---------------------------------------
 120  
 121  If you know the number and you want to retrieve all of the properties of that
 122  number, such as the ``voice_url`` or the ``sms_method``, you can use the
 123  :php:meth:`Services_Twilio_Rest_IncomingPhoneNumbers::getNumber` convenience
 124  function.
 125  
 126  .. code-block:: php
 127  
 128      $accountSid = 'AC1234567890abcdef1234567890a';
 129      $authToken = 'abcdef1234567890abcdefabcde9';
 130  
 131      $client = new Services_Twilio($accountSid, $authToken);
 132  
 133      // Number must be in e.164 format.
 134      $number = $client->account->incoming_phone_numbers->getNumber('+14105551234');
 135      echo $number->voice_url;
 136  
 137  If you know the ``sid`` of a phone number, you can retrieve it using the
 138  ``get()`` function.
 139  
 140  .. code-block:: php
 141  
 142      $accountSid = 'AC1234567890abcdef1234567890a';
 143      $authToken = 'abcdef1234567890abcdefabcde9';
 144  
 145      $client = new Services_Twilio($accountSid, $authToken);
 146  
 147      $number = $client->account->incoming_phone_numbers->get('PN123456');
 148      echo $number->voice_url;
 149  
 150  Updating a Number
 151  -----------------
 152  
 153  You can easily update any of the properties of your
 154  phone number. A full list of parameters is available
 155  in the `Incoming Phone Number REST API Documentation.
 156  <http://www.twilio.com/docs/api/rest/incoming-phone-numbers#instance-post>`_
 157  
 158  .. code-block:: php
 159  
 160      $accountSid = 'AC1234567890abcdef1234567890a';
 161      $authToken = 'abcdef1234567890abcdefabcde9';
 162  
 163      $client = new Services_Twilio($accountSid, $authToken);
 164      $numbers = $client->account->incoming_phone_numbers;
 165      foreach ($numbers as $number) {
 166          $number->update(array('VoiceMethod' => 'POST'));
 167      }
 168  
 169  Deleting a Number
 170  -----------------
 171  
 172  You can delete numbers by specifying the Sid of the phone number you'd like to
 173  delete, from the incoming phone numbers object.
 174  
 175  .. code-block:: php
 176  
 177      $accountSid = 'AC1234567890abcdef1234567890a';
 178      $authToken = 'abcdef1234567890abcdefabcde9';
 179  
 180      $client = new Services_Twilio($accountSid, $authToken);
 181      $numbers = $client->account->incoming_phone_numbers;
 182      foreach($numbers as $number) {
 183          // Delete just the first number, then quit.
 184          $client->account->incoming_phone_numbers->delete($number->sid);
 185          break;
 186      }
 187