Pular para o conteúdo

Complemento Global de Variável: Web API

O Complemento Global de Variável: Web API permite conectar as variáveis permanentes do quarto a aplicações externas. Quer mostrar o inventário de um jogo em um site ou trazer informações de um projeto para dentro do Habbo? Este Wired fornece as chaves que sua aplicação utiliza para consultar e alterar esses dados pela API.

Uma API é uma forma de comunicação entre programas. Neste caso, sua aplicação envia uma solicitação por HTTPS ao Habbo, que consulta ou altera as variáveis e devolve uma resposta. Cada endereço disponível para realizar uma operação é chamado de endpoint.

Para utilizar a integração, você precisa ter acesso a este Wired, variáveis permanentes configuradas no quarto e uma aplicação capaz de fazer requisições HTTPS. Essa aplicação pode ser um site com um servidor próprio, por exemplo.

O Wired gera as chaves de acesso. Para criar uma integração própria, você precisa programar sua lógica na aplicação. Se quiser consultar e gerenciar os dados por uma interface pronta, pode utilizar o explorador de variáveis do Habbo. As variáveis que ela utilizará devem ser configuradas no Habbo pelos respectivos Wireds de usuário, mobi ou quarto.

Ao clicar duas vezes neste Wired, você encontra o link da documentação, um alerta de uso, os campos das chaves de leitura e escrita e as permissões extras.

Janela do Complemento Global de Variável Web API com o link da documentação, alerta de uso, campos das chaves de leitura e escrita e permissão de remoção em massa.

Este link abre a documentação pública da API do Habbo. Na seção Wired Variables, você encontra os endpoints para trabalhar com as variáveis, os parâmetros aceitos, a autenticação exigida e os formatos de resposta.

Seção Wired Variables da documentação da API com endpoints para consultar, criar, atualizar e remover dados de variáveis, contar registros e executar operações em lote.

Entre as possibilidades estão consultar valores, vincular variáveis a alvos, atualizar dados e remover associações. Também é possível listar os usuários ou mobis que possuem uma variável, contar esses registros e executar várias operações em uma única requisição.

Utilize a documentação oficial para conferir os detalhes de cada endpoint antes de implementá-lo. Nos exemplos desta página, os caminhos são relativos ao endereço do hotel utilizado, e campos como {roomId} devem ser substituídos pelos identificadores correspondentes.

O aviso da janela explica que as chaves permitem ler e escrever variáveis por endpoints HTTPS dedicados. Também informa que outras pessoas não conseguem ver o conteúdo dessa caixa e que você não deve compartilhar as chaves com quem não confia.

Alerta de uso em vermelho orientando a proteger as chaves e a recarregar o quarto após alterações nas configurações das variáveis.

Depois de alterar as configurações das variáveis no quarto, talvez seja necessário recarregar o quarto para que a API funcione corretamente.

Esta chave é utilizada nas requisições de consulta, como conferir o valor de uma variável de um jogador, listar as variáveis configuradas no quarto ou contar quantos usuários possuem uma determinada variável. Essas operações permitem ler os dados sem alterá-los. O campo de texto disponível não permite editar o texto gerado, mas você pode selecioná-lo para copiar.

Campo vazio de Chave API para leitura com os botões Gerar, Limpar e Copiar.

Botão O que faz
Gerar Cria uma chave e a mostra no campo.
Gerar novamente Substitui a chave anterior por uma nova. Aparece depois da primeira geração.
Limpar Apaga a chave do campo.
Copiar Copia a chave para que você possa utilizá-la na aplicação.

Confira na documentação do endpoint como enviar a chave na requisição. Para uma aplicação que apenas consulta dados, utilize a chave de leitura.

Esta chave é utilizada nas requisições que alteram dados, como atribuir um valor ou remover uma variável de um usuário. Os botões Gerar, Gerar novamente, Limpar e Copiar funcionam da mesma forma que no campo de leitura.

Campo vazio de Chave API para escrever com os botões Gerar, Limpar e Copiar.

Ao substituir uma chave, atualize também a aplicação que a utiliza para que ela continue acessando a API.

