codechat/whatsapp-go-api

By codechat

•Updated about 11 hours ago

API for communication with whatsapp.

Image

Integration & delivery

Message queues

API management

101

Overview Tags

codechat/whatsapp-go-api repository overview

⁠CodeChat WhatsApp Go API

API HTTP escrita em Go para gerenciar múltiplas instâncias do WhatsApp utilizando o Whatsmeow⁠.

Este projeto utiliza uma integração não oficial com o WhatsApp. Não possui afiliação, patrocínio ou aprovação da Meta ou do WhatsApp.

⁠Visão geral

A imagem codechat/whatsapp-api-go disponibiliza uma API HTTP para:

Criar e administrar múltiplas instâncias do WhatsApp.
Conectar sessões por QR Code.
Conectar sessões por código de pareamento.
Realizar pareamento por passkey.
Enviar textos, links, mídias, áudios, contatos, localizações e reações.
Citar mensagens e realizar menções.
Consultar números, chats, grupos e informações de perfil.
Entregar eventos por webhook.
Persistir mensagens, contatos e atualizações.
Persistir sessões do Whatsmeow em PostgreSQL ou SQLite.
Reconectar automaticamente sessões persistidas.
Processar áudios e mídias utilizando FFmpeg.

⁠Imagem

codechat/whatsapp-api-go

⁠Plataformas suportadas

As imagens multiplataforma são publicadas para:

linux/amd64
linux/arm64

⁠Tags

Recomenda-se utilizar uma tag de versão específica em produção:

docker pull codechat/whatsapp-api-go:v1.0.0

Para obter a versão estável mais recente publicada:

docker pull codechat/whatsapp-api-go:latest

Evite depender exclusivamente de latest em ambientes de produção. Tags versionadas tornam atualizações e rollbacks previsíveis.

⁠Recursos da imagem

A imagem Docker:

Usa Alpine Linux como base de execução.
Executa a aplicação como usuário não-root.
Define DOCKER_ENV=true.
Inclui ffmpeg e ffprobe.
Inclui as migrations SQL utilizadas pela aplicação.
Executa o binário compilado da API em Go.
Expõe a porta configurada em SERVER_PORT.
Possui labels OCI com versão, commit, data de build e repositório.
Suporta execução atrás de Traefik, Nginx ou outro proxy reverso.

Caminhos disponíveis no container:

/app/codechat-api
/app/internal/database/migrations
/usr/bin/ffmpeg
/usr/bin/ffprobe
/app/tmp

⁠Início rápido com Docker Compose

Crie um arquivo docker-compose.yml:

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped

    environment:
      POSTGRES_DB: whatsapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: change-me

    volumes:
      - postgres_data:/var/lib/postgresql/data

    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U postgres -d whatsapp"
        ]
      interval: 10s
      timeout: 5s
      retries: 10

  whatsapp-api:
    image: codechat/whatsapp-api-go:latest
    restart: unless-stopped

    depends_on:
      postgres:
        condition: service_healthy

    env_file:
      - .env

    environment:
      DOCKER_ENV: "true"
      SERVER_PORT: "8084"
      DATABASE_URL: "postgres://postgres:change-me@postgres:5432/whatsapp?sslmode=disable"
      WHATSAPP_SESSION_STORE: "postgres"

    ports:
      - "8084:8084"

volumes:
  postgres_data:

Crie o arquivo .env com as configurações da aplicação.

Use como referência o arquivo mantido no repositório:

curl -fsSL \
  https://raw.githubusercontent.com/code-chat-br/whatsapp-api-go/main/.env.docker.example \
  -o .env

Defina secrets fortes antes de iniciar:

AUTHENTICATION_JWT_SECRET=change-this-jwt-secret
AUTHENTICATION_GLOBAL_AUTH_TOKEN=change-this-global-token

Inicie os containers:

docker compose up -d

Acompanhe os logs:

docker compose logs -f whatsapp-api

Verifique a API:

curl http://localhost:8084/health
curl http://localhost:8084/ready

