Documentação / v1
Conecte sua integração.
A autenticação de pessoas e a transferência de arquivos usam HTTP. Comandos, consultas e eventos de mensagens usam WebSocket. Os clientes Go e web no repositório implementam também a abertura das chaves e do conteúdo cifrado.
1. Prepare os acessos
- Entre no console com seu convite e crie sua conta. Guarde o código de recuperação.
- Pareie um número de teste. Conceda a chave do histórico somente às contas que devem ler o histórico.
- Para uma integração com leitura, gere um par de chaves com
wsctl service-key, cadastre a chave pública usando um convite de serviço e conceda acesso ao número. - Crie um token com o escopo necessário. Selecione a conta de serviço da integração e configure suas permissões por número.
O token aparece uma única vez. Guarde-o no armazenamento de segredos do seu sistema. Não coloque tokens em URLs, repositórios ou código público do navegador.
2. Abra o WebSocket
wss://api.wappie.thehappie.co/v1/wsO primeiro frame é hello. Use api_key para integrações ou session para uma sessão de pessoa. O servidor responde welcome antes dos demais comandos.
{"t":"hello","r":"connect","p":{"api_key":"SEU_TOKEN"}}
{"t":"devices.list","r":"numbers","p":{}}
{"t":"subscribe","r":"events","p":{"live_only":true}}t identifica o comando; r correlaciona a resposta; p contém os parâmetros. Use um identificador diferente por solicitação. Eventos espontâneos não precisam de r.
Para recuperar eventos, use since_seq com a última sequência processada. Trate os frames replay.begin, replay.end e lag; se houver atraso ou desconexão, retome a partir do último evento confirmado pela sua aplicação.
| Operação | Comandos | Requisito |
|---|---|---|
| Descobrir números | devices.list, device.info | Um acesso ao número |
| Consultar mensagens | chats.list, chat.page, message.get, message.history | Leitura e chave concedida |
| Acompanhar eventos | subscribe | Leitura dos números assinados |
| Enviar | message.send, message.send.media, message.react, message.poll.create, message.send.location, message.event.create, chat.start | Envio |
| Administrar aparelho | device.start, device.stop, device.rename, device.mode, history.backfill, group.create, group.participants.update, group.leave | Gerenciamento |
| Gerenciar tokens | apikeys.list, apikeys.create, apikeys.revoke | Pessoa proprietária ou administradora |
Referência completa dos tipos, parâmetros e respostas (TypeScript) · Contrato Go
chat.start · group.create · group.participants.update · group.leave · message.poll.create →
message.send.media · forwarded · forwarding_score →
message.react · Unicode emoji →
Erros e reconexão
{"t":"error","r":"request-id","p":{"code":"not_authorized","message":"..."}}Uma revogação, expiração ou alteração de acesso pode encerrar a conexão com código 1008. Atualize a autenticação e as permissões antes de reconectar. Use espera progressiva entre tentativas e não repita automaticamente envios cujo resultado seja desconhecido.
3. Use os endpoints HTTP
Base: https://api.wappie.thehappie.co. Operações autenticadas recebem Authorization: Bearer TOKEN. As rotas de gestão exigem sessão de pessoa; uma chave de API não administra usuários.
| Método | Caminho | Finalidade |
|---|---|---|
| POST | /v1/auth/challenge, /v1/auth/login | Obter os parâmetros de derivação e iniciar sessão |
| POST | /v1/auth/signup | Criar conta com convite e chaves geradas no cliente |
| GET | /v1/auth/me | Conta e concessões cifradas |
| GET | /v1/auth/workspaces | Espaços de trabalho da identidade |
| POST | /v1/auth/workspaces/session | Nova sessão no espaço indicado por tenant_id |
| POST | /v1/auth/workspaces/accept-invite | Aceitar um invite com conta existente |
| GET / PUT | /v1/auth/workspaces/members / members/{userID} | Listar e alterar papel e status |
| POST | /v1/auth/workspaces/invites | Convite com email e role |
| GET / PUT | /v1/auth/workspaces/devices/{deviceID}/permissions | Permissões de leitura, envio e gerenciamento |
| GET | /v1/auth/workspaces/capacity | Vagas configuradas e ocupadas |
| GET | /v1/media/{uid} | Bytes cifrados de um anexo autorizado |
| POST | /v1/upload?device=UUID&type=image | Preparar um anexo para envio; consulte o contrato de upload |
Contratos de gestão, exemplos e códigos HTTP · Cliente de autenticação e criptografia · Contrato de upload
4. Entenda as permissões
Uma identidade pode participar de vários espaços de trabalho. Os papéis, números, permissões e tokens ficam no espaço. Proprietários e administradores gerenciam aparelhos; esse papel, sozinho, não libera conversas.
Leitura exige permissão e chave concedida. Envio pode ser autorizado sem leitura. Os escopos de token read, send e full são limites cumulativos; quando o token age como uma conta de serviço, as permissões independentes dessa conta restringem cada número.
Tokens legados sem conta de serviço podem acessar conteúdo cifrado do espaço conforme o escopo. Prefira contas de serviço para restringir integrações por número. Remover a concessão impede novos acessos, mas não apaga chaves ou mensagens que alguém já baixou.
Hospedar você mesmo
O repositório inclui servidor Go, CLI, cliente Vue e instruções para PostgreSQL 18. A administração básica funciona sem o módulo comercial. A hospedagem oficial usa quatro endereços; uma instalação própria pode servir o cliente e a API na mesma origem.
Abrir guia de instalação →API v1 · piloto