The display name is the name people see at the top of a chat with your business number. Changing it looks like editing a field and behaves like submitting an application, which is where most of the confusion comes from.
How do I request the change?
Send the new name on the number's profile, with display_name on PATCH /v1/whatsapp/numbers/{number_id}/profile.
That is the whole mechanism. What happens next is the part worth knowing:
- The change is not immediate. The name you asked for comes back as
new_display_name, and its progress asnew_display_name_status, whiledisplay_namekeeps returning the current name until the change completes. - A requested change cannot be withdrawn. Sending a second name is not a correction and does not cancel the first, so the time to check the spelling is before the request rather than after it.
- Sending the name the number already has does nothing, and that is a guard rather than a courtesy: re-sending the current name would spend a rename and cancel a review a human had started. It is also why the 75-character limit is measured before trimming, so a name differing only in whitespace is not treated as a new one.
A few input rules save a round trip. The name is at most 75 characters, measured on the value you send rather than after trimming, leading and trailing spaces are removed, and a name that is empty or only spaces is refused as a validation error rather than passed on.
Why does the old name still show?
Because that is what the two fields are for, and it is the correct behaviour rather than a lag.
A rename would otherwise have to either blank the name during review or show an unapproved one to customers. Instead the current name keeps working while the requested one is reviewed separately, which is why the profile carries both at once. Read them as a pair: display_name with display_name_status is what people see, and new_display_name with new_display_name_status is what you asked for. new_display_name is simply absent when no change is pending.
The status values are WhatsApp's own review states: approved, pending_review, declined, expired, non_exists, and two that are easy to misread. available_without_review means the name met WhatsApp's criteria for immediate use and skipped review entirely, so it is a success rather than a pending state. none means no display name has been submitted yet. The set is open, and WhatsApp adds states over time, so accept a value you do not recognise rather than treating the response as invalid.
Why was my new name declined?
Because WhatsApp reviewed it against its own display-name guidelines and refused it. Bird passes the name through and does not adjudicate it: a name that breaks those guidelines is refused by WhatsApp itself.
Meta triggers that review on its own schedule as well as on your request. Its documentation states that "When you reach a higher messaging limit, your business phone number's display name automatically undergoes verification based on the display name guidelines", so a name that has been fine for months can be reviewed because your volume grew rather than because you touched it.
When the review finishes, Meta reports the outcome and the decision vocabulary has four values rather than two: approved, rejected, pending, and deferred, which means a decision has been put off rather than made. The guidelines themselves are Meta's and change from time to time; their display names documentation is the current statement of them.
If a name is declined, the next step is to edit it against the guidelines and request again, or to appeal Meta's decision. There is no Bird-side override.
What else should I know before renaming?
Two things that are easy to discover at the wrong moment.
The profile is read live. Bird reads the business profile from WhatsApp on each request rather than serving a stored copy, so what you get is always current, and a WhatsApp outage makes the profile briefly unavailable rather than stale. Code that reads the profile should treat unavailability as a transient condition, not as a missing name.
Not every number can be renamed this way, and the two cases are worth knowing before you build against the profile. A Bird-managed number is readable but not writable, so a profile write on one is refused as not yours. And a number of your own that has not finished connecting is neither readable nor writable, as is a number that does not exist at WhatsApp yet, both refused as unsupported rather than as missing.
WhatsApp phone numbers covers connecting and managing a number, and the profile operation's reference carries the remaining fields you can change alongside the name.