> ## Documentation Index > Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Foto de Perfil do Destinatário > Retorna a foto de perfil de um número, por redirecionamento (302) ou como JSON. ## 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)](https://developer.zapsterapi.com/pt-BR/v1/api-reference/utils/check-recipient.md) e da sua [versão em lote](https://developer.zapsterapi.com/pt-BR/v1/api-reference/utils/check-recipient-batch.md): 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. > [!NOTE] > > **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: ```html theme={null} ``` Se preferir receber a URL da imagem em JSON — por exemplo, para baixar a foto num backend — informe `?mode=json`: ```bash theme={null} curl "https://api.zapsterapi.com/v1/wa/recipients/5511999999999/pp?mode=json" ``` ```json theme={null} { "url": "https://zapsterapi.s3.us-east-1.amazonaws.com/...", "expires_at": "2026-01-15T12:00:00.000Z" } ``` 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. | `placeholder` | Resposta | | - | - | | omitido ou `1` | `200` com um avatar genérico em SVG (`Cache-Control: public, max-age=86400`) | | `0` | `404` com o código `recipient_not_found` | | uma URL `https` | `302` redirecionando para a URL informada — sirva seu próprio placeholder | ```html theme={null} ``` 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 > [!NOTE] > > 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`. > [!WARNING] > > Cada acesso a este endpoint conta no mesmo limite dos endpoints de verificação de destinatário, inclusive quando a URL está num ``. Para exibir muitas fotos com frequência, prefira o `?mode=json` e reutilize a URL assinada enquanto ela for válida. ## OpenAPI ````yaml GET /wa/recipients/{recipient}/pp openapi: 3.1.0 info: title: Zapster API description: '' version: 1.0.0 servers: - url: https://api.zapsterapi.com/v1 description: Produção security: [] tags: [] paths: /wa/recipients/{recipient}/pp: get: tags: [] summary: Foto de Perfil do Destinatário description: >- Retorna a foto de perfil de um número, por redirecionamento (302) ou como JSON. parameters: - name: recipient in: path description: >- Número do destinatário em formato internacional (E.164), com ou sem o `+` inicial. required: true example: '5511999999999' schema: type: string - name: placeholder in: query description: >- 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`. required: false example: '0' schema: type: string - name: mode in: query description: >- 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). required: false example: json schema: type: string enum: - json - name: exp in: query description: >- 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. required: false schema: type: string - name: sig in: query description: >- Assinatura da URL. Presente nas URLs retornadas pelos endpoints de verificação quando a assinatura está habilitada; não precisa ser montada manualmente. required: false schema: type: string responses: '200': description: >- 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`). content: application/json: schema: type: object properties: url: type: string format: uri nullable: true example: https://zapsterapi.s3.us-east-1.amazonaws.com/... description: >- 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`). expires_at: type: string format: date-time example: '2026-01-15T12:00:00.000Z' description: >- Momento em que a URL assinada expira (ISO 8601). Presente apenas quando `url` não é `null`. required: - url image/svg+xml: schema: type: string description: >- Avatar genérico (placeholder) servido quando o número não tem foto disponível e o parâmetro `placeholder` está omitido ou é `1`. Acompanha `Cache-Control: public, max-age=86400`. '302': description: > Redirecionamento para uma URL assinada temporária da imagem (validade de 10 minutos). É a resposta padrão, pensada para uso direto em ``. Quando o número não tem foto e `placeholder` é uma URL `https`, o redirecionamento aponta para ela. headers: Location: description: URL assinada temporária da imagem. schema: type: string format: uri Cache-Control: description: '`private, max-age=60`' schema: type: string '400': description: Número fora do formato internacional (E.164) content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: recipient_invalid_format message: type: string example: >- The recipient must be a phone number in international format (e.g. 5511999999999). '403': description: >- Assinatura da URL ausente, inválida ou expirada (apenas quando a exigência de assinatura está habilitada) content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: invalid_signature message: type: string example: >- The profile picture URL signature is missing, invalid or expired. Fetch the recipient again to get a fresh URL. '404': description: >- Número sem foto disponível quando `placeholder=0` é informado (por padrão, a resposta sem foto é o avatar genérico em `200`) content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: recipient_not_found message: type: string example: The specified recipient could not be found. '429': description: > Limite de consultas excedido. A cota é a mesma dos endpoints de verificação de destinatário (contada por destinatário). Os headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After` acompanham a resposta. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: rate_limited message: type: string example: >- You can only make 10 recipient checks every 60 seconds. '503': description: Pool de instâncias da Zapster temporariamente indisponível content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string example: recipient_pool_unavailable message: type: string example: >- The recipient verification service is temporarily unavailable. Please try again shortly. deprecated: false security: - bearer: [] components: securitySchemes: bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.