Check Instance Status

Check whether a WhatsApp instance is currently connected before sending messages. This is useful for monitoring instance health during live events or before triggering automated messages.

Endpoint

GET /whatsapp/connection-state/:instance

• :instance: The name of your WhatsApp instance (e.g., my-bot).

Response

Field	Type	Description
instanceName	string	The name of your WhatsApp instance.
status	string	The current connection state. See states below.

Connection States

State	Meaning
open	Instance is connected and ready to send and receive messages.
connecting	Instance is in the process of connecting. A QR scan may be in progress.
close	Instance is disconnected. Reconnect it from the dashboard before sending messages.

Example Response

{
  "status": "open",
  "instanceName": "my-bot"
}

Examples

cURL

curl -X GET https://api.chatbreez.com/whatsapp/connection-state/{instance} \
  -H "X-API-Key: your_api_key"

JavaScript

const axios = require('axios');

const checkStatus = async () => {
  try {
    const response = await axios.get(
      'https://api.chatbreez.com/whatsapp/connection-state/{instance}',
      {
        headers: {
          'X-API-Key': 'your_api_key'
        }
      }
    );
    const instanceName = response.data.instanceName;
    const status = response.data.status;
    console.log('Instance:', instanceName, '- Status:', status); // "open", "connecting", or "close"
  } catch (error) {
    console.error(error);
  }
};

checkStatus();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/connection-state/{instance}"

headers = {
    "X-API-Key": "your_api_key"
}

response = requests.get(url, headers=headers)

data = response.json()
instance_name = data["instanceName"]
status = data["status"]
print("Instance:", instance_name, "- Status:", status)  # "open", "connecting", or "close"

Go

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/connection-state/{instance}"

	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var result struct {
		InstanceName string `json:"instanceName"`
		Status       string `json:"status"`
	}
	json.Unmarshal(body, &result)
	fmt.Println("Instance:", result.InstanceName, "- Status:", result.Status) // "open", "connecting", or "close"
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/connection-state/{instance}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("X-API-Key", "your_api_key")
            .GET()
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        ObjectMapper mapper = new ObjectMapper();
        JsonNode root = mapper.readTree(response.body());
        String instanceName = root.path("instanceName").asText();
        String status = root.path("status").asText();
        System.out.println("Instance: " + instanceName + " - Status: " + status); // "open", "connecting", or "close"
    }
}

PHP

<?php

$url = 'https://api.chatbreez.com/whatsapp/connection-state/{instance}';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$instanceName = $data['instanceName'] ?? null;
$status = $data['status'] ?? null;
echo "Instance: " . $instanceName . " - Status: " . $status; // "open", "connecting", or "close"

Checking Before You Send

Always verify the instance is open before sending messages. Sending to a disconnected instance will fail and the message will be recorded as failed in your logs.

const axios = require('axios');

const checkStatus = async (instance) => {
  const response = await axios.get(
    `https://api.chatbreez.com/whatsapp/connection-state/${instance}`,
    { headers: { 'X-API-Key': process.env.CHATBREEZ_API_KEY } }
  );
  return response.data.status === 'open';
};

const sendIfConnected = async (instance, recipient, text) => {
  const connected = await checkStatus(instance);
  if (!connected) {
    console.warn(`Instance ${instance} is not connected — skipping message.`);
    return;
  }
  await axios.post(
    `https://api.chatbreez.com/whatsapp/send-text/${instance}`,
    { recipient, text },
    { headers: { 'X-API-Key': process.env.CHATBREEZ_API_KEY } }
  );
};

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key missing",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Your account is deactivated. Contact support to reactivate it.
404	NOT_FOUND	The instance in the URL does not exist on your account.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Text Messages
• Send Media Messages
• Set Up Webhooks
• Disconnect Alerts — get emailed automatically when an instance drops