The FORMAT_PHONE function takes a string representing an E164 formatted phone number and returns a string containing the same phone number formatted in either an international, national, or RFC3966 tel: URI format.
FORMAT_PHONE(phone_number_string, format_string, region) -> formatted_phone_number
- phone_number_string (required, type: string)
- A string containing an E164 formatted phone number.
- format_string (optional, type: string, default: "E164")
- The format to return the phone number in (any of "E164", "INTERNATIONAL", "NATIONAL", "RFC3966").
- This variable is optional, but if a value is given for region, a value must be given for format_string.
- region (optional, type: string, default: the 2-digit country code indicated by phone_number_string)
- String representing the 2-digit country code.
- If phone_number_string is not in proper E164 format and doesn't contain a country code, the region indicated by region will be used to determine the country code. (Note that an E164 country code and a 2-digit country code will not be represented by the same string.) If a value is given for region, a value must be given for format_string.
- formatted_phone_number (type: string)
- String containing the formatted phone number.
When both the format_string and region parameters are omitted, FORMAT_PHONE will return the E164 formatted phone number.
FORMAT_PHONE("+17167762323") -> "+17167762323"
When the phone_number_string parameter does not represent a valid phone number, FORMAT_PHONE will throw an error:
FORMAT_PHONE("not a phone number") -> ERROR
If a phone number has been collected from a user, it may not be in proper E164 format. The string "7167762323" is ambiguous without a country code:
FORMAT_PHONE("7167762323") -> ERROR
However, when the country code is known, it can be provided separately via the variable region. Note that if a value is given for region, a value must be given for format_string:
FORMAT_PHONE("7167762323", "E164", "US") -> "+17167762323"
Providing a value for region will not overrun information given by a country code in a given phone number. The following example takes an Australian phone number in E164 format and outputs the same Australian phone number in E164 format, even though the given value for region indicates that the phone number is from the US region:
FORMAT_PHONE("+610255501234", "E164", "US") -> "+610255501234"
When displaying a phone number to a user, it is common to group the digits of the phone number so that it can more easily be read. The format strings "NATIONAL" will omit the country code of the phone number and group the digits in the phone number according to the conventions for the country. Compare how a U.S. phone number is presented compared to an Australian phone number.
FORMAT_PHONE("+17167762323", "NATIONAL") -> "(716) 776-2323"
FORMAT_PHONE("+610255501234", "NATIONAL") -> "(02) 5550 1234"
The "NATIONAL" format string should only be used it will be obvious to a user which country the phone number belongs to. For example, when displaying a user's own phone number, using national formatting is fine as the user will recognize their own number. However, when displaying an unknown phone number, or when displaying multiple phone numbers from different countries, using the format string "INTERNATIONAL", will be more clear.
FORMAT_PHONE("+17167762323", "INTERNATIONAL") -> "+1 716-776-2323"
FORMAT_PHONE("+610255501234", "INTERNATIONAL") -> "+61 2 5550 1234"
The format string "RFC3966" is needed when communicating with external systems that require the format.
FORMAT_PHONE("+17167762323", "RFC3966") -> "tel:+1-716-776-2323"
FORMAT_PHONE("+610255501234", "RFC3966") -> "tel:+61-2-5550-1234"