Documentação / Comparação de Endpoints: Evolution GO vs Evolution V2

Comparação de Endpoints: Evolution GO vs Evolution V2

Entrar

Comparação de Endpoints: Evolution GO vs Evolution V2

Este documento compara os endpoints disponíveis nos dois provedores de WhatsApp utilizados no Pilot Status: Evolution GO e Evolution V2.

Sumário

Endpoints Exclusivos do Evolution GO

Instance Management

| Endpoint | Método | Descrição | |----------|--------|-----------| | /instance/qr | GET | Obtém QR Code para conexão | | /instance/pair | POST | Obtém pairing code para conexão | | /instance/status | GET | Verifica status de conexão da instância | | /instance/reconnect | POST | Reconecta uma instância | | /instance/{instanceId}/advanced-settings | GET | Busca configurações avançadas | | /instance/{instanceId}/advanced-settings | PUT | Atualiza configurações avançadas |

Message

| Endpoint | Método | Descrição | |----------|--------|-----------| | /send/text | POST | Envia mensagem de texto | | /send/button | POST | Envia mensagem com botões | | /send/media | POST | Envia mensagem de mídia | | /message/status | POST | Verifica status de mensagem (Delivered/Read) |

Comportamento do /message/status:

  • Retorna result: null quando mensagem ainda não foi entregue (equivalente a SERVER_ACK/PENDING)
  • Retorna status: "Delivered" quando mensagem foi entregue ao destinatário
  • Retorna status: "Read" quando mensagem foi lida pelo destinatário

Chat

| Endpoint | Método | Descrição | |----------|--------|-----------| | /message/presence | POST | Envia estado de presença (digitando, etc.) | | /user/check | POST | Verifica se números existem no WhatsApp |

Group

| Endpoint | Método | Descrição | |----------|--------|-----------| | /group/info | GET | Obtém informações de um grupo | | /group/list | GET | Lista todos os grupos que a instância participa |

Newsletter

| Endpoint | Método | Descrição | |----------|--------|-----------| | /newsletter/list | GET | Lista newsletters (canais) da conta |

Endpoints Exclusivos do Evolution V2

Instance Management

| Endpoint | Método | Descrição | |----------|--------|-----------| | /instance/connect/:instanceName | GET | Conecta uma instância existente (QR/Pairing) | | /instance/connectionState/:instanceName | GET | Obtém estado de conexão da instância | | /instance/setPresence/:instanceName | POST | Define estado de presença da instância | | /instance/restart/:instanceName | POST | Reinicia uma instância | | /settings/find/:instanceName | GET | Busca configurações locais | | /settings/set/:instanceName | POST | Define configurações locais |

Message

| Endpoint | Método | Descrição | |----------|--------|-----------| | /message/sendText/:instanceName | POST | Envia mensagem de texto | | /message/sendButtons/:instanceName | POST | Envia mensagem com botões | | /message/sendMedia/:instanceName | POST | Envia mensagem de mídia |

Chat

| Endpoint | Método | Descrição | |----------|--------|-----------| | /chat/sendPresence/:instanceName | POST | Envia estado de presença para um chat | | /chat/whatsappNumbers/:instanceName | POST | Verifica informações de números WhatsApp |

Group

| Endpoint | Método | Descrição | |----------|--------|-----------| | /group/findGroupInfos/:instanceName | GET | Obtém informações de um grupo | | /group/fetchAllGroups/:instanceName | GET | Lista todos os grupos que a instância participa |

Endpoints Comuns (com diferenças)

Create Instance

Evolution GO:

POST /instance/create
Body: { instanceId, name, token, advancedSettings, proxy?, ... }

Evolution V2:

POST /instance/create
Body: { instanceName, number, qrcode, integration, syncFullHistory, groupsIgnore, proxyFields?, extra? }

Logout Instance

Evolution GO:

DELETE /instance/logout

Evolution V2:

DELETE /instance/logout/:instanceName

Delete Instance

Evolution GO:

DELETE /instance/delete/{instanceId}

Evolution V2:

DELETE /instance/delete/:instanceName

Análise por Categoria

1. Gerenciamento de Instâncias

| Funcionalidade | Evolution GO | Evolution V2 | Observações | |----------------|--------------|--------------|-------------| | Criar instância | ✅ | ✅ | GO usa UUID, V2 usa nome | | Conectar (QR/Pairing) | ✅ (separado) | ✅ (unificado) | GO: /instance/qr + /instance/pair | | Verificar status | ✅ (/instance/status) | ✅ (/instance/connectionState) | | | Definir presença | ✅ (via /message/presence) | ✅ (via /instance/setPresence) | | | Reiniciar | ✅ (/instance/reconnect) | ✅ (/instance/restart) | | | Logout | ✅ | ✅ | V2 inclui nome na URL | | Deletar | ✅ | ✅ | GO usa ID, V2 usa nome | | Configurações avançadas | ✅ (/instance/{id}/advanced-settings) | ❌ | GO exclusivo | | Configurações locais | ❌ | ✅ (/settings/find, /settings/set) | V2 exclusivo |

2. Envio de Mensagens

| Funcionalidade | Evolution GO | Evolution V2 | Observações | |----------------|--------------|--------------|-------------| | Texto | ✅ (/send/text) | ✅ (/message/sendText/:name) | V2 inclui nome na URL | | Botões | ✅ (/send/button) | ✅ (/message/sendButtons/:name) | GO usa imageUrl, V2 usa thumbnailUrl | | Mídia | ✅ (/send/media) | ✅ (/message/sendMedia/:name) | GO usa type/url, V2 usa mediatype/media | | Diferenças de Payload: | | - Campo de tipo | type | mediatype | | | - Campo de URL | url | media | | | - Campo de arquivo | filename | fileName | |