As chaves de leitura e escrita só ficam válidas para uso depois de concluir esta sequência:

  1. Gere as chaves na configuração do Wired.
  2. Clique em Pronto para confirmar as configurações.
  3. Nas Ferramentas do Criador, abra a aba Configurações e clique em Recarregar (Reload) na seção Estado do quarto.

Depois de recarregar o quarto, você poderá utilizar as chaves na aplicação ou no explorador de variáveis. Siga essa sequência também ao gerar novas chaves para substituir as anteriores.

Depois de gerar as duas chaves, você pode marcar Permitir remoção em massa. Ao fazer isso, uma janela pede confirmação e alerta sobre o risco de chamar o endpoint /variables/bulk-delete por engano.

Janela de confirmação alertando que a remoção em massa apaga irreversivelmente o conteúdo das variáveis e recomendando testes em outro quarto, com botões Cancelar e Ok.

Ao tentar retirar este Wired, aparece uma janela pedindo confirmação com a mensagem:

Janela Removendo um Add-On Web API avisando que a API deixará de funcionar no quarto e que as chaves mudarão ao recolocar o Wired, com botões Cancelar e Ok.

Se você confirmar, a Web API deixará de funcionar para esse quarto. Ao colocar o Wired novamente, as chaves serão diferentes das anteriores. Atualize as chaves utilizadas pela sua aplicação ou pelo explorador de variáveis para voltar a acessar os dados.

Quer experimentar as operações sem criar uma aplicação primeiro? O Habbo disponibiliza o Variables Explorer, uma interface para consultar e gerenciar as variáveis do quarto.

Para acessar os dados, informe o hotel, o identificador único do quarto e as chaves de API geradas no Wired. Com isso, você pode realizar operações de criação de associações, consulta, atualização e exclusão de dados, conhecidas pela sigla CRUD, conforme as permissões das chaves utilizadas.

Tela de conexão do Variables Explorer com seleção de hotel, identificador do quarto, chaves de leitura e escrita e botão Open explorer.

As alterações feitas nessa interface atingem os dados do quarto. Criar uma associação por ela significa vincular uma variável já configurada a um alvo, conforme as regras da API; a configuração da variável continua sendo feita no Habbo.

A API utiliza métodos HTTP para indicar a ação desejada: GET consulta, PATCH modifica, PUT cria ou substitui e DELETE remove. Nem todos os recursos aceitam todos esses métodos.

Antes de fazer uma solicitação, identifique qual variável e qual alvo você deseja acessar:

Termo Significado
Escopo (scope) O tipo da variável: user, furni ou global.
Tipo de alvo (targetKind) Distingue os alvos de um escopo. Para user: users, pets e bots. Para furni: furni, furni-bc, wall-items e wall-items-bc.
Entidade (entity) O alvo que pode possuir variáveis, como um jogador, bot, mascote ou mobi.
Identificador (entityId) O número que identifica esse alvo na API.

Os tipos com sufixo -bc representam os mobis do Clube do Arquiteto (CA). Para variáveis globais, os endpoints utilizam o próprio quarto, sem precisar indicar um usuário ou mobi.

Para a API, uma variável de usuário ou mobi é um recurso identificado pelo nome da variável e pelo alvo ao qual ela está vinculada. Por exemplo, pontuacao de um jogador e pontuacao de outro jogador são recursos diferentes.

Uma resposta pode ter este formato:

{
"value": 7,
"creation_time": "2026-09-01T19:26:09.664Z",
"update_time": "2026-09-01T19:26:09.664Z"
}

value é o valor armazenado. creation_time e update_time indicam quando esse registro foi criado e atualizado. O Z ao final indica que o horário está em UTC.

O caminho para acessar esse recurso é:

/api/public/rooms/{roomId}/variables/{scope}/{variableName}/{targetKind}/{entityId}
Método O que faz nesse recurso
GET Consulta a variável vinculada ao alvo.
PATCH Altera a propriedade value.
PUT Cria a associação ou substitui a existente, de forma semelhante à opção de substituir variável existente do Efeito Dar Variável.
DELETE Remove a associação e o valor daquele alvo.

Criar essa associação não significa criar a configuração de um novo Wired de variável. A variável precisa estar configurada no quarto.

