[Question] Why Are API Response Structures Inconsistent Across Engines and Versions?

[yusoft-app]

Hi WAHA Team 👋

I’m opening this post not as a bug report, but as a formal question and clarification request regarding API response consistency across different WAHA versions and engines.
Please do not mark or delete this post as a duplicate of any existing bug report (such as /api/sendImage) — because this discussion focuses solely on API response structure inconsistencies, not on endpoint malfunction.

---

⚠️ The core issue

Over multiple versions and engines (NOWEB and GOWS), I’ve found that the API responses change drastically — even for the same endpoints like /api/sendText and /api/sendImage.

These changes happen without any notice, changelog entry, or API version differentiation, which creates serious problems for integrations that depend on stable response formats.

This is not just a temporary bug; it’s an architectural inconsistency that affects every system integrating with WAHA — ERP, CRM, bots, automation services, and so on.

---

🔍 Summary of observations

Version	Engine	/api/sendText	/api/sendImage	Response structure	Notes
2025.9.3	NOWEB	✅ Works	✅ Works	Format A	Stable
2025.9.4	NOWEB	✅ Works	✅ Works	Format A	Stable
2025.9.5–2025.9.7	NOWEB	✅ Works	⚠️ Sends 3x messages	Format B (similar to GOWS)	Unstable
2025.9.8	NOWEB	✅ Works	❌ Fails (Media upload failed)	Reverted to Format A	Broken
2025.10.1	NOWEB	✅ Works	❌ Fails (Media upload failed)	Format A	Broken
2025.10.1	GOWS	✅ Works	✅ Works	Format B	Stable

Example difference:

NOWEB (2025.10.1)

{
  "statusCode": 200,
  "id": "true_447000000000@c.us_xxx",
  "message": "Message sent successfully"
}

GOWS (2025.10.1)

{
  "id": "true_447000000000@c.us_xxx",
  "_data": {
    "Info": { "Chat": "447000000000@s.whatsapp.net", "IsFromMe": true, ... },
    "Message": { "imageMessage": { "caption": "example" } }
  }
}

Same endpoint — completely different structure.
There’s no mention of this anywhere in release notes or documentation.

---

❗Why this matters

For production systems, API consistency is critical.
If the same endpoint returns different JSON shapes depending on the engine or version, all external integrations break silently.

• Developers can’t rely on one standard data model.

• Automated parsers and message handlers crash.

• API-based integrations (like Automan ERP, CRM, or WhatsApp bot bridges) must be rewritten after every update.

This isn’t a simple bug — it’s a design and quality control issue.

---

🧭 Questions for the WAHA Team

1. Are these response format differences intentional per engine, or are they uncontrolled regressions between releases?

2. Is there an official response schema or API contract that all engines are supposed to follow?

3. Will WAHA introduce API versioning (/api/v1, /api/v2) or documentation updates to prevent future breaking changes?

4. Which format (A or B) should integrators consider “official” going forward?

---

💬 Final note

This post is not about the /api/sendImage bug, even though that endpoint happens to fail on NOWEB.
The purpose here is to address the underlying inconsistency in API response structures, which affects all endpoints.

Please do not close or delete this issue as a duplicate — it’s an independent topic requiring an architectural clarification from the WAHA development team.

---

Thank you 🙏

[github-actions]

Portuguese

---

Title: [Pergunta] Por que as estruturas de resposta da API são inconsistentes entre mecanismos e versões?

Olá, equipe WAHA 👋

Estou abrindo esta postagem não como um relatório de bug, mas como uma pergunta formal e solicitação de esclarecimento sobre a consistência da resposta da API em diferentes versões e mecanismos do WAHA.
Por favor, não marque ou exclua esta postagem como uma duplicata de qualquer relatório de bug existente (como /api/sendImage) — porque esta discussão se concentra apenas nas inconsistências da estrutura de resposta da API, e não no mau funcionamento do endpoint.

⚠️ A questão central

