Skip to content

quickstart.md

Latest commit

 

History

History
336 lines (246 loc) · 7.29 KB

quickstart.md

File metadata and controls

336 lines (246 loc) · 7.29 KB

Início Rápido

Tutorial prático para configurar sua primeira instância WhatsApp e enviar mensagens via Evolution GO.

Pré-requisitos

  • Evolution GO instalado e em execução
  • Chave de API configurada (GLOBAL_API_KEY)
  • Smartphone com WhatsApp ativo

Se ainda não instalou, consulte o Guia de Instalação.

1. Verificar API

Confirme que o servidor está respondendo:

curl http://localhost:4000/server/ok

Resposta esperada:

{
  "status": "ok"
}

2. Criar Instância

Uma instância representa uma conexão única do WhatsApp. Crie sua primeira:

curl -X POST http://localhost:4000/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-GLOBAL-API-KEY" \
  -d '{
    "name": "minha-instancia",
    "token": "token-secreto-da-instancia"
  }'

Importante:

  • apikey header: Use a GLOBAL_API_KEY configurada no servidor
  • token: Crie um token único para esta instância (será usado para autenticar requisições desta instância)
  • name: Nome identificador da instância

Resposta:

{
  "message": "success",
  "data": {
    "instanceId": "uuid-gerado",
    "name": "minha-instancia",
    "token": "token-secreto-da-instancia",
    "status": "created"
  }
}

A instância foi criada mas ainda não está autenticada no WhatsApp.

3. Autenticar via QR Code

Iniciar Conexão

curl -X POST http://localhost:4000/instance/connect \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia"

Nota: Agora use o token da instância no header apikey (não mais a GLOBAL_API_KEY).

Obter QR Code

Via navegador:

http://localhost:4000/instance/qr

(com o header apikey: token-secreto-da-instancia)

Via API:

curl "http://localhost:4000/instance/qr" \
  -H "apikey: token-secreto-da-instancia"

Escanear no WhatsApp

  1. Abra o WhatsApp no smartphone
  2. Acesse Mais opções (⋮) → Aparelhos conectados
  3. Toque em Conectar um aparelho
  4. Escaneie o QR Code exibido

A conexão deve ser estabelecida em aproximadamente 10 segundos.

4. Verificar Status

Confirme que a instância está conectada:

curl "http://localhost:4000/instance/status" \
  -H "apikey: token-secreto-da-instancia"

Resposta quando conectado:

{
  "message": "success",
  "data": {
    "instanceId": "uuid-da-instancia",
    "name": "minha-instancia",
    "status": "open",
    "profilePictureUrl": "https://...",
    "profileName": "Nome do Perfil"
  }
}

Status possíveis:

  • created - Instância criada, aguardando autenticação
  • connecting - Processo de conexão em andamento
  • open - Conectado e operacional
  • close - Desconectado

5. Enviar Mensagem

Mensagem de Texto

curl -X POST http://localhost:4000/send/text \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia" \
  -d '{
    "number": "5511999999999",
    "text": "Mensagem de teste via Evolution GO"
  }'

Nota: A instância é identificada pelo token no header apikey. Não é necessário enviar instanceName no body.

Formato do número:

  • DDI + DDD + Número (apenas dígitos)
  • Exemplo Brasil: 5511999999999 (55=Brasil, 11=São Paulo)

Resposta:

{
  "message": "success",
  "data": {
    "messageId": "3EB0...",
    "status": "sent"
  }
}

Mensagem com Mídia

curl -X POST http://localhost:4000/send/media \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia" \
  -d '{
    "number": "5511999999999",
    "mediaUrl": "https://exemplo.com/imagem.jpg",
    "caption": "Legenda da imagem"
  }'

Mensagem com Documento

curl -X POST http://localhost:4000/send/media \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia" \
  -d '{
    "number": "5511999999999",
    "mediaUrl": "https://exemplo.com/documento.pdf",
    "fileName": "relatorio.pdf"
  }'

Operações de Gerenciamento

Listar Instâncias

curl "http://localhost:4000/instance/all" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Nota: Use a GLOBAL_API_KEY para listar todas as instâncias.

Detalhes da Instância

curl "http://localhost:4000/instance/info/uuid-da-instancia" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Nota: Use o instanceId (UUID) da instância na URL.

Desconectar

curl -X POST http://localhost:4000/instance/disconnect \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia"

Reconectar (novo QR Code)

curl -X POST http://localhost:4000/instance/reconnect \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia"

Deletar

curl -X DELETE "http://localhost:4000/instance/delete/uuid-da-instancia" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Nota: Use a GLOBAL_API_KEY e o instanceId (UUID) para deletar.

Documentação Interativa (Swagger)

Acesse a interface Swagger para explorar e testar todos os endpoints:

http://localhost:4000/swagger/index.html

Passos:

  1. Clique em Authorize no topo da página
  2. Insira sua chave de API
  3. Confirme a autenticação
  4. Explore e teste os endpoints disponíveis

Resolução de Problemas

QR Code Expira

QR Code possui validade limitada (~60 segundos). Se expirar:

curl -X POST http://localhost:4000/instance/reconnect \
  -H "Content-Type: application/json" \
  -H "apikey: token-secreto-da-instancia"

Instância Não Encontrada

Verifique se está usando o token correto:

# Listar todas as instâncias
curl "http://localhost:4000/instance/all" \
  -H "apikey: SUA-GLOBAL-API-KEY"

Mensagem Não Entregue

Verificações:

  1. Status da conexão:
curl "http://localhost:4000/instance/status" \
  -H "apikey: token-secreto-da-instancia"

Status deve ser open.

  1. Formato do número:

    • Apenas dígitos (sem espaços, hífens ou símbolos)
    • Incluir DDI e DDD
    • Validar se o número existe no WhatsApp

  2. Logs do servidor:

docker-compose logs -f evolution-go

Erro de Autenticação

Verifique se está enviando o header correto:

-H "apikey: sua-chave-aqui"

Confirme a chave configurada no docker-compose.yml ou .env.

Próximos Passos

Documentação da API

Recursos Avançados

Deploy e Segurança

Documentação Evolution GO v1.0