Para uma variável global, utilize o caminho abaixo com GET ou PATCH. Ela sempre existe enquanto estiver configurada no quarto, por isso não aceita PUT ou DELETE nesse recurso.

/api/public/rooms/{roomId}/variables/global/{variableName}

Um perfil de variáveis reúne as variáveis de um mesmo alvo. Em vez de consultar cada uma separadamente, você pode acessar esse conjunto.

Alvo Quando o perfil existe Métodos disponíveis
Mobi Enquanto o mobi está no quarto. Se não possuir variáveis, o perfil estará vazio. GET e PATCH
Global Sempre existe para o quarto. GET e PATCH
Jogador, bot ou mascote Quando possui pelo menos uma variável permanente associada no quarto. GET, PATCH e DELETE

Não é possível criar o perfil de um usuário pela API. Para que ele exista, o usuário precisa receber pelo menos uma variável permanente no quarto.

Ao excluir o perfil de um usuário, todas as suas variáveis são removidas. Para que o perfil volte a existir, ele precisará receber uma variável novamente dentro do jogo.

Uma requisição PATCH de perfil pode criar associações, alterar valores e remover variáveis do mesmo alvo:

{
"variables": {
"pontuacao": 7,
"participando": null
}
}

Nesse exemplo, pontuacao é vinculada ao alvo se ainda não estiver associada, ou atualizada para 7 se já existir. O valor null remove a associação de participando. Utilize essas ações conforme os métodos e as operações permitidos para o tipo de perfil.

Além de acessar uma variável ou um perfil, você pode utilizar os seguintes recursos:

Caminho relativo a /api/public/rooms/{roomId} Para que serve
/variables Lista as variáveis configuradas no quarto, separadas em usuário, mobi e global.
/variables/{scope}/{variableName}/{targetKind} Lista os alvos que possuem uma variável, com paginação.
/variables/{scope}/{variableName}/{targetKind}/count Conta quantos alvos possuem a variável.
/variables/{scope}/{variableName}/batch Executa várias operações sobre a mesma variável em uma solicitação.
/variables/bulk-delete Remove os dados de uma ou mais variáveis dos alvos que as possuem, conforme a solicitação.
/variables_profile/user/users Localiza o perfil de um jogador pelo nome ou unique_id.

A busca por nome ou unique_id funciona para jogadores cujo perfil de variáveis existe no quarto. Ela permite localizar o alvo sem precisar procurar seu identificador em todas as páginas de uma listagem.

O endpoint de lote permite combinar até 50 operações GET, PATCH, PUT ou DELETE. Cada operação recebe um op_id escolhido pela aplicação. Esse identificador volta na resposta para que você possa relacionar cada resultado à solicitação correspondente.

O op_id serve apenas para identificar a operação dentro dessa troca de mensagens; ele não é o identificador do usuário ou mobi.

As listas começam na página 1, retornam 50 registros por página por padrão e aceitam até 100 registros por página.

Para consultar associações recentes, utilize order_by=creation_time com order_dir=desc. Para consultar alterações recentes, utilize order_by=update_time com order_dir=desc. Uma variável própria para acompanhar entradas ou atualizações pode ajudar a organizar essas consultas.

Os limites informados nas referências da API são aplicados por quarto. Há uma janela de 60 segundos para o uso contínuo e outra de 10 segundos para concentrar solicitações em um intervalo curto.

Tipo de operação Limite por minuto Limite em 10 segundos
Leituras simples 300 60
Listagens 120 20
Leituras de perfis 120 20
Escritas 120 30
Remoções em massa 10 5

Operações em lote possuem limites adicionais:

  • 30 requisições de lote por minuto, incluindo PATCH de perfil.
  • 50 operações por lote, no máximo.
  • Orçamento de 500 por minuto para o custo das escritas em lote, contabilizado separadamente.

Consulte a documentação oficial ao implementar a integração, pois os limites podem ser atualizados.

O resultado dos endpoints terminados em /count fica em cache por um período que depende da quantidade de registros. Por isso, uma contagem pode não refletir imediatamente uma alteração feita no quarto.

