API atual/Referência completa/WhatsApp: caixa de entrada

Presença dos atendentes

Informa que o atendente está online, define o recado de status e lista quem está disponível.

A presença mostra à equipe quem está disponível na caixa de entrada. O painel envia um heartbeat (sinal de vida) a cada poucos segundos. O estado é calculado pelo tempo desde o último sinal: até 60 segundos é online, até 5 minutos é idle (ausente), e depois disso offline.

Enviar heartbeat

Registra o usuário do token como atendente e carimba a hora do sinal. Sem corpo.

POST/api/v1/admin/whatsapp/heartbeatAdmin

Registra que o usuário do token está ativo agora

Exemplo de requisição (Enviar heartbeat)

bash

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

Resposta (Enviar heartbeat)

200Registrado

json

{
  "ok": true,
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "last_heartbeat": "2026-10-11T22:00:00Z"
}

Campos da resposta

okboolean

true.

user_idstring

UUID do usuário.

last_heartbeatstring

Hora do sinal, RFC 3339 em UTC.

Erros (Enviar heartbeat)

Status	Quando	Corpo
401	Token sem usuário.	`{"error":"auth required"}`
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_orders"}` ou `{"error":"admin access required"}`

Listar presença

Devolve um array simples (sem envelope), um item por atendente.

GET/api/v1/admin/whatsapp/presenceAdmin

Lista os atendentes e o estado de cada um

Exemplo de requisição (Listar presença)

bash

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

Resposta (Listar presença)

200Atendentes

json

[
  {
    "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "name": "Ana Souza",
    "email": "ana@lojaexemplo.com.br",
    "status": "online",
    "last_heartbeat": "2026-10-11T22:00:00Z",
    "last_status_label": "Em reunião até 15h"
  }
]

Campos da resposta

user_idstring

UUID do atendente.

namestring

Nome.

emailstring

E-mail.

statusstring

onlineidleoffline

Estado calculado.

last_heartbeatstring

Último sinal. Ausente se nunca houve.

last_status_labelstring

Recado de status, até 32 caracteres. Ausente se vazio.

Erros (Listar presença)

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_orders"}` ou `{"error":"admin access required"}`

Definir recado de status

O recado aparece na lista de presença. Texto acima de 32 caracteres é cortado. Envie label vazio para apagar.

POST/api/v1/admin/whatsapp/presence/statusAdmin

Define o recado de status do usuário do token

Corpo da requisição

labelstringobrigatório

Recado (até 32 caracteres).

Exemplo de requisição (Definir recado de status)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/presence/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Em reunião até 15h"
  }'

Resposta (Definir recado de status)

200Definido

json

{
  "ok": true
}

Campos da resposta

okboolean

true.

Erros (Definir recado de status)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
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_orders"}` ou `{"error":"admin access required"}`
404	O usuário ainda não é atendente registrado: envie um heartbeat antes.	`{"error":"attendant not registered"}`

Veja também

API atual/Referência completa/WhatsApp: caixa de entrada

Presença dos atendentes

Informa que o atendente está online, define o recado de status e lista quem está disponível.

Enviar heartbeat

Registra o usuário do token como atendente e carimba a hora do sinal. Sem corpo.

POST/api/v1/admin/whatsapp/heartbeatAdmin

Registra que o usuário do token está ativo agora

Exemplo de requisição (Enviar heartbeat)

bash

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

Resposta (Enviar heartbeat)

200Registrado

json

{
  "ok": true,
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "last_heartbeat": "2026-10-11T22:00:00Z"
}

Campos da resposta

okboolean

true.

user_idstring

UUID do usuário.

last_heartbeatstring

Hora do sinal, RFC 3339 em UTC.

Erros (Enviar heartbeat)

Status	Quando	Corpo
401	Token sem usuário.	`{"error":"auth required"}`
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_orders"}` ou `{"error":"admin access required"}`

Listar presença

Devolve um array simples (sem envelope), um item por atendente.

GET/api/v1/admin/whatsapp/presenceAdmin

Lista os atendentes e o estado de cada um

Exemplo de requisição (Listar presença)

bash

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

Resposta (Listar presença)

200Atendentes

json

[
  {
    "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "name": "Ana Souza",
    "email": "ana@lojaexemplo.com.br",
    "status": "online",
    "last_heartbeat": "2026-10-11T22:00:00Z",
    "last_status_label": "Em reunião até 15h"
  }
]

Campos da resposta

user_idstring

UUID do atendente.

namestring

Nome.

emailstring

E-mail.

statusstring

onlineidleoffline

Estado calculado.

last_heartbeatstring

Último sinal. Ausente se nunca houve.

last_status_labelstring

Recado de status, até 32 caracteres. Ausente se vazio.

Erros (Listar presença)

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_orders"}` ou `{"error":"admin access required"}`

Definir recado de status

O recado aparece na lista de presença. Texto acima de 32 caracteres é cortado. Envie label vazio para apagar.

POST/api/v1/admin/whatsapp/presence/statusAdmin

Define o recado de status do usuário do token

Corpo da requisição

labelstringobrigatório

Recado (até 32 caracteres).

Exemplo de requisição (Definir recado de status)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/presence/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Em reunião até 15h"
  }'

Resposta (Definir recado de status)

200Definido

json

{
  "ok": true
}

Campos da resposta

okboolean

true.

Erros (Definir recado de status)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
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_orders"}` ou `{"error":"admin access required"}`
404	O usuário ainda não é atendente registrado: envie um heartbeat antes.	`{"error":"attendant not registered"}`