Relationship to profile/getBusiness: The profile/getBusiness operation also returns profilePictureUrl alongside all other profile fields. Use profile/getPhoto when you need only the photo URL and want a lightweight call.
When to Use
- Logo consistency verification: A brand compliance workflow retrieves the profile picture URL for all managed phone numbers and visually flags any accounts where the profile image differs from the approved brand logo.
- Customer portal display: A web portal workflow fetches the current profile picture URL to display the business logo next to live chat widgets powered by WhatsApp.
- Photo change detection: A monitoring workflow retrieves the URL daily and compares it against a stored reference. A change in URL indicates the profile picture was updated, triggering a brand team notification.
- Onboarding readiness check: A tenant onboarding workflow checks whether a profile picture URL is set (non-null). If not, it notifies the tenant that their WhatsApp profile picture is missing and provides setup instructions.
- Cross-channel branding sync: A branding workflow retrieves the WhatsApp profile picture URL and uses it as the source of truth to update the same logo across other communication channels (email headers, support chat widgets).
Configuration
Connection
| Field | Required | Description |
|---|
accessToken | Required | Permanent System User access token from Meta Business Manager. Store in BizFirst Credentials Manager. |
phoneNumberId | Required | Numeric string ID of the WhatsApp Business phone number whose profile photo you want to retrieve. |
apiVersion | Optional | Meta Graph API version, e.g. v18.0. Defaults to v18.0. |
Operation
This operation retrieves the profile_picture_url field from the WhatsApp Business profile. No additional operation fields are required.
| Field | Required | Description |
|---|
| No additional operation fields required. |
Implementation note: This node calls the same endpoint as profile/getBusiness (the whatsapp_business_profile endpoint with profile_picture_url in the fields). The output is a subset of the full business profile response, returning only the picture URL.
Sample Configuration
{
"resource": "profile",
"operation": "getPhoto",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty or missing. |
phoneNumberId is required | The phoneNumberId field is empty or missing. |
100 (Meta) | Phone number ID not found or the token does not have access. |
190 (Meta) | Access token expired or invalid. |
200 (Meta) | Token lacks required permission scope (whatsapp_business_management). |
Output
Success Port
Fires when the profile photo URL is successfully retrieved. The URL may be null if no profile picture has been set for the phone number.
| Field | Type | Description |
|---|
profilePictureUrl | string | Publicly accessible URL of the business profile picture. Null if no profile picture has been set. This is a WhatsApp CDN URL — do not cache it long-term as it can change when the photo is updated. |
status | string | "success" on success. |
errorCode | string | Empty on success. |
errorMessage | string | Empty on success. |
rawResponse | string | Full raw JSON response from Meta. |
Error Port
| Field | Type | Description |
|---|
status | string | "failed" or "error". |
errorCode | string | Meta error code. |
errorMessage | string | Human-readable description of the failure. |
rawResponse | string | Raw API error JSON for diagnostics. |
Sample Output
{
"profilePictureUrl": "https://pps.whatsapp.net/v/t61.29466-19/123456789_456789123_n.jpg?stp=dst-jpg_s96x96...",
"status": "success",
"errorCode": null,
"errorMessage": null,
"rawResponse": "{\"data\":[{\"profile_picture_url\":\"https://pps.whatsapp.net/v/t61.29466-19/...\"}]}"
}
Expression Reference
| Value | Expression | Notes |
|---|
| Profile picture URL | {{ $output.getPhoto.profilePictureUrl }} | Publicly accessible URL. Null if not set. Use in an IfCondition to gate on null before display. |
| Status | {{ $output.getPhoto.status }} | "success" on success. |
| Error code | {{ $output.getPhoto.errorCode }} | Non-null on error port. Code 100 means phone number ID not found. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Null URL handling | The profilePictureUrl is null if the profile picture has never been set. Always check for null before using the URL in downstream nodes. |
| URL stability | The WhatsApp CDN URL changes when the profile picture is updated. Do not store the URL as a permanent reference — always fetch fresh when you need the current photo. |
| Credential storage | Store the access token in BizFirst Credentials Manager. Never paste it into node configuration as plain text. |
| Error port handling | Always connect the error port. A 200 permissions error on this node requires a token scope update in Meta Business Manager. |
| Use getBusiness for full profile | If you need multiple profile fields alongside the photo URL, use profile/getBusiness instead — it returns all profile fields in a single API call. |
Examples
Onboarding Photo Readiness Check
{
"resource": "profile",
"operation": "getPhoto",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $input.phoneNumberId }}"
}
A new tenant onboarding workflow calls this node and checks whether profilePictureUrl is null. If null, it sends an email to the account owner with instructions to upload a profile picture in Meta Business Manager. If a URL is returned, the workflow logs it as the initial profile picture reference and marks the photo step as complete.
Brand Compliance Scan
// Loop node iterates over all managed phone number IDs
{
"resource": "profile",
"operation": "getPhoto",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $loop.currentItem.phoneNumberId }}"
}
A weekly brand compliance workflow retrieves the profile photo URL for all managed accounts. A Function node compares each URL against the stored approved brand logo URL. Accounts with a different or missing photo are collected into a report emailed to the brand team with the phone number, tenant name, and current photo URL for review.
Photo Change Monitoring
{
"resource": "profile",
"operation": "getPhoto",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345"
}
A daily monitoring workflow fetches the photo URL and compares it against the URL stored in the configuration database. If the URL has changed (indicating the profile picture was updated), it creates an audit log entry and sends a Slack notification to the brand team with the old URL, the new URL, and the change detection timestamp.