⁠Execução com `docker run`

A API exige acesso ao PostgreSQL principal. Crie ou utilize uma rede Docker onde o banco esteja disponível.

Exemplo:

docker network create whatsapp-network

Execute o PostgreSQL:

docker run -d \
  --name whatsapp-postgres \
  --network whatsapp-network \
  -e POSTGRES_DB=whatsapp \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=change-me \
  -v whatsapp_postgres_data:/var/lib/postgresql/data \
  postgres:17-alpine

Execute a API:

docker run -d \
  --name whatsapp-api \
  --network whatsapp-network \
  --restart unless-stopped \
  --env-file .env \
  -e DOCKER_ENV=true \
  -e SERVER_PORT=8084 \
  -e DATABASE_URL="postgres://postgres:change-me@whatsapp-postgres:5432/whatsapp?sslmode=disable" \
  -e WHATSAPP_SESSION_STORE=postgres \
  -p 8084:8084 \
  codechat/whatsapp-api-go:latest

Logs:

docker logs -f whatsapp-api

⁠Variáveis de ambiente

A configuração completa está documentada em:

⁠Servidor

Variável	Descrição
`DOCKER_ENV`	Indica execução em container. Use `true`.
`SERVER_PORT`	Porta HTTP da aplicação.
`LOG_LEVEL`	Nível dos logs da aplicação.

Exemplo:

DOCKER_ENV=true
SERVER_PORT=8084
LOG_LEVEL=info

⁠Banco principal

Variável	Descrição
`DATABASE_URL`	URL de conexão com o PostgreSQL principal.
`DATABASE_SAVE_DATA_NEW_MESSAGE`	Salva novas mensagens no banco.
`DATABASE_SAVE_MESSAGE_UPDATE`	Salva atualizações de mensagens.
`DATABASE_SAVE_DATA_CONTACTS`	Salva dados de contatos.

Exemplo:

DATABASE_URL=postgres://postgres:password@postgres:5432/whatsapp?sslmode=disable

DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=false
DATABASE_SAVE_DATA_CONTACTS=false

⁠Autenticação

Variável	Descrição
`AUTHENTICATION_JWT_SECRET`	Segredo utilizado para gerar tokens de instância.
`AUTHENTICATION_JWT_EXPIRES_IN`	Tempo de expiração dos tokens.
`AUTHENTICATION_GLOBAL_AUTH_TOKEN`	Token administrativo global.

Nunca utilize os valores de exemplo em produção.

⁠Persistência das sessões

Variável	Descrição
`WHATSAPP_SESSION_STORE`	Backend da sessão: `postgres` ou `sqlite`.
`WHATSAPP_SESSION_POSTGRES_URL`	PostgreSQL exclusivo para sessões.
`WHATSAPP_SESSION_SQLITE_DSN`	Caminho e configuração do SQLite.
`WHATSAPP_AUTO_RECONNECT`	Reconecta sessões no startup.
`WHATSAPP_STARTUP_RECONNECT_CONCURRENCY`	Limite de reconexões simultâneas.

Quando WHATSAPP_SESSION_STORE=postgres:

A API usa WHATSAPP_SESSION_POSTGRES_URL, quando preenchida.
Quando essa variável estiver vazia, a API usa DATABASE_URL.

Exemplo:

WHATSAPP_SESSION_STORE=postgres
WHATSAPP_SESSION_POSTGRES_URL=
WHATSAPP_AUTO_RECONNECT=true

⁠Webhook global

Variável	Descrição
`WEBHOOK_GLOBAL_ENABLED`	Ativa o webhook global.
`WEBHOOK_GLOBAL_URL`	URL que receberá eventos globais.

Exemplo:

WEBHOOK_GLOBAL_ENABLED=true
WEBHOOK_GLOBAL_URL=https://example.com/webhooks/whatsapp

⁠FFmpeg

A imagem já contém FFmpeg e FFprobe.

Valores recomendados:

FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe
TMPDIR=/app/tmp

