WhatsApp via Evolution API

The WhatsApp (Evolution) integration uses an Evolution API instance that your organization already manages. The session and QR code stay in Evolution; SquadOS validates the credentials, receives messages through the webhook, and sends replies through the API.

Unofficial integration

This integration uses a WhatsApp Web-based gateway, not Meta’s official API. The session can drop, and the number remains subject to WhatsApp policies. For an official integration, use Official WhatsApp.

What this connector requires

The current SquadOS connector is compatible with the Evolution API contract that provides:

• GET /instance/connectionState/{instanceName} to check the connection;
• GET /instance/fetchInstances?instanceName={instanceName} to identify the number;
• the messages.upsert webhook event;
• the /message/sendText/{instanceName}, /message/sendMedia/{instanceName}, and /chat/sendPresence/{instanceName} endpoints.

Do not confuse that product with Evolution Go: it uses different endpoints and event names. Refer to the matching Evolution API installation guide and official webhook configuration.

Before you start

You need:

• permission to create inboxes in SquadOS;
• an existing Evolution API instance;
• its Instance name;
• a key accepted in the apikey header by your installation — global or instance-specific, depending on your Evolution configuration;
• the absolute base URL of the instance, for example https://evolution.yourcompany.com;
• access to Evolution Manager to configure the webhook and pair WhatsApp.

A trailing / in the base URL is accepted and removed by SquadOS. Use only a trusted address managed by your organization. Do not enter localhost, private-network addresses, or internal admin panels: validation makes a request from the SquadOS server.

Connect the inbox

1. In Admin, open Inboxes.
2. Click Connect inbox.
3. In the WhatsApp group, choose WhatsApp (Evolution). Its description is Use your own Evolution API instance.
4. Fill in exactly three fields:
   • Your Evolution instance URL;
   • Instance name;
   • Instance API key.
5. Click Validate and continue.

At this point, SquadOS calls GET /instance/connectionState/{instanceName} with the apikey header. An HTTP 2xx response proves that the URL, instance, and key were accepted; it does not yet prove that WhatsApp is paired or that the webhook delivers messages. The inbox has not been created yet.

Configure the webhook and WhatsApp

After validation, SquadOS shows a webhook URL unique to the pending connection. Copy the complete URL and follow the text shown in the product:

1. Open Evolution Manager and select the instance you entered.
2. Go to the instance’s Settings > Webhook or Events.
3. Paste the URL into Webhook URL and keep the POST method.
4. Select only the message event. SquadOS calls it messages.upsert; some Evolution versions show the configuration option as MESSAGES_UPSERT. The payload received by SquadOS must contain event: "messages.upsert".
5. Save the webhook.
6. In Evolution Manager itself, connect WhatsApp and scan the QR code. SquadOS does not display this QR code.
7. Return to SquadOS and click Webhook configured.
8. If the instance is not connected yet, finish pairing it in Evolution and use Check again.

SquadOS activates the connection only when connectionState returns instance.state: "open". It then tries to obtain the number through fetchInstances; that identity must not already be active in another inbox.

Choose who handles it

After connection, the wizard opens Who handles this inbox?:

• choose an active agent to reply automatically; or
• keep Human support so the message enters the queue and an operator replies in Conversations.

Enter an Inbox name and click Done. The credential belongs to the inbox, not to the agent. Configuration and disconnection therefore live under Inboxes; the agent editor only shows the inboxes routed to that agent.

Accepted messages

On inbound traffic, the current adapter:

• accepts only JSON requests with event: "messages.upsert";
• ignores groups whose remoteJid ends in @g.us;
• ignores messages with fromMe: true;
• reads plain text, extended text, and an image caption;
• uses the phone number extracted from remoteJid to keep the conversation in the same inbox.

Received files are not transported into SquadOS by this integration. An image without a caption, audio, video, sticker, or document can reach the pipeline without useful content. Until that limitation is fixed, ask the customer to send the information as text or use another channel for journeys that depend on attachments.

On outbound traffic, an agent, operator, or Automation can reuse the conversation and inbox. The adapter sends text, a generated image by URL, and typing presence. An image sent by SquadOS does not mean that images received through Evolution are preserved.

Status, credentials, and disconnection

Open the inbox and use Edit to check the connection or replace its URL, name, and key. SquadOS validates the new set before saving it; if validation fails, it keeps the previous credentials.

The displayed status is a query to Evolution, not continuous proof of delivery. An HTTP or network failure during that query can currently be treated as connected: false and deactivate an inbox that is still paired. Before pairing again, check the state in Evolution Manager and retry.

When you disconnect, SquadOS calls DELETE /instance/logout/{instanceName} and removes the local inbox. Existing conversations remain in history, but that connection can no longer receive or answer them. Because a remote failure can be hidden, also confirm in Evolution Manager that the session actually ended. Disconnecting does not delete the instance; delete it separately at the provider only if that is your goal.

Troubleshooting

• Invalid credentials: validation received a non-2xx HTTP response other than 404 or 5xx. Check the URL, name, and key. Do not assume every occurrence is only a bad key.
• Instance not found: Evolution returned 404. Check instanceName, including capitalization, and the base URL.
• Provider unavailable: there was a network error or HTTP 5xx. Check Evolution’s health and retry; do not recreate the inbox immediately.
• The instance is not connected yet: its state is not open. Pair it in Evolution Manager and click Check again.
• The webhook receives no messages: check the complete URL, POST method, message event, and whether event-specific webhooks appended a suffix to the URL. SquadOS expects the endpoint exactly as copied.
• The inbox connects, but the first message does not appear: send plain text from an individual contact. Do not use a group, a message sent by the connected number, or captionless media as the first test.
• Wrong number or reply path: check that the inbox is routed to the expected destination and that the same number is not active in another inbox.

To complete the test, send a text message from another number, confirm that it appears in Conversations, and reply through the chosen destination. Connected status alone does not validate the full path.