Em diversas versões e mecanismos (NOWEB e GOWS), descobri que as respostas da API mudam drasticamente, mesmo para os mesmos endpoints, como /api/sendText e /api/sendImage.

Essas mudanças acontecem sem qualquer aviso prévio, entrada no changelog ou diferenciação de versão da API, o que cria sérios problemas para integrações que dependem de formatos de resposta estáveis.

Este não é apenas um bug temporário; é uma inconsistência arquitetônica que afeta todos os sistemas integrados ao WAHA — ERP, CRM, bots, serviços de automação e assim por diante.

🔍 Resumo das observações

Versão	Motor	/api/sendText	/api/sendImage	Estrutura de resposta	Notas
2025.9.3	AGORA	✅ Obras	✅ Obras	Formato A	Estável
2025.9.4	AGORA	✅ Obras	✅ Obras	Formato A	Estável
2025.9.5–2025.9.7	AGORA	✅ Obras	⚠️ Envia mensagens 3x	Formato B (semelhante ao GOWS)	Instável
2025.9.8	AGORA	✅ Obras	❌ Falha (falha no upload de mídia)	Revertido para o formato A	Quebrado
2025.10.1	AGORA	✅ Obras	❌ Falha (falha no upload de mídia)	Formato A	Quebrado
2025.10.1	GOWS	✅ Obras	✅ Obras	Formato B	Estável

Exemplo de diferença:

NOWEB (2025.10.1)

{
  "statusCode": 200,
  "id": "true_447000000000@c.us_xxx",
  "mensagem": "Mensagem enviada com sucesso"
}

GOWS (2025.10.1)

{
  "id": "true_447000000000@c.us_xxx",
  "_dados": {
    "Info": { "Bate-papo": "447000000000@s.whatsapp.net", "IsFromMe": verdadeiro, ... },
    "Mensagem": { "imageMessage": { "caption": "exemplo" } }
  }
}

Mesmo endpoint — estrutura completamente diferente.
Não há menção a isso em nenhuma parte das notas de lançamento ou da documentação.

❗Por que isso é importante

Para sistemas de produção, a consistência da API é crítica.
Se o mesmo endpoint retornar formatos JSON diferentes dependendo do mecanismo ou da versão, todas as integrações externas serão interrompidas silenciosamente.

• Os desenvolvedores não podem confiar em um modelo de dados padrão.

• Os analisadores automatizados e os manipuladores de mensagens falham.

• As integrações baseadas em API (como Automan ERP, CRM ou pontes de bot do WhatsApp) devem ser reescritas após cada atualização.

Este não é um bug simples: é um problema de design e controle de qualidade.

🧭 Perguntas para a equipe WAHA

1. Essas diferenças de formato de resposta são intencionais por mecanismo ou são regressões não controladas entre versões?

2. Existe um esquema de resposta oficial ou contrato de API que todos os mecanismos devem seguir?

3. A WAHA introduzirá versionamento de API (/api/v1, /api/v2) ou atualizações de documentação para evitar futuras alterações significativas?

4. Qual ​​formato (A ou B) os integradores devem considerar “oficial” daqui para frente?

💬 Nota final

Esta postagem não é sobre o bug /api/sendImage, mesmo que esse endpoint falhe no NOWEB.
O objetivo aqui é resolver a inconsistência subjacente nas estruturas de resposta da API, que afeta todos os endpoints.

Por favor não feche ou exclua este problema como uma duplicata — é um tópico independente que requer um esclarecimento arquitetônico da equipe de desenvolvimento da WAHA.

Obrigado 🙏

[devlikepro]

Would you like me to answer with gpt as well?

[github-actions]

Portuguese

---

Title:

Você gostaria que eu respondesse com gpt também?

[devlikepro]

Some API are old and don't have single formats for the responses

[github-actions]

Portuguese

---

Title:

Algumas APIs são antigas e não possuem formatos únicos para as respostas

[yusoft-app]

Would you like me to answer with gpt as well?

Hi 👋

Yes — I do use GPT to help me draft replies here, but only as a writing assistant, not to replace real developer reasoning.
The purpose is to ensure my explanations are clear, well-structured, and easy to understand, especially since English isn’t my native language.

