Pular para o conteúdo principal
GET
Foto de Perfil do Destinatário

Introdução

Este endpoint serve a foto de perfil de um número do WhatsApp a partir de uma URL estável. É a URL retornada no campo profile_picture da Verificação de Número (Sem Instância) e da sua versão em lote: ela não expira como uma URL assinada de storage, então pode ser armazenada e reutilizada — a cada acesso, a API resolve a foto mais recente disponível.
Endpoint público. No momento, este endpoint pode ser usado sem autenticação. Por ser público, as requisições sem token ficam sujeitas a limites de uso gratuito, mais restritos e que podem mudar a qualquer momento. Com o token da sua conta, valem os limites da sua conta. Ao ultrapassar o limite, a resposta é 429 com o código rate_limited e o header Retry-After indica quando tentar de novo.

Como funciona

Por padrão, a resposta é um redirecionamento 302 para uma URL assinada temporária da imagem (validade de 10 minutos). Isso significa que a URL funciona diretamente onde um navegador resolve redirecionamentos por conta própria:
Se preferir receber a URL da imagem em JSON — por exemplo, para baixar a foto num backend — informe ?mode=json:
No modo JSON a URL assinada tem a mesma validade do redirecionamento (10 minutos) — consulte expires_at para o momento exato e solicite uma nova URL quando expirar. Qualquer outro valor de mode é tratado como o padrão (redirecionamento). Quando o número não tem foto disponível, o modo JSON responde { "url": null }.

Sem foto: placeholder

Este endpoint funciona de forma independente: não é preciso consultar o número antes nos endpoints de verificação. Um número que existe no WhatsApp mas está sem foto disponível (foto privada ou nenhuma foto atribuída) — ou que não está no WhatsApp — não retorna erro por padrão: o parâmetro placeholder controla a resposta.
Uma URL de placeholder inválida (não-https, longa demais) é tratada como o padrão (avatar genérico). O mode=json ignora o placeholder e responde { "url": null }.

Assinatura da URL (opcional)

As URLs de profile_picture retornadas pelos endpoints de verificação podem vir com os parâmetros exp e sig, que assinam a URL com prazo de validade. Quando a exigência de assinatura está habilitada na plataforma, uma requisição sem assinatura válida retorna 403 com o código invalid_signature — basta consultar o destinatário novamente para receber uma URL nova. Você não precisa montar (nem entender) esses parâmetros: use a URL exatamente como ela foi retornada.

Pontos de Atenção

As URLs de profile_picture retornadas pelos endpoints de verificação sempre apontam para este endpoint, mesmo quando o número não tem foto — nesse caso, a resposta é o placeholder descrito acima. Para saber se um número tem foto de fato, use ?mode=json e verifique se url é null.
Cada acesso a este endpoint conta no mesmo limite dos endpoints de verificação de destinatário, inclusive quando a URL está num <img src>. Para exibir muitas fotos com frequência, prefira o ?mode=json e reutilize a URL assinada enquanto ela for válida.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

recipient
string
obrigatório

Número do destinatário em formato internacional (E.164), com ou sem o + inicial.

Parâmetros de consulta

placeholder
string

Comportamento quando o número não tem foto disponível. Omitido ou 1, a resposta é 200 com um avatar genérico em SVG; 0 retorna 404 com o código recipient_not_found; uma URL https retorna 302 redirecionando para ela (útil para servir um placeholder próprio). Ignorado quando mode=json.

mode
enum<string>

Formato da resposta. Use json para receber a URL assinada num corpo JSON em vez do redirecionamento 302. Qualquer outro valor é tratado como o padrão (redirecionamento).

Opções disponíveis:
json
exp
string

Expiração da assinatura da URL (epoch em segundos). Presente nas URLs retornadas pelos endpoints de verificação quando a assinatura está habilitada; não precisa ser montado manualmente.

sig
string

Assinatura da URL. Presente nas URLs retornadas pelos endpoints de verificação quando a assinatura está habilitada; não precisa ser montada manualmente.

Resposta

Resposta em JSON quando mode=json é informado, ou o avatar genérico em SVG quando o número não tem foto disponível (comportamento padrão do placeholder).

url
string<uri> | null
obrigatório

URL assinada temporária da imagem. null quando o número não tem foto disponível (o mode=json ignora o parâmetro placeholder).

Exemplo:

"https://zapsterapi.s3.us-east-1.amazonaws.com/..."

expires_at
string<date-time>

Momento em que a URL assinada expira (ISO 8601). Presente apenas quando url não é null.

Exemplo:

"2026-01-15T12:00:00.000Z"