InstanceName versus InstanceID design issue

[jjmmbb]

The Evolution API currently exposes endpoints and configuration that rely on an InstanceName to identify instances and to create ChatWoot inboxes, which leads to ambiguous identification when the same readable name is reused across accounts or users; the documentation and examples show instance creation and ChatWoot integration using a name field such as chatwootNameInbox or instanceName. Using a human-friendly name as the primary URL identifier makes the API vulnerable to collisions and unintended behavior when multiple users or accounts create inboxes with identical names, producing duplicate or conflicting inbox resources in ChatWoot and in the Evolution system.

A more robust design is to require and use an immutable InstanceID in the call URL and internal routing while keeping InstanceName as a user-facing label only. Using InstanceID prevents routing ambiguity, eliminates race conditions and naming collisions when creating inboxes across different ChatWoot accounts, and simplifies permission checks and logging. Real-world reports and issues show crashes and integration failures when instances and ChatWoot account combinations behave unexpectedly under name-based addressing, demonstrating that a switch to ID-based URLs would resolve many of these conflicts and improve reliability.