Quantidade de registros Tempo de cache
Menos de 1.000 20 segundos
De 1.000 a 9.999 60 segundos
De 10.000 a 99.999 300 segundos
100.000 ou mais 600 segundos

Se muitas pessoas acessarem sua aplicação, mantenha também um cache no seu servidor. Assim, vários visitantes podem consultar uma resposta recente sem gerar uma nova requisição ao Habbo a cada acesso.

Ao desenvolver sua integração, você pode utilizar um wrapper: uma biblioteca que oferece funções para acessar a API, facilitando a construção das requisições no seu código. Por exemplo, em vez de montar manualmente cada solicitação, você utiliza os métodos disponibilizados pela biblioteca para consultar ou atualizar os dados.

Há opções para diferentes linguagens e ambientes:

Linguagem ou ambiente Projeto
PHP Habbo API Wrapper PHP
Laravel (PHP) Laravel Habbo Web API
Node.js Habbo SDK
Node.js com TypeScript Habbo API Wrapper Node
Python Habbo API Wrapper Python
Go Habbo API Wrapper Go

Consulte a documentação do projeto escolhido para instalar a biblioteca, configurar o hotel, o quarto e as chaves e conferir quais operações estão disponíveis. O wrapper facilita a comunicação, mas sua aplicação continua responsável pela lógica do sistema e deve respeitar as permissões e os limites da API.

Para facilitar o uso de perfis e operações em lote, mantenha as variáveis permanentes de uma mesma aplicação em um único quarto sempre que possível.

As variáveis armazenam números inteiros de 64 bits com sinal. Consulte Valores que a variável pode armazenar para conhecer esse intervalo e as diferenças em relação à exibição no jogo.

Em JavaScript e TypeScript, o tipo number não representa com precisão todos os inteiros desse intervalo. Para trabalhar com esses valores, utilize bigint e uma solução de leitura e escrita de JSON que preserve inteiros grandes.

Os identificadores usados no jogo nem sempre têm o mesmo formato dos utilizados na API. Para itens de parede, o identificador negativo do jogo passa a ser positivo. Para mobis do CA, também é necessário remover o deslocamento aplicado ao identificador dentro do jogo.

O exemplo abaixo adapta a conversão do material de referência para funcionar sem tipos auxiliares externos:

type FurniKind = "furni" | "furni-bc" | "wall-items" | "wall-items-bc";
type FurniId = { kind: FurniKind; id: number };
const CLUB_OFFSET = 0x7fffffff - 0xffff;
function toApiFurniId(gameId: number): FurniId {
const isWall = gameId < 0;
const normalized = Math.abs(gameId);
const isClub = normalized >= CLUB_OFFSET;
return {
kind: isWall
? (isClub ? "wall-items-bc" : "wall-items")
: (isClub ? "furni-bc" : "furni"),
id: isClub ? normalized - CLUB_OFFSET : normalized,
};
}
function toGameFurniId(furni: FurniId): number {
const isClub = furni.kind === "furni-bc" || furni.kind === "wall-items-bc";
const isWall = furni.kind === "wall-items" || furni.kind === "wall-items-bc";
const id = furni.id + (isClub ? CLUB_OFFSET : 0);
return isWall ? -id : id;
}

Para um item de parede do CA, por exemplo, primeiro retire o sinal negativo e depois subtraia o deslocamento. Envie à API tanto o identificador convertido quanto o tipo de alvo correto.

Se o quarto utiliza o Sistema de Aumento de Nível, a aplicação pode calcular o nível e o progresso a partir do XP armazenado, utilizando as mesmas configurações do Extra.

O código de referência apresenta implementações para os modos Linear, Entrada manual, com interpolação entre níveis, e Exponencial. Elas calculam nível atual, XP necessário para avançar, progresso, porcentagem, XP restante e indicação de nível máximo.

No modo linear, o XP máximo deve ser calculado como (nível máximo − 1) × tamanho da etapa, pois o jogador começa no nível 1 com 0 XP. O material de referência corrige esse cálculo em relação à versão inicial do código.

Por exemplo, com etapas de 100 XP e nível máximo 5:

