Alterar configurações de privacidade

PATCH /inbox/privacy

Altera uma ou mais configurações de privacidade da conta conectada. Mande só os campos que quer mudar; os que já têm o valor pedido não são reenviados ao WhatsApp. A resposta traz todas as configurações depois da alteração.

Valores que não são óbvios:

contact_blacklist: meus contatos, exceto os escolhidos no celular;
match_last_seen (só online): igual ao visto por último;
known (só call_add): só números conhecidos.

Em status, a privacidade é a do recado (o texto embaixo do nome). A privacidade dos stories não é alterada por aqui.

Erros: corpo sem nenhum campo conhecido, valor vazio ou valor que aquele campo não aceita responde 400, e nada é aplicado. Uma falha do WhatsApp no meio responde 500; o que foi gravado antes dela fica.

Autenticação

[
  {
    "token": []
  }
]

{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}

Corpo da requisição

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "group_add": {
            "type": "string",
            "enum": [
              "all",
              "contacts",
              "contact_blacklist",
              "none"
            ],
            "description": "Quem pode adicionar aos grupos. Valores - all, contacts, contact_blacklist, none"
          },
          "last_seen": {
            "type": "string",
            "enum": [
              "all",
              "contacts",
              "contact_blacklist",
              "none"
            ],
            "description": "Quem pode ver visto por último. Valores - all, contacts, contact_blacklist, none"
          },
          "status": {
            "type": "string",
            "enum": [
              "all",
              "contacts",
              "contact_blacklist",
              "none"
            ],
            "description": "Quem pode ver status (recado embaixo do nome). Valores - all, contacts, contact_blacklist, none"
          },
          "profile_picture": {
            "type": "string",
            "enum": [
              "all",
              "contacts",
              "contact_blacklist",
              "none"
            ],
            "description": "Quem pode ver foto de perfil. Valores - all, contacts, contact_blacklist, none"
          },
          "read_receipts": {
            "type": "string",
            "enum": [
              "all",
              "none"
            ],
            "description": "Confirmação de leitura. Valores - all, none"
          },
          "online": {
            "type": "string",
            "enum": [
              "all",
              "match_last_seen"
            ],
            "description": "Quem pode ver status online. Valores - all, match_last_seen"
          },
          "call_add": {
            "type": "string",
            "enum": [
              "all",
              "known"
            ],
            "description": "Quem pode fazer chamadas. Valores - all, known"
          }
        },
        "minProperties": 1,
        "additionalProperties": false
      },
      "examples": {
        "single_setting": {
          "summary": "Alterar uma configuração",
          "value": {
            "group_add": "contacts"
          }
        },
        "multiple_settings": {
          "summary": "Alterar múltiplas configurações",
          "value": {
            "group_add": "contacts",
            "last_seen": "none",
            "status": "contacts",
            "profile_picture": "contacts"
          }
        },
        "privacy_strict": {
          "summary": "Configuração mais restritiva",
          "value": {
            "group_add": "none",
            "last_seen": "none",
            "status": "contacts",
            "profile_picture": "contacts",
            "read_receipts": "none"
          }
        }
      }
    }
  }
}

Respostas

{
  "200": {
    "description": "Configuração de privacidade alterada com sucesso",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "group_add": {
              "type": "string",
              "enum": [
                "all",
                "contacts",
                "contact_blacklist",
                "none"
              ],
              "description": "Quem pode adicionar aos grupos. Valores - all, contacts, contact_blacklist, none"
            },
            "last_seen": {
              "type": "string",
              "enum": [
                "all",
                "contacts",
                "contact_blacklist",
                "none"
              ],
              "description": "Quem pode ver visto por último. Valores - all, contacts, contact_blacklist, none"
            },
            "status": {
              "type": "string",
              "enum": [
                "all",
                "contacts",
                "contact_blacklist",
                "none"
              ],
              "description": "Quem pode ver status (recado embaixo do nome). Valores - all, contacts, contact_blacklist, none"
            },
            "profile_picture": {
              "type": "string",
              "enum": [
                "all",
                "contacts",
                "contact_blacklist",
                "none"
              ],
              "description": "Quem pode ver foto de perfil. Valores - all, contacts, contact_blacklist, none"
            },
            "read_receipts": {
              "type": "string",
              "enum": [
                "all",
                "none"
              ],
              "description": "Confirmação de leitura. Valores - all, none"
            },
            "online": {
              "type": "string",
              "enum": [
                "all",
                "match_last_seen"
              ],
              "description": "Quem pode ver status online. Valores - all, match_last_seen"
            },
            "call_add": {
              "type": "string",
              "enum": [
                "all",
                "known"
              ],
              "description": "Quem pode fazer chamadas. Valores - all, known"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Configurações atualizadas após alteração",
            "value": {
              "group_add": "contacts",
              "last_seen": "contacts",
              "status": "contacts",
              "profile_picture": "contacts",
              "read_receipts": "all",
              "online": "all",
              "call_add": "all"
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Corpo que não é JSON (`Invalid payload`), nenhum campo conhecido, ou um valor vazio, que não é texto ou fora da lista. Nada é aplicado. Campos desconhecidos são ignorados.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "Corpo que não é JSON (`Invalid payload`), nenhum campo conhecido, ou um valor vazio, que não é texto ou fora da lista. N"
        }
      }
    }
  },
  "401": {
    "description": "Token ausente ou inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "description": "Falha do WhatsApp ao gravar, ou inbox sem sessão (`No session`). Os campos gravados antes da falha ficam aplicados.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "internal_error",
          "message": "Falha do WhatsApp ao gravar, ou inbox sem sessão (`No session`). Os campos gravados antes da falha ficam aplicados."
        }
      }
    }
  },
  "501": {
    "$ref": "#/components/responses/CloudUnsupported"
  },
  "503": {
    "$ref": "#/components/responses/Disconnected"
  }
}

Estado: Disponível

Compatibilidade de canais

Canal	Compatível	Observação
WhatsApp (Web)	Sim
WhatsApp (API oficial)	Não	Só no WhatsApp Web.
Instagram	Não
Messenger	Não
Telegram	Não

Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em GET /events): o resultado vem só na resposta.

Antes e depois (uazapi → Orkesio)

Na uazapi: POST /instance/privacy.

PATCH /inbox/privacy; os mesmos nomes do GET.

#/components/schemas/OrkesioError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}

#/components/responses/RateLimited

{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}

#/components/responses/CloudUnsupported

{
  "description": "`unsupported_for_channel`: o canal da inbox não atende esta rota (rota só do WhatsApp Web numa inbox oficial, ou rota da API oficial numa inbox do WhatsApp Web). O canal está em `Inbox.channel`.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "unsupported_for_channel",
        "message": "Esta rota não está disponível no canal da inbox."
      }
    }
  }
}

#/components/responses/Disconnected

{
  "description": "`disconnected`: a inbox está desconectada do WhatsApp (a api esperou a sessão e tentou reconectar). `unavailable`: o WhatsApp não respondeu agora; tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "disconnected",
        "message": "Instância desconectada do WhatsApp."
      }
    }
  }
}

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi