API atual/Referência completa/WhatsApp: conexão

Perfil comercial do número

Lê e atualiza o perfil público do número no WhatsApp: nome, descrição, endereço, foto e site.

O perfil comercial é o que o cliente vê ao tocar no nome da loja dentro do WhatsApp: descrição, endereço, e-mail, site e foto. Ele vive na Meta; estas rotas lêem e escrevem lá. Exigem que o número da loja já esteja conectado (veja Credenciais).

Consultar o perfil

Combina o que a Meta devolve com o que a loja guardou. Se a Meta não puder ser lida (token sem permissão, número inexistente), a resposta continua 200, com meta_sync: false e o motivo em meta_error.

GET/api/v1/admin/whatsapp/profileAdmin

Lê o perfil comercial do número da loja

Exemplo de requisição (Consultar o perfil)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/profile" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar o perfil)

200Perfil

json

{
  "display_name": "Loja Exemplo",
  "verified_name": "Loja Exemplo",
  "display_phone_number": "5511999998888",
  "about": "Moda e acessórios",
  "description": "Loja de moda com entrega para todo o Brasil.",
  "category": "RETAIL",
  "address": "Av. Paulista, 1000, São Paulo",
  "email": "contato@lojaexemplo.com.br",
  "website": "https://lojaexemplo.com.br",
  "profile_picture_url": "",
  "photo_on_meta": false,
  "business_phone": "5511999998888",
  "phone_number_id": "109876543210987",
  "verified": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED",
  "meta_sync": true
}

Campos da resposta

display_namestring

Nome que o lojista quer exibir. Pode diferir do verified_name enquanto a Meta analisa a troca.

verified_namestring

Nome aprovado pela Meta. Só leitura: mudar exige análise da Meta.

display_phone_numberstring

Telefone como a Meta o exibe.

aboutstring

Texto curto de recado (campo about).

descriptionstring

Descrição do negócio.

categorystring

Categoria da Meta, por exemplo RETAIL, AUTO, GROCERY, OTHER.

addressstring

Endereço.

emailstring

E-mail de contato.

websitestring

Site.

profile_picture_urlstring

Foto de perfil. Pode ser um rascunho local ainda não enviado à Meta (veja photo_on_meta).

photo_on_metaboolean

true quando a Meta já hospeda a foto.

business_phonestring

Telefone comercial guardado na loja.

phone_number_idstring

Id do número na Meta.

verifiedboolean

Número ativo e verificado.

quality_ratingstring

Qualidade do número segundo a Meta: GREEN, YELLOW, RED ou UNKNOWN. Ausente se a Meta não informou.

name_statusstring

Situação da análise do nome: APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED ou NONE.

meta_syncboolean

true quando a Meta respondeu a pelo menos uma das duas consultas.

meta_errorstring

Último erro da Meta. Vazio quando a leitura funcionou.

warningstring

Aviso não fatal da última gravação. Só aparece no PUT.

Erros (Consultar o perfil)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
404	A loja não tem número conectado.	`{"error":"whatsapp number not connected","detail":"..."}`

Atualizar o perfil

Envia à Meta todos os campos editáveis. A resposta é o perfil já recarregado, com warning quando alguma parte não pôde ser aplicada (por exemplo, a Meta recusou apagar um campo ou o nome entrou em análise).

PUT/api/v1/admin/whatsapp/profileAdmin

Atualiza o perfil comercial na Meta

Corpo da requisição

display_namestring

Novo nome de exibição. A troca passa por análise da Meta: o cliente continua vendo o nome antigo até a aprovação. Reenviar o mesmo nome não gasta outra solicitação.

aboutstring

Recado curto. Se description vier vazia, este texto é usado como descrição.

descriptionstring

Descrição do negócio.

categorystring

Categoria da Meta.

addressstring

Endereço.

emailstring

E-mail.

websitestring

Site.

profile_picture_urlstring

URL pública da foto (por exemplo, de um /uploads/... da loja). Se vier preenchida, a foto é enviada à Meta.

Exemplo de requisição (Atualizar o perfil)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Loja Exemplo",
    "about": "Moda e acessórios",
    "description": "Loja de moda com entrega para todo o Brasil.",
    "category": "RETAIL",
    "address": "Av. Paulista, 1000, São Paulo",
    "email": "contato@lojaexemplo.com.br",
    "website": "https://lojaexemplo.com.br"
  }'

Resposta (Atualizar o perfil)

200Perfil salvo

json

{
  "display_name": "Loja Exemplo",
  "about": "Moda e acessórios",
  "description": "Loja de moda com entrega para todo o Brasil.",
  "category": "RETAIL",
  "address": "Av. Paulista, 1000, São Paulo",
  "email": "contato@lojaexemplo.com.br",
  "website": "https://lojaexemplo.com.br",
  "photo_on_meta": false,
  "meta_sync": true,
  "warning": "Nome de exibição já está em revisão na Meta."
}

Campos da resposta

(...)object

Mesmos campos do GET. warning descreve avisos não fatais, em português, como a plataforma devolve.

Erros (Atualizar o perfil)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
404	A loja não tem número conectado.	`{"error":"whatsapp number not connected","detail":"..."}`
502	Não há token da Meta, ou a Meta recusou a atualização (inclusive a foto).	`{"error":"meta credentials missing","detail":"..."}`

Veja também

API atual/Referência completa/WhatsApp: conexão

Perfil comercial do número

Lê e atualiza o perfil público do número no WhatsApp: nome, descrição, endereço, foto e site.

Consultar o perfil

GET/api/v1/admin/whatsapp/profileAdmin

Lê o perfil comercial do número da loja

Exemplo de requisição (Consultar o perfil)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/profile" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar o perfil)

200Perfil

json

{
  "display_name": "Loja Exemplo",
  "verified_name": "Loja Exemplo",
  "display_phone_number": "5511999998888",
  "about": "Moda e acessórios",
  "description": "Loja de moda com entrega para todo o Brasil.",
  "category": "RETAIL",
  "address": "Av. Paulista, 1000, São Paulo",
  "email": "contato@lojaexemplo.com.br",
  "website": "https://lojaexemplo.com.br",
  "profile_picture_url": "",
  "photo_on_meta": false,
  "business_phone": "5511999998888",
  "phone_number_id": "109876543210987",
  "verified": true,
  "quality_rating": "GREEN",
  "name_status": "APPROVED",
  "meta_sync": true
}

Campos da resposta

display_namestring

Nome que o lojista quer exibir. Pode diferir do verified_name enquanto a Meta analisa a troca.

verified_namestring

Nome aprovado pela Meta. Só leitura: mudar exige análise da Meta.

display_phone_numberstring

Telefone como a Meta o exibe.

aboutstring

Texto curto de recado (campo about).

descriptionstring

Descrição do negócio.

categorystring

Categoria da Meta, por exemplo RETAIL, AUTO, GROCERY, OTHER.

addressstring

Endereço.

emailstring

E-mail de contato.

websitestring

Site.

profile_picture_urlstring

Foto de perfil. Pode ser um rascunho local ainda não enviado à Meta (veja photo_on_meta).

photo_on_metaboolean

true quando a Meta já hospeda a foto.

business_phonestring

Telefone comercial guardado na loja.

phone_number_idstring

Id do número na Meta.

verifiedboolean

Número ativo e verificado.

quality_ratingstring

Qualidade do número segundo a Meta: GREEN, YELLOW, RED ou UNKNOWN. Ausente se a Meta não informou.

name_statusstring

Situação da análise do nome: APPROVED, AVAILABLE_WITHOUT_REVIEW, PENDING_REVIEW, DECLINED, EXPIRED ou NONE.

meta_syncboolean

true quando a Meta respondeu a pelo menos uma das duas consultas.

meta_errorstring

Último erro da Meta. Vazio quando a leitura funcionou.

warningstring

Aviso não fatal da última gravação. Só aparece no PUT.

Erros (Consultar o perfil)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
404	A loja não tem número conectado.	`{"error":"whatsapp number not connected","detail":"..."}`

Atualizar o perfil

PUT/api/v1/admin/whatsapp/profileAdmin

Atualiza o perfil comercial na Meta

Corpo da requisição

display_namestring

Novo nome de exibição. A troca passa por análise da Meta: o cliente continua vendo o nome antigo até a aprovação. Reenviar o mesmo nome não gasta outra solicitação.

aboutstring

Recado curto. Se description vier vazia, este texto é usado como descrição.

descriptionstring

Descrição do negócio.

categorystring

Categoria da Meta.

addressstring

Endereço.

emailstring

E-mail.

websitestring

Site.

profile_picture_urlstring

URL pública da foto (por exemplo, de um /uploads/... da loja). Se vier preenchida, a foto é enviada à Meta.

Exemplo de requisição (Atualizar o perfil)

bash

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp/profile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Loja Exemplo",
    "about": "Moda e acessórios",
    "description": "Loja de moda com entrega para todo o Brasil.",
    "category": "RETAIL",
    "address": "Av. Paulista, 1000, São Paulo",
    "email": "contato@lojaexemplo.com.br",
    "website": "https://lojaexemplo.com.br"
  }'

Resposta (Atualizar o perfil)

200Perfil salvo

json

{
  "display_name": "Loja Exemplo",
  "about": "Moda e acessórios",
  "description": "Loja de moda com entrega para todo o Brasil.",
  "category": "RETAIL",
  "address": "Av. Paulista, 1000, São Paulo",
  "email": "contato@lojaexemplo.com.br",
  "website": "https://lojaexemplo.com.br",
  "photo_on_meta": false,
  "meta_sync": true,
  "warning": "Nome de exibição já está em revisão na Meta."
}

Campos da resposta

(...)object

Mesmos campos do GET. warning descreve avisos não fatais, em português, como a plataforma devolve.

Erros (Atualizar o perfil)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_settings"}` ou `{"error":"admin access required"}`
404	A loja não tem número conectado.	`{"error":"whatsapp number not connected","detail":"..."}`
502	Não há token da Meta, ou a Meta recusou a atualização (inclusive a foto).	`{"error":"meta credentials missing","detail":"..."}`