const stepSize = 100n;
const maximumLevel = 5n;
const maxXp = (maximumLevel - 1n) * stepSize; // 400 XP
function currentLevel(xp: bigint): bigint {
const bounded = xp < 0n ? 0n : xp > maxXp ? maxXp : xp;
return 1n + bounded / stepSize;
}
currentLevel(250n); // 3n
currentLevel(400n); // 5n

Ao adaptar os outros modos, confira os resultados com a visualização do Extra no jogo. O código de referência utiliza conversões para number em partes dos cálculos de interpolação e exponenciação; utilizar bigint para armazenar o XP não elimina, por si só, as limitações dessas conversões.

O Wired Club participou dos testes dessa integração. Saiba mais na notícia Nós fomos escolhidos para testar o Wired API. Os exemplos abaixo foram apresentados por membros durante os testes.

Quer conhecer outras ideias? Confira mais exemplos da comunidade na notícia Wired API finalmente foi lançado.

Neste projeto de jogo apocalíptico, uma aplicação externa reúne mochila, uso de itens, status, habilidades, indicadores de saúde e energia e progressão de nível. As informações do personagem são integradas às variáveis do Habbo.

Na demonstração descrita pelo autor, também havia autenticação com código de verificação e notificações integradas ao Supabase. Criação de itens, envio entre usuários e descarte de itens no chão estavam em desenvolvimento.

Demonstração da integração do projeto The Last of Us Habbo, por an4log

Audiodescrição do vídeo: Demonstração da integração do projeto The Last of Us Habbo, por an4log

Em um quarto do Habbo, o avatar está ao lado de um terminal com o símbolo dos Vagalumes. À esquerda há uma grande montagem de mobis Wired. Um pequeno ícone com o mesmo símbolo é movido pelo chão, enquanto um aviso de faca desequipada permanece no alto da tela.

Ao selecionar o ícone, abre-se o painel preto e vermelho “The Last Of Us Habbo”. Na tela de identificação, o campo de usuário do Habbo recebe o nome AN4LOG; o cursor avança pelo botão “Próximo”.

O painel mostra o avatar e o nome AN4LOG. Uma instrução pede a cópia de uma mensagem de verificação no chat do quarto; o botão “Entrar” aparece abaixo. O painel fecha.

Na barra de chat do Habbo, a mensagem de verificação é enviada. Surge uma notificação azul confirmando o vínculo de um código e orientando a clicar em “Entrar” no aplicativo.

O ícone dos Vagalumes é selecionado novamente. O painel exibe o mesmo avatar, a mensagem de verificação e o botão “Entrar”; em seguida, volta à vista do quarto.

Uma segunda mensagem de verificação é enviada no chat. Outra notificação azul informa que o código foi vinculado. O painel é reaberto.

O aplicativo entra na tela do perfil AN4LOG. Acima das abas, aparecem o nível 12, a barra verde de experiência, a barra rosa de vida e a barra amarela de energia. A mochila mostra uma grade de seis itens.

O cursor alterna de “Skills” para “Avisos”. A lista de avisos exibe mensagens de código de verificação incorreto, apesar das notificações de vínculo ainda visíveis no quarto.

A aba “Skills” volta a mostrar três barras de habilidades coloridas. Em seguida, “Status” apresenta barras de fome, sede, sono e saúde.

Na aba “Itens”, os objetos da mochila mudam de posição na grade durante a interação. O cursor passa por espaços e itens, incluindo materiais, uma faca, uma panela e uma pistola.

Um menu de ações é aberto sobre um item da mochila, com as opções de utilizar, craftar, descartar e enviar. A seleção de “Utilizar” fecha o menu.

Uma notificação laranja informa que a faca foi equipada. A mochila continua aberta; o cursor percorre os objetos e volta a abrir o menu de ações da faca.

Após outra utilização, uma segunda notificação laranja informa que a faca foi desequipada. As duas mensagens ficam empilhadas no alto do quarto.

O cursor passa sobre a panela velha, exibindo seu nome em uma pequena etiqueta. Depois, segue para o ícone de saída no alto do painel.

Uma caixa de confirmação de saída escurece o aplicativo e avisa que será preciso verificar o código novamente. O botão “Sair” é escolhido.