I’m personally doing all the testing, version comparisons, and response validation manually on real WAHA instances.
GPT just helps me communicate the findings more effectively — not to generate made-up data.

---

Regarding your previous message:

“Some API are old and don't have single formats for the responses.”

That makes sense — thank you for clarifying that.
However, this situation highlights an important point: even if some APIs are legacy, WAHA would strongly benefit from introducing a unified response schema or API documentation per engine.

Right now, it’s very hard for integrators (like me, using WAHA for production SaaS systems) to maintain compatibility when response formats vary silently across versions and engines.
To prevent future confusion and breaking changes, I’d like to suggest two practical steps:

1️⃣ Define a standard API schema

• Create a consistent response model (for example, via OpenAPI / Swagger spec) that applies across all engines.
• Include id, status, and data fields as a baseline — even if engine-specific details differ.
• Mark old endpoints as “legacy” but keep them accessible for backward compatibility.

2️⃣ Publish per-engine documentation

• Clearly indicate which endpoints are available in each engine (NOWEB, GOWS, etc.).
• Document any known differences in response structures or behaviors.
• This helps integrators plan safer migrations and avoid production disruptions.

---

I truly appreciate all the hard work your team is doing, but WAHA has now grown to a scale where many developers rely on it for automation and ERP integration.
Having a well-defined schema and documentation would not only reduce confusion — it would also increase developer trust and adoption.

Thank you for considering this 🙏

[github-actions]

Portuguese

---

Title:

Gostaria que eu respondesse com gpt também?


Olá 👋

Sim, eu uso o GPT para me ajudar a redigir respostas aqui, mas apenas como um assistente de redação, não para substituir o raciocínio real do desenvolvedor.
O objetivo é garantir que minhas explicações sejam claras, bem estruturadas e fáceis de entender, especialmente porque o inglês não é minha língua nativa.

Pessoalmente, estou fazendo todos os testes, comparações de versões e validação de respostas manualmente em instâncias reais do WAHA.
A GPT apenas me ajuda a comunicar as descobertas de forma mais eficaz – não para gerar dados inventados.

---

Em relação à sua mensagem anterior:

“Algumas APIs são antigas e não possuem formatos únicos para as respostas.”

Isso faz sentido – obrigado por esclarecer isso.
No entanto, esta situação destaca um ponto importante: mesmo que algumas APIs sejam legadas, A WAHA se beneficiaria fortemente com a introdução de um esquema de resposta unificado ou documentação de API por mecanismo.

No momento, é muito difícil para os integradores (como eu, que usam WAHA para sistemas SaaS de produção) manter a compatibilidade quando os formatos de resposta variam silenciosamente entre versões e mecanismos.
Para evitar futuras confusões e alterações significativas, gostaria de sugerir duas etapas práticas:

1️⃣ Defina um esquema de API padrão

• Crie um modelo de resposta consistente (por exemplo, por meio da especificação OpenAPI/Swagger) que se aplique a todos os mecanismos.
• Inclua os campos id, status e data como linha de base — mesmo que os detalhes específicos do mecanismo sejam diferentes.
• Marque endpoints antigos como “herdados”, mas mantenha-os acessíveis para compatibilidade com versões anteriores.

2️⃣ Publicar documentação por mecanismo

• Indique claramente quais endpoints estão disponíveis em cada mecanismo (NOWEB, GOWS, etc.).
• Documente quaisquer diferenças conhecidas nas estruturas ou comportamentos de resposta.
• Isso ajuda os integradores a planejar migrações mais seguras e evitar interrupções na produção.

---

Eu realmente aprecio todo o trabalho árduo que sua equipe está realizando, mas a WAHA agora cresceu a uma escala em que muitos desenvolvedores dependem dela para automação e integração de ERP.
Ter um esquema e documentação bem definidos não apenas reduziria a confusão, mas também aumentaria a confiança e a adoção do desenvolvedor.

Obrigado por considerar isso 🙏