Using with Postman

Postman is a tool for testing and exploring REST APIs visually and intuitively. With the official Evolution Go collection, you can execute requests, configure environments, and explore all endpoints without writing any code.

Prerequisites

Evolution Go installed and running — see the installation guide
Postman installed — download here
Your API Key (GLOBAL_API_KEY configured in your .env)

Step 1: Import the Official Collection

The official Evolution Go collection is publicly available on Postman and includes all API endpoints ready to use.

Open Postman

Open Postman on your computer or access Postman Web.

Access Import

In the upper left corner, click Import.

Import via link

Select the Link tab and paste the official collection URL:

https://www.postman.com/agenciadgcode/evolution-api/collection/u95jxho/evolution-go

Confirm import

Click Continue and then Import. The Evolution Go collection will appear in your sidebar.

Step 2: Create the Environment

Environment variables centralize your instance configurations, allowing you to switch between environments (local, staging, production) without modifying each request.

Create new Environment

In Postman, click Environments (eye icon in the upper right corner) and then + to create a new one.

Name the Environment

Name it Evolution Go (or any name you prefer).

Add variables

Add the following variables:

Variable	Initial value	Description
`base_url`	`http://localhost:8080`	Your Evolution Go server base URL
`api_key`	`your-key-here`	Value of `GLOBAL_API_KEY` in `.env`
`instance_id`	(fill after creating instance)	WhatsApp instance UUID

Save and activate

Click Save and select the Evolution Go environment in the selector in the upper right corner of Postman.

Never share or expose the api_key value publicly. It provides full access to your API.

Step 3: Configure Collection Headers

To avoid adding headers to each request individually, configure them at the collection level.

Open collection settings

Right-click on Evolution Go in the sidebar and select Edit.

Access the Variables tab

Confirm that the variables base_url, api_key, and instance_id are referenced.

Configure Pre-request Script (optional)

Optionally, add default headers to all requests via Pre-request Script:

pm.request.headers.add({ key: "apikey", value: pm.environment.get("api_key") });
pm.request.headers.add({ key: "instanceId", value: pm.environment.get("instance_id") });
pm.request.headers.add({ key: "Content-Type", value: "application/json" });

Required authentication headers are:

apikey: your GLOBAL_API_KEY
instanceId: instance UUID (required on routes that operate on a specific instance)
Content-Type: application/json (for requests with a body)

Step 4: Test the Connection

Before creating instances, verify that Evolution Go is accessible. Request:

GET {{base_url}}/

A successful response indicates the server is running. If you get a connection error, verify that Evolution Go is running and that base_url is correct.

Step 5: Create a WhatsApp Instance

With the connection verified, create your first instance. Request:

POST {{base_url}}/instance/create

Headers:

Key	Value
`Content-Type`	`application/json`
`apikey`	`{{api_key}}`

Body:

{
  "instanceName": "my-instance",
  "integration": "WHATSAPP-BAILEYS"
}

Success response:

{
  "instanceName": "my-instance",
  "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e",
  "token": "your-token-here",
  "status": "created"
}

Copy the instanceId from the response and save it to the instance_id variable in your Environment to use in subsequent requests.

Step 6: Connect to WhatsApp

With the instance created, start the WhatsApp connection. This endpoint also allows you to configure the webhook to receive events. Request:

POST {{base_url}}/instance/connect

Headers:

Key	Value
`Content-Type`	`application/json`
`apikey`	`{{api_key}}`
`instanceId`	`{{instance_id}}`

Body:

{
  "webhookUrl": "https://webhook.site/your-unique-id",
  "subscribe": ["ALL"],
  "immediate": true
}

After the request, you’ll receive a QR Code via webhook (field qrcode in base64). Scan it with your WhatsApp mobile app at Settings > Linked Devices > Link a Device.

To connect via Pairing Code instead of QR Code, add the phone field to the body with the phone number in the format 5511999999999.

Exploring More Endpoints

Access the Swagger interactive documentation of your instance to discover all available endpoints:

{{base_url}}/swagger/index.html

Swagger lets you visualize parameters, test endpoints directly in the browser, and see response examples.

Getting Started

Configuration

Integrations

Prerequisites

Step 1: Import the Official Collection

Step 2: Create the Environment

Step 3: Configure Collection Headers

Step 4: Test the Connection

Step 5: Create a WhatsApp Instance

Step 6: Connect to WhatsApp

Exploring More Endpoints

Next steps

Configure Webhooks

Initial Setup

​Prerequisites

​Step 1: Import the Official Collection

​Step 2: Create the Environment

​Step 3: Configure Collection Headers

​Step 4: Test the Connection

​Step 5: Create a WhatsApp Instance

​Step 6: Connect to WhatsApp

​Exploring More Endpoints

​Next steps

Configure Webhooks

Initial Setup

Prerequisites

Step 1: Import the Official Collection

Step 2: Create the Environment

Step 3: Configure Collection Headers

Step 4: Test the Connection

Step 5: Create a WhatsApp Instance

Step 6: Connect to WhatsApp

Exploring More Endpoints

Next steps