Valide dentro do container:

docker exec whatsapp-api ffmpeg -version
docker exec whatsapp-api ffprobe -version

⁠Sessões com SQLite

Para utilizar SQLite como store das sessões:

WHATSAPP_SESSION_STORE=sqlite
WHATSAPP_SESSION_SQLITE_DSN=file:/app/data/whatsmeow.db?_foreign_keys=on

Monte um volume persistente:

services:
  whatsapp-api:
    image: codechat/whatsapp-api-go:latest

    volumes:
      - whatsapp_sessions:/app/data

volumes:
  whatsapp_sessions:

Sem volume, o banco SQLite será perdido quando o container for removido.

Certifique-se de que o usuário não-root da imagem tenha permissão de escrita no diretório montado.

⁠Health checks

A API possui duas rotas públicas:

GET /health
GET /ready

Exemplo de health check no Compose:

healthcheck:
  test:
    [
      "CMD",
      "wget",
      "--quiet",
      "--tries=1",
      "--spider",
      "http://127.0.0.1:8084/health"
    ]
  interval: 30s
  timeout: 5s
  retries: 5
  start_period: 20s

⁠Uso básico

Os exemplos abaixo assumem que a API está disponível em:

http://localhost:8084

⁠Criar uma instância

curl -X POST "http://localhost:8084/instance/create" \
  -H "Content-Type: application/json" \
  -H "apikey: <GLOBAL_API_KEY>" \
  -d '{
    "instanceName": "minha-instancia",
    "description": "Instância principal"
  }'

A resposta contém o token da instância em auth.token.

⁠Conectar por QR Code

curl -X GET \
  "http://localhost:8084/instance/connect/minha-instancia" \
  -H "Authorization: Bearer <INSTANCE_TOKEN>"

⁠Conectar por código de pareamento

curl -X GET \
  "http://localhost:8084/instance/connect/minha-instancia/code/5511999999999" \
  -H "Authorization: Bearer <INSTANCE_TOKEN>"

⁠Consultar estado da conexão

curl -X GET \
  "http://localhost:8084/instance/connectionState/minha-instancia" \
  -H "Authorization: Bearer <INSTANCE_TOKEN>"

⁠Enviar mensagem de texto

curl -X POST \
  "http://localhost:8084/message/sendText/minha-instancia" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <INSTANCE_TOKEN>" \
  -d '{
    "number": "5511999999999",
    "textMessage": {
      "text": "Olá!"
    }
  }'

⁠Endpoints de mensagem

A API implementa os seguintes endpoints:

POST /message/sendText/:instanceName
POST /message/sendLink/:instanceName
POST /message/sendMedia/:instanceName
POST /message/sendMediaFile/:instanceName
POST /message/sendWhatsAppAudio/:instanceName
POST /message/sendWhatsAppAudioFile/:instanceName
POST /message/sendContact/:instanceName
POST /message/sendLocation/:instanceName
POST /message/sendReaction/:instanceName

As mensagens podem utilizar opções como:

Delay antes do envio.
Presença de digitação ou gravação.
Citação por ID da mensagem.
Citação por payload.
Menções individuais.
Menção de todos os participantes.
Atributos externos.

Consulte a documentação completa:

docs/send-messages.md⁠

⁠Webhooks

O webhook de uma instância pode ser configurado por:

PUT /webhook/set/:instanceName
GET /webhook/find/:instanceName

Exemplo:

curl -X PUT \
  "http://localhost:8084/webhook/set/minha-instancia" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <INSTANCE_TOKEN>" \
  -d '{
    "url": "https://example.com/webhooks/whatsapp",
    "enabled": true,
    "events": {
      "qrcodeUpdated": true,
      "connectionUpdated": true,
      "messagesUpsert": true,
      "sendMessage": true
    }
  }'

Envelope geral:

{
  "event": "messages.upsert",
  "instance": {
    "id": 1,
    "name": "minha-instancia",
    "connectionStatus": "ONLINE",
    "ownerJid": "[email protected]",
    "externalAttributes": {}
  },
  "data": {},
  "timestamp": "2026-07-07T12:00:00Z"
}

