User phone numbers

This article will discuss different topics around your users’ or customers’ phone numbers.

Phone numbers are shown in the user profile in local formats, but will not be in the format you use to import the number ((724) 123 4567).

Importing phone numbers

You can import phone numbers by uploading a CSV or via API to create a user.

Formatting

It is important to import non-U.S. numbers in E.164 format, including the “+” and country code. Any phone numbers not provided in this format will be interpreted as a US number.

If a phone number is coerced into E.164 format but does not pass validation, Braze will not be able to send WhatsApp messages to this number. Any users with phone numbers that are not formattable will automatically exit from a Canvas step that includes WhatsApp

All U.S. numbers must be valid, 10-digit phone numbers with a valid area code. They can be input without the + and country code, as Braze will assume and map all valid, 10-digit phone numbers as U.S. numbers.

All international numbers should start with a +, followed by their country code and then the phone number. (e.g +442071838750)

However, to ensure accuracy in the event that you are sending to multiple regions with different country or area codes, it is recommended to use the E.164 format, even for U.S.-based phone numbers.

You can see the differences between local number formatting as well as universal, E.164 formatting in the following table:

Country	Local	Country Code	E.164
USA	4155552671	1	+14155552671
UK	02071838750	44	+442071838750
Brazil	1155256325	55	+551155256325

Adding users to WhatsApp a subscription group

For a customer to receive an WhatsApp message, they must have a valid phone number and be opted-in to a subscription group. For more information, refer to WhatsApp subscription groups.

Multiple users with the same phone number

Outbound sends

If multiple users have the same phone number within a segment of a single campaign or Canvas step, Braze deduplicates the sending and sends only one message to that phone number.

Inbound messages

When multiple user profiles share the same phone number, Braze uses the following tiebreak logic to determine which profile receives attribution for an inbound WhatsApp message:

1. If the message is attributed to a campaign, Braze attributes the inbound WhatsApp message to the profile that most recently received that campaign on WhatsApp. If no profile received that campaign on WhatsApp, Braze uses the profile that most recently received that same campaign on another channel (such as email or SMS).
2. Otherwise, Braze attributes the message to the profile that most recently received a campaign from the associated WhatsApp subscription group that sent anything in the last seven days on WhatsApp. If no profile received one of those campaigns on WhatsApp, Braze uses the profile that most recently received one of those same campaigns on another channel.
3. Otherwise, Braze attributes the message to the profile with the phone user alias for the sender’s phone number—the first profile to have sent an inbound WhatsApp message from that number.
4. Otherwise, Braze attributes the message to the first matching profile Braze finds. This choice may not be consistent across inbound WhatsApp messages from the same phone number.

To prevent duplicate profiles from forming when users share phone numbers, use the users/merge endpoint to consolidate user data.