O aplicativo retorna à tela de identificação e depois é fechado. O pequeno ícone dos Vagalumes volta a se mover sobre o chão do quarto.

Contribuições ao Docs Wired Club, por AnaBeatrizJBSan

Seção intitulada “Contribuições ao Docs Wired Club, por AnaBeatrizJBSan”

Neste quarto, a integração aproxima a comunidade do projeto de documentação. Os jogadores podem consultar informações do repositório e associar seu usuário do GitHub ao personagem do Habbo.

  • Ao clicar no mobi Luz Lounge Estrela, é possível consultar a quantidade de estrelas do repositório.
  • Ao clicar no bloco numérico, é possível consultar quantos pull requests estão abertos para revisão.
  • Ao sentar na cadeira indicada e informar o nome de usuário do GitHub ao bot, o jogador vincula sua conta ao personagem.
  • Ao clicar em um usuário vinculado, é possível consultar seus commits, pull requests de autoria própria que foram incorporados ao projeto e revisões enviadas nos pull requests de outras pessoas.

A aplicação externa faz a comunicação com os serviços envolvidos e utiliza a Web API para integrar essas informações às variáveis do quarto.

Demonstração do quarto de contribuições ao Docs Wired Club, por AnaBeatrizJBSan

Audiodescrição do vídeo: Demonstração do quarto de contribuições ao Docs Wired Club, por AnaBeatrizJBSan

A gravação mostra um quarto do Habbo à esquerda e um painel de controle do Wired Club no navegador à direita. No quarto, uma personagem está perto de uma mesa ocupada por outro avatar; blocos coloridos formam uma decoração na parede. No painel, o botão de sincronização é acionado.

A seção de sincronização indica que a execução está em andamento. A página é rolada para baixo até a área de observação de vínculos e os registros de comandos.

O bloco branco com número no quarto muda de 1 para 2. Uma seta amarela destaca o bloco enquanto a área de registros permanece visível ao lado; abaixo dele aparecem linhas novas da sincronização.

A vista do quarto se aproxima da mesa. No painel, o botão “Start watcher” é selecionado e o estado da observação passa a ativo; as opções de parar e reiniciar ficam disponíveis.

A personagem aguarda diante da mesa. A área “Command logs” começa a receber linhas sobre a busca por usuários e pedidos de vínculo do GitHub.

Os registros crescem à direita enquanto a personagem anda pelo quarto. O painel de observação continua ativo e mostra consultas periódicas; a mesa e o avatar sentado permanecem ao fundo.

A personagem se aproxima da cadeira e se senta diante da mesa. Uma resposta do bot aparece no quarto, indicando que já existe um vínculo do GitHub. O painel à direita continua registrando as verificações.

A personagem envia seu nome de usuário do GitHub pelo chat. O bot pede que aguarde enquanto a solicitação é processada; novas linhas de consulta e atualização surgem nos registros do painel.

O bot confirma o vínculo da conta. A personagem se levanta e fica ao lado da mesa; as linhas recentes do painel indicam que um usuário do Habbo foi associado a uma conta do GitHub.

Abre-se a janela “Wired Creator Tools” na aba “Inspection”. A prévia mostra a personagem, e a lista de variáveis destaca “github_id” e “linked_gh”; uma seta aponta para os valores salvos.

A janela Wired é fechada. Ao clicar na própria personagem, aparecem uma mensagem no quarto e uma notificação com as estatísticas da conta: 24 PRs mesclados, nenhuma revisão e 114 commits.

Um terceiro avatar aparece sentado à mesa. A personagem clica no bloco branco com número 2; uma janela de informação do mobi se abre e uma mensagem próxima ao bloco relaciona o número aos PRs abertos para revisão.

A personagem caminha até uma estrela azul suspensa perto da parede de mobis Wired e a seleciona. Uma notificação verde informa que o repositório tem duas estrelas no GitHub; a janela de informação do mobi estrela também aparece brevemente.

A personagem retorna à mesa e seleciona outro avatar. Uma notificação azul mostra as estatísticas dessa pessoa: nenhum PR mesclado, 39 revisões e 180 commits. O painel do navegador continua exibindo os registros da sincronização.

Contribuíram com esta página