=================
Phone Numbers
=================
Purchasing phone numbers is a two step process.
Searching For a Number
----------------------
First, we need to search for an available phone number. Use the
:php:meth:`Services_Twilio_Rest_AvailablePhoneNumbers::getList` method of the
:php:class:`Services_Twilio_Rest_AvailablePhoneNumbers` list resource.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$numbers = $client->account->available_phone_numbers->getList('US', 'TollFree');
foreach($numbers->available_phone_numbers as $number) {
echo 'Number: ' + $number->phone_number + "\n";
}
You can also pass in parameters to search for phone numbers in a certain area
code, or which contain a certain pattern.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
// Full parameter documentation at http://www.twilio.com/docs/api/rest/available-phone-numbers#local
$params = array('AreaCode' => '925', 'Contains' => 'hi');
$numbers = $client->account->available_phone_numbers->getList('US', 'Local', $params);
foreach($numbers->available_phone_numbers as $number) {
echo 'Number: ' + $number->phone_number + "\n";
}
You can also use the type subresources to search for a given type.
Available types include:
- `local`
- `toll_free`
- `mobile`
.. code-block:: php
// Local
$numbers = $client->account->available_phone_numbers->local;
foreach($numbers as $number) {
echo 'Number: ' + $number->phone_number + "\n";
}
// TollFree
$numbers = $client->account->available_phone_numbers->toll_free;
foreach($numbers as $number) {
echo 'Number: ' + $number->phone_number + "\n";
}
// Mobile
$numbers = $client->account->available_phone_numbers->mobile;
foreach($numbers as $number) {
echo 'Number: ' + $number->phone_number + "\n";
}
Buying a Number
---------------
Once you have a phone number, purchase it by creating a new
:php:class:`Services_Twilio_Rest_IncomingPhoneNumber` instance.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$phoneNumber = '+44XXXYYYZZZZ';
$purchasedNumber = $client->account->incoming_phone_numbers->create(array('PhoneNumber' => $phoneNumber));
echo $purchasedNumber->sid;
Tying the two together, you can search for a number, and then purchase it.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
// Full parameter documentation at http://www.twilio.com/docs/api/rest/available-phone-numbers#local
$params = array('AreaCode' => '800', 'Contains' => 'hi');
$numbers = $client->account->available_phone_numbers->getList('CA', 'TollFree', $params);
$firstNumber = $numbers->available_phone_numbers[0]->phone_number;
$purchasedNumber = $client->account->incoming_phone_numbers->create(array('PhoneNumber' => $firstNumber));
echo $purchasedNumber->sid;
You can also purchase a random number with a given area code (US/Canada only):
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$purchasedNumber = $client->account->incoming_phone_numbers->create(array('AreaCode' => '925'));
echo $purchasedNumber->sid;
Retrieving All of a Number's Properties
---------------------------------------
If you know the number and you want to retrieve all of the properties of that
number, such as the ``voice_url`` or the ``sms_method``, you can use the
:php:meth:`Services_Twilio_Rest_IncomingPhoneNumbers::getNumber` convenience
function.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
// Number must be in e.164 format.
$number = $client->account->incoming_phone_numbers->getNumber('+14105551234');
echo $number->voice_url;
If you know the ``sid`` of a phone number, you can retrieve it using the
``get()`` function.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$number = $client->account->incoming_phone_numbers->get('PN123456');
echo $number->voice_url;
Updating a Number
-----------------
You can easily update any of the properties of your
phone number. A full list of parameters is available
in the `Incoming Phone Number REST API Documentation.
`_
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$numbers = $client->account->incoming_phone_numbers;
foreach ($numbers as $number) {
$number->update(array('VoiceMethod' => 'POST'));
}
Deleting a Number
-----------------
You can delete numbers by specifying the Sid of the phone number you'd like to
delete, from the incoming phone numbers object.
.. code-block:: php
$accountSid = 'AC1234567890abcdef1234567890a';
$authToken = 'abcdef1234567890abcdefabcde9';
$client = new Services_Twilio($accountSid, $authToken);
$numbers = $client->account->incoming_phone_numbers;
foreach($numbers as $number) {
// Delete just the first number, then quit.
$client->account->incoming_phone_numbers->delete($number->sid);
break;
}