FALSEHOODS.md

Falsehoods Programmers Believe About Phone Numbers

... and tips on how to use libphonenumber.

Given how ubiquitous phone numbers are and how long they've been around, it's surprising how many false assumptions programmers continue to make about them.

1. An individual has a phone number

   Some people do not own phones, or do not wish to provide you with their telephone number when asked. Do not require a user to provide a phone number unless it is essential, and whenever possible try to provide a fallback to accommodate these users.

2. You can make a call to any phone number

   Some devices such as EFTPOS terminals, fax machines and mobile internet dongles may not support receiving calls. In addition, some people can not use their phones for phone calls. This may be permanent (such as a hearing disability), temporary (temporary hearing loss) or situational (when the user is in a noisy environment).

   Tip: Make how you use phone numbers apparent to the user and give them the option to set their preference. Ensure that you look up this preference before attempting to communicate with the user.

3. An individual has only one phone number

   Obviously, this isn't necessarily true.

4. A phone number uniquely identifies an individual

   It wasn't even that long ago that mobile phones didn't exist, and it was common for an entire household to share one fixed-line telephone number. In some parts of the world, this is still true, and relatives (or even friends) share a single phone number. Many phone services (especially for businesses) allow multiple inbound calls to or outbound calls from the same phone number.

5. Phone numbers cannot be re-used

   Old phone numbers are recycled and get reassigned to other people.

6. Phone numbers that are valid today will always be valid. Phone numbers of a certain type today (e.g., mobile) will never be reassigned to another type.

   A phone number which connects today may be disconnected tomorrow. A number which is free to call today may cost money to call tomorrow. The phone company may decide to expand the range of available phone numbers by inserting a digit into an existing number.

   Tip: Don’t store properties for a phone number such as validity or type. Check this information again from the library when you need it.

7. Each country calling code corresponds to exactly one country

   The USA, Canada, and several Caribbean islands share the country calling code +1. Russia and Kazakhstan share +7. These are not the only examples!

8. Each country has only one country calling code

   As of this present moment (in Mar. 2016), phones in the disputed territory and partially recognised state of Kosovo may be reached by dialing the country calling code for Serbia (+381), Slovenia (+386), or Monaco (+377), depending on where and when one obtained the number.

   Tip: Use a phone widget to encourage users to enter their phone number in an international format such that it can be unambiguously understood.

9. A phone number is dialable from anywhere

   Some numbers can only be dialed within the country. Some can only be dialled from within a subset of countries, such as the +800 Universal International Freephone Numbers. Some may be dialable only if the caller is a subscriber to a particular telecom company.

10. You can send a text message to any phone number

    A lot of people still only have a fixed-line telephone, which typically cannot send or receive text messages.

    Tip: Whenever possible, try to accommodate these users by calling them with a voice message or voice prompts. Alternatively, if your service requires sending text messages, verify that the number can receive text messages after the user provides it.

11. Only mobile phones can receive text messages

    Some service providers support sending and receiving text messages to fixed-line numbers. There are also online services like Skype that can send and receive text messages.

12. There are only two ways to dial a phone number: domestically and from overseas

    Some numbers may need different prefixes depending on: the carrier you are using; what device you are dialling from/to; whether you are inside or outside a particular geographical region.

    Examples:

    • In Brazil, to dial numbers internally but across a certain geographical boundary, a carrier code must be explicitly dialed to say which carrier you will use to pay for the call.
    • In Nepal, the leading zero in national format is omitted depending on whether the originating phone is mobile or fixed-line.
    • In New Zealand, you need to dial the area-code (e.g. 03) even if the number is within the same area-code region as you are, unless it is "close" (something approximating city/district boundaries), in which case it shouldn’t be dialled.

    Tip: Use formatForMobileDialling to get the number a user should actually dial on their mobile phone.

13. To make a number dialable, you only need to change the prefix

    In Argentina, to dial a mobile number domestically, the digits "15" need to be inserted after the area code but before the local number, and the "9" after the country code (54) needs to be removed. This transforms +54 9 2982 123456 into 02982 15 123456.

14. No prefix of a valid phone number can be a valid phone number

    In some countries, it's possible to connect to a different endpoint by dialing more digits after a number. So "12345678" may not reach the same person as dialing "123456".

15. An invalid number will not reach an endpoint

    In some countries, or on some phones, extra digits are thrown away. Hence, 1-800-MICROSOFT is an invalid number - but it still connects to Microsoft, since any later digits are ignored. Numbers such as "911" can be reached by dialling "911 123" in some countries: but not in others.

    In other countries, invalid numbers may be "fixed" by a carrier, e.g., adding a mobile token if they know it is a mobile number, such that it connects.

