Skip to main content

​
Avatares de contato

​
Por que não buscamos automaticamente as fotos de perfil do WhatsApp

A Cloud API do WhatsApp, da Meta, não expõe fotos de perfil dos usuários finais. O webhook messages entrega um payload contacts[].profile que inclui apenas name. O campo profile_picture_url existe apenas em /whatsapp_business_profile — ou seja, o perfil da própria empresa — não o dos contatos usuários finais que enviam mensagens para você. Isso é consistente em todos os BSPs da plataforma (360dialog, Twilio, Infobip, etc.). Não existe API pública, edge do Graph, ou campo de webhook que retorne o avatar do cliente.

​
O que renderizamos

  1. Fallback de iniciais (padrão). Renderizamos as iniciais do contato sobre um selo de cor determinístico derivado de um hash do wa_id do contato (com fallback para o número de telefone, e depois para o nome). O mesmo contato sempre recebe a mesma cor entre sessões e dispositivos.
  2. Substituição enviada pelo operador. Operadores podem enviar um JPG / PNG / WEBP de até 2 MB pelo painel de detalhes do contato no inbox. A imagem é reconvertida para um JPG quadrado de 256×256 (com EXIF removido) e armazenada no object store workspace-attachments, em contacts/{workspaceId}/{contactId}/avatar-{hash}.jpg. A URL é persistida em public.contacts.avatar_url e renderizada em todos os lugares em que o contato aparece (barra lateral do inbox, cabeçalho do inbox, lista de contatos, layouts mobile).

​
Fluxo de trabalho do operador

  • Abra uma conversa → painel de detalhes à direita → seção Profile → botões Upload / Replace / Remove.
  • Os uploads acessam POST /api/contacts/[contactId]/avatar (multipart/form-data, campo file); a remoção acessa DELETE /api/contacts/[contactId]/avatar.
  • Ambas as rotas exigem uma verificação ativa de acesso ao workspace do operador e confirmam que o contato pertence ao workspace de quem faz a chamada antes de alterar dados.

​
Modelo de dados

avatar_url é anulável (nullable). Nulo significa “renderizar o fallback de iniciais”.

​
Componente compartilhado

@repo/design-system/components/contact-avatar expõe <ContactAvatar> com size de xs, sm, md, lg. Use-o em qualquer lugar em que um contato seja listado, para manter o comportamento de fallback consistente.