Send Text Message

Send a plain text message to a WhatsApp recipient using either their phone number or the full sender address from a webhook.

Endpoint

POST /whatsapp/send-text/:instance

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

Authentication

Send text messages using your ChatBreez API key:

X-API-Key: your_api_key
Content-Type: application/json

Playground testing

If you're testing your instance connection from the ChatBreez dashboard Playground, the playground sends a test text using an access token in the Authorization header instead of X-API-Key. That access token works only inside the Playground — use your regular API key (X-API-Key) when you integrate the API into your own application.

Request Body

Parameter	Type	Required	Description
recipient	string	Yes	The recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
text	string	Yes	The message content you want to send.

Example Payload

{
  "recipient": "254123456789",
  "text": "Hello! This is a test message from ChatBreeZ API."
}

Examples

cURL

curl -X POST https://api.chatbreez.com/whatsapp/send-text/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "text": "Hello from ChatBreeZ!"
  }'

JavaScript

const axios = require('axios');

const sendMessage = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-text/{instance}', {
      recipient: '254123456789',
      text: 'Hello from ChatBreeZ!'
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendMessage();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/send-text/{instance}"

payload = {
    "recipient": "254123456789",
    "text": "Hello from ChatBreeZ!"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

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

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

	payload := map[string]interface{}{
		"recipient": "254123456789",
		"text":      "Hello from ChatBreeZ!",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	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()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-text/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "text": "Hello from ChatBreeZ!"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

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

$payload = json_encode([
    'recipient' => '254123456789',
    'text' => 'Hello from ChatBreeZ!',
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

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

echo $response;

Response

{
  "message": "Message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "recipient: Required · text: Required",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	The request body is invalid or a required field is missing/invalid (e.g. recipient or text), or the recipient is not registered on WhatsApp.
401	UNAUTHORIZED	Missing or invalid API key. When testing from the Playground, the Authorization: Bearer access token is missing or expired instead.
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.
409	CONFLICT	The instance is not connected to WhatsApp. Reconnect it and scan the QR code before sending messages.
502	UPSTREAM_ERROR	WhatsApp did not acknowledge the message. Try again shortly.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Media Messages — images, videos, documents, and audio files
• Send Audio Messages — audio attachments and voice notes
• Send Location Messages — share a location pin
• Send Contact Messages — share contact cards
• Send Poll Messages — create polls with up to ten options
• Check Instance Status — confirm your instance is connected before sending