16. All valid phone numbers follow the ITU specifications

    ITU-T specifies that a phone number cannot be longer than fifteen digits, with one to three digits reserved for the country calling code, but valid numbers in Germany have been assigned that are longer than this.

17. All valid phone numbers belong to a country

    There are many "country calling codes" issued to non-geographical entities, such as satellite services, and the "800" code for Universal International Freephone Numbers.

18. Phone numbers contain only digits

    In Israel, certain advertising numbers start with a *. In New Zealand, non-urgent traffic incidents can be reported by calling *555 from a mobile phone. Alpha characters may also be used in phone numbers, such as in 1-800-Flowers.

19. Phone numbers are always written in ASCII

    In Egypt, it is common for phone numbers to be written in native digits.

20. Phone numbers have only one prefix (area code or national destination code) at a given time

    In the mid-90s in Iceland, phone numbers changed from 5 and 6 digits to 7 digits. The old system had regional prefixes, but the new one doesn't. During the transition period, phone numbers could be reached by the old area code or the new 7 digit number (a different prefix). For example, a Reykjavik phone number could be dialed with nnnnn and 55nnnnn inside the region, and 91-nnnnn and 55nnnnn from outside.

    Tip: During transition periods, make sure that both forms of a number are supported for look-up by phone number. If sending messages/dialling affected numbers, both the new and old prefix may need to be tried. Depending on the type of transition, you may need to contact affected customers and ask them to update their number.

21. A leading zero in numbers formatted for domestic usage can always be discarded when dialing from abroad

    In some countries, people write the national prefix in brackets (typically (0)) after the country calling code to indicate that it should be discarded when dialing internationally. In Italy, since 1998, the prefix was "fixed" to the phone numbers, so that (01) 2345 became 012345 and should be dialed (internationally) as +39012345 (including the leading zero).

    Tip: Use the library to parse and format numbers to handle this correctly for every country.

22. The country or area code of a phone number indicates the user's location, place of residence, time-zone, or preferred language

    There are many reasons for someone to have a phone number issued in a state or region other than where they reside or hold citizenship.

    These include, but are not limited to:

    • Moving within a country: In countries with phone number portability, you may retain your number when moving, even in some cases if it is a fixed-line number and even if it has an area code (see xkcd for a US example.)
    • Moving to another country: Some people keep their mobile phones when they move to another country.
    • Geopolitical turmoil: Sometimes countries change their borders, cease to exist, or come into existence.
    • Business, family, and friends: A business may have many customers in a neighbouring country, or a person may have many family and friends there.
    • Wanting cheaper rates: VoIP is often cheaper than regular calls. People traveling around Europe may get a SIM card from one country and have a roaming plan.

    Note that geographical area codes are assigned in some countries to mobile phones.

    Tip: Programmers should not disallow users from signing up with a phone number merely because it belongs to another country. Care should be taken when calling methods such as isValidNumberForRegion that this is what's actually intended. If you have a phone input widget, make sure you allow numbers to be entered in international format (i.e., allow the + sign) so people can sign up with an international contact number.

23. The plus sign in front of phone numbers in international format is optional, or can always be replaced by 00

    The plus sign is part of the E.164 format for international telephone numbers. It can be replaced with the international call prefix when dialing internationally. Note that while 00 is a common international call prefix, this actually varies by country.

    In North America, which has a country calling code of +1, it is a common error to drop the + in front of the number and write it like 1-555-123-4567. This is technically incorrect. To call this number from Japan, where the international call prefix is 010, one may dial either +1 555 123 4567 or 010 1 555 123 4567.

24. Users will only store phone numbers in your product's phone number fields

    Some users use their contact lists to store things like birthdays or other information. Unless a piece of user-supplied data has actually been verified to be a phone number, it should be stored as-is as entered by the user.

25. Phone numbers are numbers

    Never try to store phone numbers as an int or any other kind of numeric data type. You can't do arithmetic on them, and while 007, 07 and 7 are the same number they are not necessarily the same phone number - in some countries a leading 0 is significant and forms part of the number itself (see A leading zero in numbers formatted for domestic usage can always be discarded when dialing from abroad). Moreover, a phone number may contain other diallable characters (see Phone numbers contain only digits) or an extension portion, dialled after waiting for a tone.

    Tip: Use the library to parse and format numbers to handle this correctly for every country.

26. Phone numbering plans published by governments or telecoms represent reality

    National numbering plans, such as those administered by the ITU, represent the intentions of the government or telecom. These may be published before, during, or after the actual implementation of numbering plan changes in the real world. The actual date on which a phone number range becomes active may not always adhere to official announcements.