3. Chat e Presença

| Funcionalidade | Evolution GO | Evolution V2 | Observações | |----------------|--------------|--------------|-------------| | Enviar presença (digitando) | ✅ (/message/presence) | ✅ (/chat/sendPresence) | | | Buscar status de mensagem | ✅ (/message/status) | ✅ (/chat/findStatusMessage) | GO usa endpoint direto, V2 usa findStatusMessage | | Verificar números WhatsApp | ✅ (/user/check) | ✅ (/chat/whatsappNumbers) | Respostas diferentes |

Diferenças de Verificação de Números:

Evolution GO:

POST /user/check
Body: { number: string[] }
Response: { data: { Users: [{ Query, IsInWhatsapp, JID, VerifiedName }] } }

Evolution V2:

POST /chat/whatsappNumbers/:instanceName
Body: { numbers: string[] }
Response: [{ number, exists, name }]

4. Grupos

| Funcionalidade | Evolution GO | Evolution V2 | Observações | |----------------|--------------|--------------|-------------| | Buscar informações | ✅ (/group/info) | ✅ (/group/findGroupInfos) | GO usa query param, V2 usa instanceName | | Listar grupos | ✅ (/group/list) | ✅ (/group/fetchAllGroups) | |

Diferenças:

Evolution GO:

GET /group/info?jid=<groupJid>
Response: { data: { Subject: "..." } }

Evolution V2:

GET /group/findGroupInfos/:instanceName?groupJid=<jid>&participants=<bool>
Response: { subject: "..." }

5. Newsletters (Canais)

| Funcionalidade | Evolution GO | Evolution V2 | Observações | |----------------|--------------|--------------|-------------| | Listar newsletters | ✅ (/newsletter/list) | ❌ | GO exclusivo |

Evolution GO:

GET /newsletter/list
Response: { data: [{ id, thread_metadata: { name: { text } } }] }

Principais Diferenças Arquiteturais

1. Identificação de Instância

Evolution GO:

  • Usa UUID para identificar instâncias
  • ID armazenado em WhatsAppInstance.goInstanceId
  • Instância pode ser excluída sem afetar o nome

Evolution V2:

  • Usa nome da instância (string) como identificador
  • Nome faz parte da URL em quase todos os endpoints
  • Ex: /message/sendText/{instanceName}

2. Autenticação

Evolution GO:

  • Chave global para operações admin (create, delete)
  • Token por instância para operações específicas
  • Token passado via header apikey

Evolution V2:

  • Usa API key do ambiente em quase tudo
  • Algumas operações aceitam override via opts.apiKey

3. Formato de Resposta

Evolution GO:

  • Retorna wrapper { data: {...}, message: "success" }
  • Campos capitalizados (ex: Subject, JID)

Evolution V2:

  • Retorna dados diretamente ou com campos específicos
  • Campos em camelCase

4. Webhooks e Eventos

Evolution GO:

  • Eventos de status: Delivered, Read via webhook Receipt
  • Não possui evento SERVER_ACK

Evolution V2:

  • Eventos de status: PENDING, SERVER_ACK, DELIVERED, READ, ERROR
  • Via webhook messages.update

Tabela Resumida

| Endpoint | GO | V2 | Equivalência | |----------|----|----|-------------| | Instance - Create | ✅ | ✅ | Similar | | Instance - Connect | /instance/qr + /instance/pair | /instance/connect/:name | ✅ Diferente | | Instance - Status | /instance/status | /instance/connectionState/:name | ✅ Similar | | Instance - Set Presence | /message/presence | /instance/setPresence/:name | ✅ Diferente | | Instance - Restart | /instance/reconnect | /instance/restart/:name | ✅ Similar | | Instance - Logout | /instance/logout | /instance/logout/:name | ✅ Similar | | Instance - Delete | /instance/delete/{id} | /instance/delete/:name | ✅ Similar | | Instance - Advanced Settings | ✅ | ❌ | GO exclusivo | | Instance - Local Settings | ❌ | ✅ /settings/find & /settings/set | V2 exclusivo | | Message - Send Text | /send/text | /message/sendText/:name | ✅ Similar | | Message - Send Buttons | /send/button | /message/sendButtons/:name | ✅ Similar | | Message - Send Media | /send/media | /message/sendMedia/:name | ✅ Similar | | Message - Get Status | /message/status | /chat/findStatusMessage/:name | ✅ Diferente | | Chat - Send Presence | /message/presence | /chat/sendPresence/:name | ✅ Similar | | Chat - Check Numbers | /user/check | /chat/whatsappNumbers/:name | ✅ Similar | | Group - Find Info | /group/info | /group/findGroupInfos/:name | ✅ Similar | | Group - List | /group/list | /group/fetchAllGroups/:name | ✅ Similar | | Newsletter - List | /newsletter/list | ❌ | GO exclusivo |

Legenda

  • ✅ = Disponível no provedor
  • ❌ = Não disponível no provedor
  • Similar = Funcionalidade equivalente com pequenas diferenças
  • Diferente = Funcionalidade disponível mas com abordagem diferente

Referências

  • Código Evolution GO: packages/whatsapp-provider/src/go/
  • Código Evolution V2: packages/whatsapp-provider/src/v2/
  • Documentação Geral: docs/evolution-api-endpoints.md
  • Tipos Compartilhados: packages/whatsapp-provider/src/types.ts