WhatsApp Profile API: Photo URL, About and Last Seen After userHash
url is the field people mean by a WhatsApp profile photo. It is not on the registration check. A 200 from check-exist-by-phone can mint a 24-hour userHash; the photo URL, the About line and last-seen live on later objects, and only after you pass that hash β never the phone β into get-avatar, get-about and get-presence.
This guide walks those JSON shapes. It is not another "is this number on WhatsApp" tutorial: three-state isExist lives in how to check if a number is on WhatsApp, and when to pay for the check at all lives in the number lookup budget. Opening this page or copying a snippet does not send a lookup. Running a command does, and it spends credits. Sign in, copy an authorized key from the dashboard, and read it from OPENDATA_API_KEY on the server. Curl examples use the YOUR_API_KEY placeholder. The key travels in the query string, so those URLs do not belong in tickets, screenshots or source control.
The three public fields people actually store
A public WhatsApp profile that teams persist is three records, not one mega-object.
- Photo. From
get-avatar:pictureSet, a temporaryurl, apictureIdthat changes when the person changes the photo, and areasonwhen there is no photo to fetch. - About. From
get-about:about(empty or null when unset or hidden) and the samepictureId. - Last-seen / online. From
get-presence:visible, and only thenonline,lastSeenMsandlastSeenIso.
get-biz-profile is a fourth object for shops (name, verifiedLevel, description, address, email, website, memberSince when isBusiness is true; personal numbers return isBusiness=false). Sparse extras β device name, masked backup email, previous-device name β exist only when the check's hasExtra map listed them. This walk stays on the three public fields people actually store.
You already hold a userHash from a true isExist. Profile operations accept no phone parameter. The number was resolved when the hash was minted. A missing, unknown or expired hash is rejected without a lookup. Reuse one hash across avatar, About, business and presence until it is 24 hours old. The documented check example 15551234567 is a number shape, not a promised account, and it is not an input to these calls.
HTTP status and gateway status sit above every field below. A missing or unauthorized key, a validation error, or a transport failure is HTTP 4xx/5xx or a gateway code other than 200 β there is no WhatsApp profile in that envelope. Replies wrap as {"code", "data"} (sometimes twice); unwrap until you see pictureSet, about or visible. HTTP 200 with gateway code 200 means the call was delivered. pictureSet=false, an empty about, and visible=false are then business answers, not crashes.
Hash in, photo URL out
get-avatar takes only userHash.
# Documented request shape β running it spends credits. USER_HASH is not a live ticket.
curl "https://api.opendata-api.com/api/project/whatsapp/get-avatar?key=YOUR_API_KEY&userHash=USER_HASH"
Read pictureSet first. When it is true, url is a temporary public photo URL. Fetch the bytes immediately and store the bytes (or your own durable copy). Do not persist url as the photo: the link expires. pictureId is the version id. Keep it next to the contact. On the next enrichment, a different pictureId means the photo changed, so download again; the same value means skip the download. get-about reports pictureId too β same id, two places.
When pictureSet is false, reason explains unset or hidden-by-privacy. That is a real answer. Do not retry it as a bad hash, and do not treat it as "not on WhatsApp" β registration was already decided. A hash error is a gateway rejection, not pictureSet=false.
import os
import requests
BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()
def call(operation, timeout=30, **params):
response = requests.get(
f"{BASE}/{operation}",
params={"key": KEY, **params},
timeout=timeout,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"http {response.status_code}")
body = response.json()
# Envelope may wrap more than once as {"code": ..., "data": {...}}
while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
if body.get("code") != 200:
raise RuntimeError(f"gateway {body.get('code')}: {body.get('message')}")
body = body["data"]
return body
def avatar_record(user_hash):
payload = call("get-avatar", userHash=user_hash)
record = {
"picture_set": payload.get("pictureSet"),
"picture_id": payload.get("pictureId"),
"reason": payload.get("reason"),
"photo_bytes": None,
}
if payload.get("pictureSet") is True and payload.get("url"):
image = requests.get(payload["url"], timeout=30)
image.raise_for_status()
record["photo_bytes"] = image.content
return record
The helper does not invent a hit. USER_HASH / user_hash must already be a ticket you minted. Copying this block does not fetch a photo.
About text and last-seen are optional
Teams that require an About line or a last-seen clock throw away most registered numbers. Both fields are public only when the person left them public.
get-about returns exists, about and pictureId. Empty or null about means no status text, or it is hidden β store null, do not retry. exists=false means the number is not registered; you should not be on this operation without a hash from a true check. Reuse pictureId here if you skipped get-avatar and only need a cheap change detector.
curl "https://api.opendata-api.com/api/project/whatsapp/get-about?key=YOUR_API_KEY&userHash=USER_HASH"
get-presence is the slow, privacy-gated optional. If you are not a contact and last-seen / online is not set to everyone, presence is not delivered: visible=false. That cannot be bypassed. Call it only when the signal is worth a wait of up to about 17 seconds, and give the client a long timeout (60 seconds is a working floor). Default enrichment should skip it.
get-biz-profile is optional in the same sense: personal numbers return isBusiness=false and no shop fields. Do not read a masked backup email as a business contact address; that extra is a different object, and only when hasExtra listed it.
def about_record(user_hash):
payload = call("get-about", userHash=user_hash)
about = payload.get("about")
return {
"exists": payload.get("exists"),
"about": about if about else None,
"picture_id": payload.get("pictureId"),
}
Fold photo, About and (only if asked) presence into one contact row keyed by the number you already checked. Do not send the phone again.
Presence is a snapshot, not a live socket
get-presence is one GET. It is not a websocket, not a subscribe, not "notify me when they come online." The payload is whatever was observable at collection time.
When visible is true, read online (currently online or not), lastSeenMs (epoch milliseconds) and lastSeenIso (ISO-8601). Those keys are present only on a visible result. When visible is false, stop. There is no last-seen to parse, and looping the call will not lift the privacy flag.
def presence_snapshot(user_hash):
payload = call("get-presence", timeout=60, userHash=user_hash)
if payload.get("visible") is not True:
return {"visible": False}
return {
"visible": True,
"online": payload.get("online"),
"last_seen_ms": payload.get("lastSeenMs"),
"last_seen_iso": payload.get("lastSeenIso"),
}
A long wall-clock is normal. A timeout with no body is transport, not visible=false. Classify those separately: retry a timeout with backoff; store a delivered hidden result. Polling every few seconds as if this were a live socket burns credits and still cannot bypass privacy.
Operation pages: get-avatar, get-about, get-presence, get-biz-profile. Product: WhatsApp Number Validation. Costs: pricing. Scoring a photo next to other signals is in the lead verification workflow.
Mistakes that empty a CRM: sending phoneNumber to avatar, About or presence; storing the temporary url instead of bytes; treating pictureSet=false, empty about or visible=false as HTTP failures; requiring last-seen; using a 5-second timeout on presence; reading HTTP 200 as "there is a photo"; pasting query-string keys into tickets; calling profile operations on an expired hash or on a number that never minted one; polling presence as a live socket. Treat the payload as personal data, process only numbers you have a lawful basis to use, and follow WhatsApp's terms.