{"id":51839404,"url":"https://github.com/code-chat-br/whatsapp-api-go","last_synced_at":"2026-07-23T02:30:22.972Z","repository":{"id":372380900,"uuid":"1292575405","full_name":"code-chat-br/whatsapp-api-go","owner":"code-chat-br","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-20T20:39:40.000Z","size":399,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-20T22:23:23.773Z","etag":null,"topics":["chatbot","codechat","passkeys","rest","rest-api","whatsapp","whatsapp-api","whatsapp-bot","whatsmeow","whatsmeow-bot"],"latest_commit_sha":null,"homepage":"https://docs.codechat.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-chat-br.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-07-07T16:35:01.000Z","updated_at":"2026-07-20T20:39:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/code-chat-br/whatsapp-api-go","commit_stats":null,"previous_names":["code-chat-br/whatsapp-api-go"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/code-chat-br/whatsapp-api-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-chat-br%2Fwhatsapp-api-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-chat-br%2Fwhatsapp-api-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-chat-br%2Fwhatsapp-api-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-chat-br%2Fwhatsapp-api-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-chat-br","download_url":"https://codeload.github.com/code-chat-br/whatsapp-api-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-chat-br%2Fwhatsapp-api-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35785916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","codechat","passkeys","rest","rest-api","whatsapp","whatsapp-api","whatsapp-bot","whatsmeow","whatsmeow-bot"],"created_at":"2026-07-23T02:30:18.784Z","updated_at":"2026-07-23T02:30:22.958Z","avatar_url":"https://github.com/code-chat-br.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# whatsapp-go-api\n\nAPI HTTP em Go para gerenciar instâncias do WhatsApp com Whatsmeow.\n\n![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go\u0026logoColor=white)\n[![Telegram Group](https://img.shields.io/badge/Group-Telegram-%2333C1FF)](https://t.me/codechatBR)\n[![Whatsapp Group](https://img.shields.io/badge/Group-WhatsApp-%2322BC18)](https://chat.whatsapp.com/HyO8X8K0bAo0bfaeW8bhY5)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](./LICENSE)\n\n## Visão geral\n\n`whatsapp-go-api` expõe funcionalidades do WhatsApp por meio de uma API HTTP escrita em Go. O projeto usa [Whatsmeow](https://github.com/tulir/whatsmeow) para a integração com o WhatsApp e [Fiber v3](https://github.com/gofiber/fiber) para o servidor HTTP.\n\nA aplicação permite criar e autenticar múltiplas instâncias, conectar uma sessão por QR Code ou código de pareamento, consultar estado de conexão, enviar mensagens, operar recursos de chat e grupo, persistir dados no PostgreSQL e encaminhar eventos por webhook.\n\nEste projeto não usa a API oficial do WhatsApp.\n\n## Principais recursos\n\n- Gerenciamento de instâncias com token próprio por instância.\n- Autenticação administrativa global por header de API key.\n- Conexão por QR Code.\n- Conexão por código de pareamento com telefone.\n- Fluxo de pareamento por passkey.\n- Estado de conexão, logout e remoção de instância.\n- Envio de texto, link com preview, mídia por base64, mídia por upload, áudio no formato WhatsApp, contato, localização e reação.\n- Opções de mensagem para presença, delay, citação e menções.\n- Operações de chat para validação de números, leitura, arquivamento, exclusão, edição, foto de perfil, rejeição de chamada e download de mídia.\n- Operações de grupo para criação, foto, convite, revogação de convite, participantes e saída.\n- Webhooks por instância e webhook global opcional.\n- Persistência opcional de mensagens, atualizações de mensagem e contatos.\n- Persistência de sessões Whatsmeow em PostgreSQL ou SQLite.\n- Reconexão automática de sessões persistidas no startup.\n- Migrations SQL internas para o banco principal.\n- Especificação OpenAPI estática para endpoints de mensagem.\n\n## Tecnologias utilizadas\n\n- Go `1.26`.\n- Fiber `v3.4.0`.\n- Whatsmeow `v0.0.0-20260630180629-b572e5bcb92b`.\n- PostgreSQL via `pgx/v5`.\n- SQLite via `go-sqlite3` para store de sessão Whatsmeow.\n- `sqlc` para código de acesso a dados já gerado no repositório.\n- `zerolog` para logs.\n- `go-playground/validator` para validação.\n- `golang-jwt/jwt/v5` para tokens por instância.\n- `air` como ferramenta opcional de desenvolvimento, com `.air.toml` já presente.\n\n## Estrutura do projeto\n\n```text\n.\n|-- cmd/\n|   |-- api/\n|   |-- migrate/\n|   `-- webhook-docs/\n|-- docs/\n|-- internal/\n|   |-- app/\n|   |-- authentication/\n|   |-- chat/\n|   |-- config/\n|   |-- database/\n|   |-- group/\n|   |-- http/\n|   |-- instance/\n|   |-- message/\n|   |-- webhook/\n|   `-- whatsapp/\n|-- tests/\n|-- .air.toml\n|-- .env.dev\n|-- go.mod\n|-- go.sum\n`-- sqlc.yaml\n```\n\nExecutáveis em `cmd/`:\n\n- `cmd/api`: inicia a API HTTP.\n- `cmd/migrate`: executa migrations do banco principal e inicializa as migrations da store Whatsmeow.\n- `cmd/webhook-docs`: regenera `docs/webhooks.md` a partir do contrato interno de webhooks.\n\n## Pré-requisitos\n\nPara desenvolvimento local:\n\n- Git, caso ainda precise clonar o projeto.\n- Go compatível com `go 1.26`.\n- PostgreSQL acessível pela variável `DATABASE_URL`.\n- Opcionalmente Air para hot reload.\n- Opcionalmente SQLite quando `WHATSAPP_SESSION_STORE=sqlite`.\n\nPara produção:\n\n- Go ou um binário compilado da API.\n- PostgreSQL para o banco principal.\n- Store de sessão Whatsmeow em PostgreSQL ou SQLite, conforme configuração.\n- Variáveis de ambiente seguras para autenticação e conexão.\n\nPara Docker:\n\n- Docker Engine ou Docker Desktop com `docker compose`.\n- BuildKit/Buildx para builds multiplataforma.\n- PostgreSQL acessível pela rede usada pelo container.\n- FFmpeg não precisa ser instalado no host quando a API roda pela imagem Docker; a imagem final já contém `ffmpeg` e `ffprobe`.\n\n## Instalação do Go\n\nInstale o Go pela página oficial: [go.dev/dl](https://go.dev/dl/).\n\n- Windows: use o instalador `.msi` oficial e abra um novo terminal após a instalação.\n- macOS: use o pacote oficial `.pkg` ou um gerenciador de pacotes de sua preferência.\n- Linux: use o pacote oficial ou o repositório da sua distribuição.\n\nValide a instalação:\n\n```bash\ngo version\n```\n\nO diretório de binários do Go precisa estar no `PATH` para comandos instalados com `go install`. Versões anteriores à diretiva `go 1.26` do `go.mod` não são suportadas por este projeto.\n\n## Instalação do Air para desenvolvimento\n\nO projeto possui `.air.toml`, então o Air pode ser usado como dependência opcional de desenvolvimento:\n\n```bash\ngo install github.com/air-verse/air@latest\n```\n\nO binário normalmente é instalado em:\n\n```bash\ngo env GOPATH\n```\n\nNo Linux ou macOS, se `air` não estiver no `PATH`, adicione o diretório de binários do Go:\n\n```bash\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\n```\n\nDepois execute:\n\n```bash\nair\n```\n\nA configuração atual compila `./cmd/api/main.go` e gera o binário temporário em `tmp/main.exe`.\n\n## Instalação do Docker\n\nO repositório contém `Dockerfile`, `docker-compose.yml`, `.env.docker.example` e `scripts/build-and-push.sh` para executar e publicar a API em container.\n\nLinks oficiais:\n\n- [Docker Engine](https://docs.docker.com/engine/install/)\n  - [Script de instalação](https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script)\n- [Docker Desktop para Windows e macOS](https://docs.docker.com/desktop/)\n- [Instalação em Linux](https://docs.docker.com/engine/install/#server)\n\nValide a instalação:\n\n```bash\ndocker version\ndocker compose version\n```\n\nUse `docker compose`; não use o comando legado `docker-compose`.\n\n## Instalação local da API\n\n### Clonar o projeto\n\n```\ngit clone https://github.com/code-chat-br/whatsapp-api-go.git\n```\n\n```bash\ncd whatsapp-go-api\n```\n\n### Instalar dependências\n\n```bash\ngo mod download\ngo mod verify\n```\n\n### Configurar variáveis de ambiente\n\nPara execução local fora de Docker, a aplicação carrega `.env`. Use o arquivo de referência existente:\n\n```bash\ncp .env.dev .env\n```\n\nNo Windows PowerShell:\n\n```powershell\nCopy-Item .env.dev .env\n```\n\nVariáveis mínimas para iniciar a API:\n\n- `DOCKER_ENV=false`\n- `SERVER_PORT`\n- `DATABASE_URL`\n- `AUTHENTICATION_JWT_EXPIRES_IN`\n- `AUTHENTICATION_JWT_SECRET`\n- `AUTHENTICATION_GLOBAL_AUTH_TOKEN`\n- `QRCODE_LIMIT`\n- `QRCODE_EXPIRATION_TIME`\n- `QRCODE_LIGHT_COLOR`\n- `QRCODE_DARK_COLOR`\n- `WHATSAPP_AUTO_RECONNECT`\n- `WHATSAPP_STARTUP_RECONNECT_CONCURRENCY`\n- `WHATSAPP_CONNECT_TIMEOUT`\n- `WHATSAPP_RECONNECT_INITIAL_DELAY`\n- `WHATSAPP_RECONNECT_MAX_DELAY`\n- `WHATSAPP_PROFILE_PICTURE_TIMEOUT`\n\nConsulte a [documentação de variáveis de ambiente](./docs/environment.md#environment-configuration) para a lista completa.\n\n### Preparar o banco de dados\n\nO banco principal da API é PostgreSQL, configurado por `DATABASE_URL`. Crie o banco antes de iniciar a aplicação, antes de executar migrations.\n\n```SQL\nCREATE DATABASE WHATSAPP;\n```\n\nConfigure a URL no `.env`, por exemplo:\n\n```dotenv\nDATABASE_URL=\"postgres://postgres:postgres@postgres.local:5432/whatsapp?sslmode=disable\"\n```\n\nA store de sessão Whatsmeow é escolhida por `WHATSAPP_SESSION_STORE`:\n\n- `postgres`: usa `WHATSAPP_SESSION_POSTGRES_URL` quando preenchida, ou `DATABASE_URL` quando vazia.\n- `sqlite`: usa `WHATSAPP_SESSION_SQLITE_DSN`, com valor padrão compatível com `file:./data/whatsmeow.db?_foreign_keys=on`.\n\n### Executar migrations\n\nA API executa as migrations no startup. Também existe um comando dedicado:\n\n```bash\ngo run ./cmd/migrate\n```\n\nAs migrations do banco principal ficam em `internal/database/migrations` e registram o estado em `schema_migrations`. Há arquivos `.down.sql`, mas o código atual não expõe comando de rollback nem comando de status.\n\nLeia mais em [Migrations](./docs/migrations.md#migrations).\n\n### Iniciar a aplicação\n\n```bash\ngo run ./cmd/api\n```\n\nCom Air:\n\n```bash\nair\n```\n\nPor padrão, quando `SERVER_PORT` não é alterado, a API escuta em:\n\n```text\nhttp://localhost:8084\n```\n\nRotas públicas de saúde:\n\n```text\nGET /health\nGET /ready\n```\n\n### Compilar\n\nLinux ou macOS:\n\n```bash\ngo build -o ./api ./cmd/api\n```\n\nWindows PowerShell:\n\n```powershell\ngo build -o .\\api.exe .\\cmd\\api\n```\n\n## Docker\n\nO container executa a API pelo entrypoint real `./cmd/api`, compilado como `/app/codechat-api`. A imagem final usa Alpine, instala `ffmpeg` e `ffprobe`, define `DOCKER_ENV=true`, roda como usuário não-root `app` e mantém as migrations em `/app/internal/database/migrations`, porque o runner atual lê `internal/database/migrations` do filesystem.\n\n[Imagem oficial](https://hub.docker.com/repository/docker/codechat/whatsapp-go-api/general) no DockerHub.\n\n### Execução direta\n\n```bash\ndocker run --rm \\\n  --env-file .env \\\n  -p 8084:8084 \\\n  codechat/whatsapp-go-api:latest\n```\n\nNo Docker, mantenha `DOCKER_ENV=true`. A porta interna padrão é `8084`, lida de `SERVER_PORT`, e as rotas públicas de saúde são:\n\n```text\nGET /health\nGET /ready\n```\n\n### Docker Compose\n\nCrie um arquivo `.env` a partir do exemplo e preencha as variáveis reais. Não versiona secrets.\n\n```bash\ncp .env.docker.example .env\ndocker compose up -d\n```\n\nLogs:\n\n```bash\ndocker compose logs -f codechat-api\n```\n\nEncerrar:\n\n```bash\ndocker compose down\n```\n\nO Compose não publica a porta no host por padrão; ele usa `expose` para o Traefik. Para teste local direto sem Traefik, use `docker run -p 8084:8084` ou um arquivo override próprio com `ports`.\n\n### Traefik\n\nCrie a rede externa somente se ela ainda não existir:\n\n```bash\ndocker network create public_network\n```\n\nO serviço entra nas redes `codechat_network` e `traefik_network`. A rede externa é parametrizada por:\n\n```env\nTRAEFIK_NETWORK=public_network\n```\n\nRegra padrão:\n\n```text\nHost(`api.codechat.local`)\n```\n\nVariáveis principais:\n\n```env\nAPI_HOST=api.codechat.local\nTRAEFIK_ENTRYPOINT=websecure\nTRAEFIK_TLS=true\nTRAEFIK_CERT_RESOLVER=letsencrypt\n```\n\nA porta configurada no load balancer Traefik é a mesma da aplicação:\n\n```text\ntraefik.http.services.codechat-api.loadbalancer.server.port=8084\n```\n\nO arquivo base não adiciona labels vazias para middlewares ou `serversTransport`. Quando precisar referenciar middlewares externos, adicione-os em um override de produção, por exemplo:\n\n```yaml\nservices:\n  codechat-api:\n    labels:\n      - \"traefik.http.routers.codechat-api.middlewares=compress@file,cors@file\"\n      - \"traefik.http.services.codechat-api.loadbalancer.serverstransport=sse_transport@file\"\n```\n\nNão configure timeouts no Traefik que encerrem conexões persistentes, porque a API usa conexões HTTP longas durante fluxos de WhatsApp e uploads.\n\n### Dependência do FFmpeg\n\nA imagem Docker contém:\n\n```text\n/usr/bin/ffmpeg\n/usr/bin/ffprobe\n```\n\nVariáveis usadas dentro do container:\n\n```env\nFFMPEG_PATH=/usr/bin/ffmpeg\nFFPROBE_PATH=/usr/bin/ffprobe\nTMPDIR=/app/tmp\n```\n\nFora do Docker, se `FFMPEG_PATH` e `FFPROBE_PATH` não forem definidas, a aplicação continua procurando `ffmpeg` e `ffprobe` no `PATH`.\n\nVerificar no container:\n\n```bash\ndocker compose exec codechat-api ffmpeg -version\ndocker compose exec codechat-api ffprobe -version\n```\n\nInstalação fora do Docker:\n\nUbuntu e Debian:\n\n```bash\nsudo apt-get update\nsudo apt-get install -y ffmpeg\n```\n\nAlpine:\n\n```bash\napk add --no-cache ffmpeg\n```\n\nmacOS:\n\n```bash\nbrew install ffmpeg\n```\n\nWindows:\n\n```powershell\nwinget install --id Gyan.FFmpeg\n```\n\nValide:\n\n```bash\nffmpeg -version\nffprobe -version\n```\n\n## Configuração\n\nAs variáveis estão agrupadas nas seguintes áreas:\n\n- Servidor HTTP: porta e modo de execução.\n- Logs: nível de log.\n- Banco principal: URL e persistência opcional de mensagens, atualizações e contatos.\n- Autenticação: segredo JWT, expiração e token global.\n- WhatsApp: QR Code, dispositivo vinculado, timeouts e reconexão.\n- Sessões Whatsmeow: backend `postgres` ou `sqlite`.\n- Webhooks: URL global e ativação global.\n- Processamento de mensagens: workers, fila e timeouts.\n\nConsulte a [documentação de variáveis de ambiente](./docs/environment.md#docker-execution).\n\n## Documentação\n\nA documentação técnica completa está disponível em [`/docs`](./docs/).\n\n- [Variáveis de ambiente](./docs/environment.md#environment-configuration): descreve execução local, execução em Docker e configuração da store de sessões Whatsmeow.\n- [Migrations](./docs/migrations.md#migrations): resume o comando dedicado de migrations e o comportamento no startup.\n- [Pareamento por Passkey](./docs/passkey-pairing.md#pareamento-por-passkey-no-whatsapp): detalha endpoints, headers, estados e limitações do fluxo de passkey.\n- [Envio de mensagens](./docs/send-messages.md#send-messages): documenta corpos, respostas, opções, fila, erros e limitações dos endpoints de mensagem.\n- [Webhooks](./docs/webhooks.md#webhooks): descreve configuração, envelope, headers, entrega e payloads dos eventos suportados.\n- [OpenAPI](./docs/openapi.yaml): especificação OpenAPI estática dos endpoints de envio de mensagem.\n\n## Autenticação\n\nA API usa dois escopos de autenticação.\n\nAutenticação administrativa global:\n\n- Protege criação e listagem de instâncias.\n- Usa o valor de `AUTHENTICATION_GLOBAL_AUTH_TOKEN`.\n- Headers aceitos: `apikey`, `x-api-key` e `apiKey`.\n- Se mais de um desses headers for enviado, os valores precisam ser iguais.\n\nExemplo:\n\n```http\napikey: \u003cGLOBAL_API_KEY\u003e\n```\n\nAutenticação por instância:\n\n- Protege conexão, estado, logout, remoção, token refresh, webhooks, mensagens, chats e grupos.\n- Usa JWT gerado na criação da instância.\n- O token precisa pertencer ao `:instanceName` da rota.\n\nExemplo:\n\n```http\nAuthorization: Bearer \u003cINSTANCE_TOKEN\u003e\n```\n\n## Uso básico da API\n\nOs exemplos abaixo usam dados fictícios e assumem a API em `http://localhost:8084`.\n\n### 1. Criar uma instância\n\n```bash\ncurl -X POST \"http://localhost:8084/instance/create\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"apikey: \u003cGLOBAL_API_KEY\u003e\" \\\n  -d '{\n    \"instanceName\": \"minha-instancia\",\n    \"description\": \"Instância de desenvolvimento\"\n  }'\n```\n\nA resposta inclui `auth.token`. Use esse valor como `\u003cINSTANCE_TOKEN\u003e`.\n\n### 2. Conectar por QR Code\n\n```bash\ncurl -X GET \"http://localhost:8084/instance/connect/minha-instancia\" \\\n  -H \"Authorization: Bearer \u003cINSTANCE_TOKEN\u003e\"\n```\n\nA resposta contém o código e o QR Code em base64 quando a instância ainda não está conectada.\n\n### 3. Conectar por código de pareamento\n\n```bash\ncurl -X GET \"http://localhost:8084/instance/connect/minha-instancia/code/5511999999999\" \\\n  -H \"Authorization: Bearer \u003cINSTANCE_TOKEN\u003e\"\n```\n\n### 4. Consultar o status da conexão\n\n```bash\ncurl -X GET \"http://localhost:8084/instance/connectionState/minha-instancia\" \\\n  -H \"Authorization: Bearer \u003cINSTANCE_TOKEN\u003e\"\n```\n\n### 5. Enviar uma mensagem de texto\n\n```bash\ncurl -X POST \"http://localhost:8084/message/sendText/minha-instancia\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer \u003cINSTANCE_TOKEN\u003e\" \\\n  -d '{\n    \"number\": \"5511999999999\",\n    \"textMessage\": {\n      \"text\": \"Olá!\"\n    }\n  }'\n```\n\n### 6. Configurar um webhook da instância\n\n```bash\ncurl -X PUT \"http://localhost:8084/webhook/set/minha-instancia\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer \u003cINSTANCE_TOKEN\u003e\" \\\n  -d '{\n    \"url\": \"https://example.com/webhooks/whatsapp\",\n    \"enabled\": true,\n    \"events\": {\n      \"qrcodeUpdated\": true,\n      \"connectionUpdated\": true,\n      \"messagesUpsert\": true,\n      \"sendMessage\": true\n    }\n  }'\n```\n\n## OpenAPI\n\nO projeto possui especificação OpenAPI estática em [docs/openapi.yaml](./docs/openapi.yaml). O servidor HTTP atual não registra rota de Swagger, Scalar ou Redoc.\n\n## Envio de mensagens\n\nEndpoints de mensagem implementados:\n\n- `POST /message/sendText/:instanceName`\n- `POST /message/sendLink/:instanceName`\n- `POST /message/sendMedia/:instanceName`\n- `POST /message/sendMediaFile/:instanceName`\n- `POST /message/sendWhatsAppAudio/:instanceName`\n- `POST /message/sendWhatsAppAudioFile/:instanceName`\n- `POST /message/sendContact/:instanceName`\n- `POST /message/sendLocation/:instanceName`\n- `POST /message/sendReaction/:instanceName`\n\nAs opções aceitas incluem `delay`, `presence`, `quotedMessageId`, `quotedMessage`, `externalAttributes` e `mentionAll`. Para detalhes de payload, respostas e limitações, consulte [Envio de mensagens](./docs/send-messages.md).\n\n## Webhooks\n\nO webhook por instância é configurado por:\n\n```text\nPUT /webhook/set/:instanceName\nGET /webhook/find/:instanceName\n```\n\nO corpo de configuração aceita:\n\n- `url`: URL HTTP ou HTTPS de destino.\n- `enabled`: habilita ou desabilita a entrega da instância.\n- `events`: objeto com flags por evento, usando campos como `qrcodeUpdated`, `connectionUpdated`, `messagesUpsert` e `sendMessage`.\n\nTambém existe webhook global opcional por `WEBHOOK_GLOBAL_URL` e `WEBHOOK_GLOBAL_ENABLED`.\n\nO envelope geral entregue é:\n\n```json\n{\n  \"event\": \"messages.upsert\",\n  \"instance\": {\n    \"id\": 1,\n    \"name\": \"minha-instancia\",\n    \"connectionStatus\": \"ONLINE\",\n    \"ownerJid\": \"5511999999999@s.whatsapp.net\",\n    \"externalAttributes\": {}\n  },\n  \"data\": {},\n  \"timestamp\": \"2026-07-07T12:00:00Z\"\n}\n```\n\nHeaders enviados:\n\n- `Content-Type`\n- `User-Agent`\n- `x-request-id`\n- `x-owner-jid`\n- `x-instance-name`\n- `x-instance-id`\n- `x-webhook-event`\n\nA entrega é assíncrona por fila em memória. Falhas são registradas em log; o código atual não implementa retry persistente.\n\nConsulte [Webhooks](./docs/webhooks.md) para o mapa completo de eventos e payloads.\n\n## Persistência de sessões\n\nAs sessões e dispositivos do WhatsApp são persistidos pela `sqlstore` do Whatsmeow.\n\nBackend configurável:\n\n```dotenv\nWHATSAPP_SESSION_STORE=\"postgres\"\n```\n\nValores aceitos:\n\n- `postgres`: usa `WHATSAPP_SESSION_POSTGRES_URL` ou, quando vazia, `DATABASE_URL`.\n- `sqlite`: usa `WHATSAPP_SESSION_SQLITE_DSN`.\n\nQuando `WHATSAPP_AUTO_RECONNECT=true`, o startup tenta restaurar as sessões persistidas. O número de restaurações concorrentes é controlado por `WHATSAPP_STARTUP_RECONNECT_CONCURRENCY`.\n\nConsulte [Variáveis de ambiente](./docs/environment.md).\n\n## Passkey\n\nO projeto implementa endpoints de pareamento por passkey:\n\n```text\nPOST /instance/connect/:instanceName/passkey/challenge\nPOST /instance/connect/:instanceName/passkey/assertion\n```\n\nO fluxo cria um challenge temporário para a instância e espera a assertion do cliente. Ele depende da mesma autenticação por instância via `Authorization: Bearer \u003cINSTANCE_TOKEN\u003e`.\n\nConsulte [Pareamento por Passkey](./docs/passkey-pairing.md) para requisitos, estados, erros e limitações.\n\n## Comandos de desenvolvimento\n\n```bash\ngo mod download\ngo mod verify\ngo run ./cmd/migrate\ngo run ./cmd/api\ngo run ./cmd/webhook-docs\ngo test ./...\ngo vet ./...\ngo build ./...\nair\n```\n\nNão há `Makefile` ou `Taskfile` no repositório atual.\n\n## Testes\n\nExecute:\n\n```bash\ngo test ./...\n```\n\nAlguns testes e caminhos de inicialização dependem de configuração válida de ambiente e PostgreSQL quando exercitam banco real. A suíte existente também possui testes unitários para configuração, HTTP, mensagens, webhooks e WhatsApp.\n\n## Solução de problemas\n\n- Go em versão incompatível: confirme `go version` e use uma versão compatível com `go 1.26`.\n- `air: command not found`: instale com `go install github.com/air-verse/air@latest` e adicione `$(go env GOPATH)/bin` ao `PATH`.\n- `.env` ausente em execução local: copie `.env.dev` para `.env`.\n- `DATABASE_URL` ausente ou inválida: confira a URL do PostgreSQL e o parâmetro `sslmode` quando necessário.\n- PostgreSQL indisponível: valide host, porta, credenciais e existência do banco.\n- Migrations pendentes ou falhando: execute `go run ./cmd/migrate` e confira a tabela `schema_migrations`.\n- Porta em uso: altere `SERVER_PORT` no `.env`.\n- Sessão não reconectada: confirme `WHATSAPP_AUTO_RECONNECT=true`, store de sessão correta e registros de estado da instância.\n- QR Code expirado: solicite novamente `GET /instance/connect/:instanceName`.\n- Token recusado: confirme se o header é `Authorization: Bearer \u003cINSTANCE_TOKEN\u003e` e se o token pertence ao mesmo `instanceName`.\n- Webhook sem entrega: confira `enabled`, `events`, URL HTTP/HTTPS e logs de falha da fila.\n\n## Segurança e uso responsável\n\nEste projeto não é afiliado, patrocinado ou endossado pelo WhatsApp ou pela Meta. Ele usa uma integração não oficial via Whatsmeow, e alterações no protocolo do WhatsApp podem causar interrupções.\n\nO usuário é responsável por cumprir leis, termos de serviço e políticas aplicáveis. Não use a API para spam, abuso ou envio de mensagens sem consentimento.\n\nCuidados operacionais:\n\n- Não envie tokens, chaves, `.env` ou bancos de sessão ao Git.\n- Use valores fortes para `AUTHENTICATION_JWT_SECRET` e `AUTHENTICATION_GLOBAL_AUTH_TOKEN`.\n- Evite registrar tokens, números completos, conteúdos de mensagem ou dados sensíveis em logs.\n- Proteja o acesso HTTP com rede privada, proxy autenticado ou controles equivalentes em produção.\n\n## Licença\n\nEste projeto é disponibilizado sob a licença [GNU Affero General Public License v3.0](./LICENSE), utilizando o identificador SPDX `AGPL-3.0-only`.\n\nO uso comercial é permitido sob os termos da AGPL. Organizações que necessitem manter modificações privadas, incorporar o projeto em software proprietário ou utilizar termos diferentes podem solicitar uma [licença comercial separada](./LICENSE-COMMERCIAL.md).\n\nComponentes de terceiros permanecem sujeitos às suas respectivas licenças. Consulte também os arquivos [NOTICE](./NOTICE) e [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).\n\nEste projeto não é oficial, não é afiliado à Meta ou ao WhatsApp, e o usuário é responsável por cumprir leis, termos de serviço e políticas aplicáveis.\n\n## Contribuição\n\nLeia [CONTRIBUTING.md](./CONTRIBUTING.md) antes de enviar contribuições. Contribuições externas poderão exigir aceite do [CLA.md](./CLA.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-chat-br%2Fwhatsapp-api-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-chat-br%2Fwhatsapp-api-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-chat-br%2Fwhatsapp-api-go/lists"}