A entrega atual é realizada de forma assíncrona por fila em memória. Falhas são registradas em log, mas não existe retry persistente.

⁠Uso com Traefik

Exemplo básico:

services:
  whatsapp-api:
    image: codechat/whatsapp-api-go:latest
    restart: unless-stopped

    env_file:
      - .env

    networks:
      - traefik_public
      - whatsapp_internal

    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik_public"

      - "traefik.http.routers.whatsapp-api.rule=Host(`api.example.com`)"
      - "traefik.http.routers.whatsapp-api.entrypoints=websecure"
      - "traefik.http.routers.whatsapp-api.tls=true"
      - "traefik.http.routers.whatsapp-api.tls.certresolver=letsencrypt"

      - "traefik.http.services.whatsapp-api.loadbalancer.server.port=8084"

networks:
  traefik_public:
    external: true

  whatsapp_internal:
    driver: bridge

A API utiliza conexões HTTP prolongadas em determinados fluxos. Não configure timeouts agressivos no proxy reverso.

Quando utilizar um serversTransport específico para conexões persistentes:

labels:
  - "traefik.http.services.whatsapp-api.loadbalancer.serverstransport=sse_transport@file"

⁠Segurança

Não publique ou versione:

Arquivos .env.
Tokens administrativos.
Tokens de instância.
Segredos JWT.
URLs de banco com credenciais.
Bancos SQLite de sessão.
Backups da store do Whatsmeow.

Em produção:

Utilize HTTPS.
Restrinja o acesso à API.
Use secrets fortes e exclusivos.
Utilize tags Docker versionadas.
Mantenha backups do PostgreSQL.
Proteja os endpoints administrativos.
Não registre tokens ou conteúdos sensíveis nos logs.
Não exponha o banco de dados diretamente à internet.

⁠Uso responsável

Esta API utiliza uma integração não oficial com o WhatsApp. Mudanças no protocolo podem interromper total ou parcialmente o funcionamento da aplicação.

O operador da imagem é responsável por:

Cumprir as leis aplicáveis.
Cumprir os termos de serviço do WhatsApp.
Obter consentimento para o envio de mensagens.
Evitar spam, abuso e automações indevidas.
Proteger dados pessoais, tokens e sessões.

⁠Documentação

⁠Licença

O projeto é disponibilizado sob a licença:

AGPL-3.0-only

O uso comercial é permitido dentro dos termos da AGPL.

Empresas que precisem:

Manter modificações privadas.
Incorporar o projeto em software proprietário.
Distribuir sob termos diferentes.
Evitar as obrigações da AGPL.

devem obter uma licença comercial separada.

Consulte:

⁠Comunidade

Tag summary

Recent tags

Content type

Image

Digest

sha256:c38c32138…

Size

61.3 MB

Last updated

about 11 hours ago

docker pull codechat/whatsapp-go-api:sha-7fac67f

codechat/whatsapp-go-api

codechat/whatsapp-go-api repository overview

⁠CodeChat WhatsApp Go API

⁠Visão geral

⁠Imagem

⁠Plataformas suportadas

⁠Tags

⁠Recursos da imagem

⁠Início rápido com Docker Compose

⁠Execução com docker run

⁠Variáveis de ambiente

⁠Servidor

⁠Banco principal

⁠Autenticação

⁠Persistência das sessões

⁠Webhook global

⁠FFmpeg

⁠Sessões com SQLite

⁠Health checks

⁠Uso básico

⁠Criar uma instância

⁠Conectar por QR Code

⁠Conectar por código de pareamento

⁠Consultar estado da conexão

⁠Enviar mensagem de texto

⁠Endpoints de mensagem

⁠Webhooks

⁠Uso com Traefik

⁠Segurança

⁠Uso responsável

⁠Documentação

⁠Licença

⁠Comunidade

Tag summary

⁠Execução com `docker run`