1# Falsehoods Programmers Believe About Phone Numbers 2 3... and tips on how to use libphonenumber. 4 5Given how ubiquitous phone numbers are and how long they've been around, it's 6surprising how many false assumptions programmers continue to make about them. 7 81. **An individual has a phone number** 9 10 Some people do not own phones, or do not wish to provide you with their 11 telephone number when asked. Do not require a user to provide a phone number 12 unless it is essential, and whenever possible try to provide a fallback 13 to accommodate these users. 14 151. **You can make a call to any phone number** 16 17 Some devices such as EFTPOS terminals, fax machines and mobile internet 18 dongles may not support receiving calls. In addition, some people can not 19 use their phones for phone calls. This may be permanent (such as a hearing 20 disability), temporary (temporary hearing loss) or situational (when the 21 user is in a noisy environment). 22 23 **Tip:** Make how you use phone numbers apparent to the user and give them 24 the option to set their preference. Ensure that you look up this preference 25 before attempting to communicate with the user. 26 271. **An individual has only one phone number** 28 29 Obviously, this isn't necessarily true. 30 311. **A phone number uniquely identifies an individual** 32 33 It wasn't even that long ago that mobile phones didn't exist, and it was 34 common for an entire household to share one fixed-line telephone number. In 35 some parts of the world, this is still true, and relatives (or even friends) 36 share a single phone number. Many phone services (especially for businesses) 37 allow multiple inbound calls to or outbound calls from the same phone 38 number. 39 401. **Phone numbers cannot be re-used** 41 42 Old phone numbers are recycled and get reassigned to other people. 43 441. **Phone numbers that are valid today will always be valid. Phone numbers of 45 a certain type today (e.g., mobile) will never be reassigned to another 46 type.** 47 48 A phone number which connects today may be disconnected tomorrow. A number 49 which is free to call today may cost money to call tomorrow. The phone 50 company may decide to expand the range of available phone numbers by 51 inserting a digit into an existing number. 52 53 **Tip:** Don’t store properties for a phone number such as validity or 54 type. Check this information again from the library when you need it. 55 561. **Each country calling code corresponds to exactly one country** 57 58 The USA, Canada, and several Caribbean islands share the country calling 59 code +1. Russia and Kazakhstan share +7. These are not the only examples! 60 611. **Each country has only one country calling code** 62 63 As of this present moment (in Mar. 2016), phones in the disputed territory 64 and partially recognised state of Kosovo may be reached by dialing the 65 country calling code for Serbia (+381), Slovenia (+386), or Monaco (+377), 66 depending on where and when one obtained the number. 67 68 **Tip:** Use a phone widget to encourage users to enter their phone number 69 in an international format such that it can be unambiguously understood. 70 711. **A phone number is dialable from anywhere** 72 73 Some numbers can only be dialed within the country. Some can only be dialled 74 from within a subset of countries, such as the +800 [Universal 75 International Freephone Numbers](https://en.wikipedia.org/wiki/Toll-free_telephone_number#Universal_International_Freephone_Service). 76 Some may be dialable only if the caller is a subscriber to a particular 77 telecom company. 78 791. **You can send a text message to any phone number** 80 81 A lot of people still only have a fixed-line telephone, which typically cannot 82 send or receive text messages. 83 84 **Tip:** Whenever possible, try to accommodate these users by calling them 85 with a voice message or voice prompts. Alternatively, if your service 86 requires sending text messages, verify that the number can receive text 87 messages after the user provides it. 88 891. **Only mobile phones can receive text messages** 90 91 Some service providers support sending and receiving text messages to fixed-line 92 numbers. There are also online services like Skype that can send and receive 93 text messages. 94 951. **There are only two ways to dial a phone number: domestically and from 96 overseas** 97 98 Some numbers may need different prefixes depending on: the carrier you are 99 using; what device you are dialling from/to; whether you are inside or 100 outside a particular geographical region. 101 102 Examples: 103 * In Brazil, to dial numbers internally but across a certain geographical 104 boundary, a carrier code must be explicitly dialed to say which carrier 105 you will use to pay for the call. 106 * In Nepal, the leading zero in national format is omitted depending on 107 whether the originating phone is mobile or fixed-line. 108 * In New Zealand, you need to dial the area-code (e.g. 03) even if the 109 number is within the same area-code region as you are, unless it is 110 "close" (something approximating city/district boundaries), in which 111 case it shouldn’t be dialled. 112 113 **Tip:** Use formatForMobileDialling to get the number a user should 114 actually dial on their mobile phone. 115 1161. **To make a number dialable, you only need to change the prefix** 117 118 In Argentina, to dial a mobile number domestically, the digits "15" need to 119 be inserted *after* the area code but *before* the local number, and the "9" 120 after the country code (54) needs to be removed. This transforms +54 9 2982 121 123456 into 02982 15 123456. 122 1231. **No prefix of a valid phone number can be a valid phone number** 124 125 In some countries, it's possible to connect to a different endpoint by 126 dialing more digits after a number. So "12345678" may not reach the same 127 person as dialing "123456". 128 1291. **An invalid number will not reach an endpoint** 130 131 In some countries, or on some phones, extra digits are thrown away. Hence, 132 1-800-MICROSOFT is an invalid number - but it still connects to Microsoft, 133 since any later digits are ignored. Numbers such as "911" can be reached by 134 dialling "911 123" in some countries: but not in others. 135 136 In other countries, invalid numbers may be "fixed" by a carrier, e.g., 137 adding a mobile token if they know it is a mobile number, such that it 138 connects. 139 1401. **All valid phone numbers follow the ITU specifications** 141 142 ITU-T specifies that a phone number cannot be longer than fifteen digits, 143 with one to three digits reserved for the country calling code, but valid 144 numbers in Germany have been assigned that are longer than this. 145 1461. **All valid phone numbers belong to a country** 147 148 There are many "country calling codes" issued to non-geographical entities, 149 such as satellite services, and the "800" code for [Universal International 150 Freephone Numbers](https://en.wikipedia.org/wiki/Toll-free_telephone_number#Universal_International_Freephone_Service). 151 1521. **Phone numbers contain only digits** 153 154 In Israel, certain advertising numbers start with a `*`. In New Zealand, 155 non-urgent traffic incidents can be reported by calling `*555` from a mobile 156 phone. Alpha characters may also be used in phone numbers, such as in 157 `1-800-Flowers`. 158 1591. **Phone numbers are always written in ASCII** 160 161 In Egypt, it is common for phone numbers to be written in native digits. 162 1631. **Phone numbers have only one prefix (area code or national destination 164 code) at a given time** 165 166 In the mid-90s in Iceland, phone numbers changed from 5 and 6 digits to 7 167 digits. The old system had regional prefixes, but the new one doesn't. 168 During the transition period, phone numbers could be reached by the old area 169 code or the new 7 digit number (a different prefix). For example, a 170 Reykjavik phone number could be dialed with `nnnnn` and `55nnnnn` inside the 171 region, and `91-nnnnn` and `55nnnnn` from outside. 172 173 **Tip:** During transition periods, make sure that both forms of a number 174 are supported for look-up by phone number. If sending messages/dialling 175 affected numbers, both the new and old prefix may need to be tried. 176 Depending on the type of transition, you may need to contact affected 177 customers and ask them to update their number. 178 1791. **A leading zero in numbers formatted for domestic usage can always be 180 discarded when dialing from abroad** 181 182 In some countries, people write the national prefix in brackets (typically 183 `(0)`) after the country calling code to indicate that it should be 184 discarded when dialing internationally. In Italy, since 1998, the prefix was 185 "fixed" to the phone numbers, so that `(01) 2345` became `012345` and should 186 be dialed (internationally) as `+39012345` (including the leading zero). 187 188 **Tip:** Use the library to parse and format numbers to handle this 189 correctly for every country. 190 1911. **The country or area code of a phone number indicates the user's location, 192 place of residence, time-zone, or preferred language** 193 194 There are many reasons for someone to have a phone number issued in a state 195 or region other than where they reside or hold citizenship. 196 197 These include, but are not limited to: 198 * *Moving within a country*: In countries with phone number portability, 199 you may retain your number when moving, even in some cases if it is a 200 fixed-line number and even if it has an area code (see 201 *[xkcd](https://xkcd.com/1129/)* for a US example.) 202 * *Moving to another country*: Some people keep their mobile phones when 203 they move to another country. 204 * *Geopolitical turmoil*: Sometimes countries change their borders, cease 205 to exist, or come into existence. 206 * *Business, family, and friends*: A business may have many customers in a 207 neighbouring country, or a person may have many family and friends 208 there. 209 * *Wanting cheaper rates*: VoIP is often cheaper than regular calls. 210 People traveling around Europe may get a SIM card from one country and 211 have a roaming plan. 212 213 Note that geographical area codes are assigned in some countries to mobile phones. 214 215 **Tip:** Programmers should not disallow users from signing up with a phone 216 number merely because it belongs to another country. Care should be taken 217 when calling methods such as `isValidNumberForRegion` that this is what's 218 actually intended. If you have a phone input widget, make sure you allow 219 numbers to be entered in international format (i.e., allow the `+` sign) so 220 people can sign up with an international contact number. 221 2221. **The plus sign in front of phone numbers in international format is 223 optional, or can always be replaced by `00`** 224 225 The plus sign is part of the [E.164 226 format](https://en.wikipedia.org/wiki/E.164) for international telephone 227 numbers. It can be replaced with the [international call 228 prefix](https://en.wikipedia.org/wiki/List_of_international_call_prefixes) 229 when dialing internationally. Note that while `00` is a common international 230 call prefix, this actually varies by country. 231 232 In North America, which has a country calling code of `+1`, it is a common 233 error to drop the `+` in front of the number and write it like 234 `1-555-123-4567`. This is technically incorrect. To call this number from 235 Japan, where the international call prefix is `010`, one may dial either `+1 236 555 123 4567` or `010 1 555 123 4567`. 237 2381. **Users will only store phone numbers in your product's phone number fields** 239 240 Some users use their contact lists to store things like birthdays or other 241 information. Unless a piece of user-supplied data has actually been verified 242 to be a phone number, it should be stored as-is as entered by the user. 243 2441. **Phone numbers are numbers** 245 246 Never try to store phone numbers as an int or any other kind of numeric 247 data type. You can't do arithmetic on them, and while 007, 07 and 7 are the 248 same number they are not necessarily the same phone number - in some 249 countries a leading 0 is significant and forms part of the number itself 250 (see *A leading zero in numbers formatted for domestic usage can always be 251 discarded when dialing from abroad*). Moreover, a phone number may contain 252 other diallable characters (see *Phone numbers contain only digits*) or an 253 extension portion, dialled after waiting for a tone. 254 255 **Tip:** Use the library to parse and format numbers to handle this 256 correctly for every country. 257 2581. **Phone numbering plans published by governments or telecoms represent 259 reality** 260 261 National numbering plans, such as those administered by the 262 [ITU](http://www.itu.int/oth/T0202.aspx?parent=T0202), represent the 263 intentions of the government or telecom. These may be published before, 264 during, or after the actual implementation of numbering plan changes in the 265 real world. The actual date on which a phone number range becomes active may 266 not always adhere to official announcements. 267