Examples
Copy-paste starting points for sending a WhatsApp message through a connected link, plus a small Laravel client and the OpenAPI spec for tooling. It all starts with the same set of credentials.
Environment variables#
Every integration uses the same values. Link your number, then open the link in your dashboard and copy them from its Credentials tab into your server's environment — the same names are used throughout this guide. Keep them on the server and never commit them to source control.
# .env - copy from the Credentials tab of your link
WACENTRACONNECT_API_URL=https://wacentraconnectapi.com/api/v1
WACENTRACONNECT_SESSION_ID=6f1c1f0e-2b7a-4c8e-9d1a-0b2c3d4e5f60
WACENTRACONNECT_API_TOKEN=your_account_token
WACENTRACONNECT_WEBHOOK_URL=https://example.com/webhooks/wacentraconnect
WACENTRACONNECT_WEBHOOK_SECRET=your_webhook_secret
| Variable | Required | Notes |
|---|---|---|
WACENTRACONNECT_API_URL | Always | Base URL for every API call, e.g. https://wacentraconnectapi.com/api/v1. Request paths are appended to it. |
WACENTRACONNECT_SESSION_ID | Always | The uuid of the WhatsApp link you send from. Used in every /sessions/{uuid}/… path. |
WACENTRACONNECT_API_TOKEN | Always | Sent as Authorization: Bearer …. Create it on the Webhook tab of a link (API access). |
WACENTRACONNECT_WEBHOOK_URL | To receive events | The public HTTPS endpoint on your server that WaCentra Connect API posts events to. See Events. |
WACENTRACONNECT_WEBHOOK_SECRET | To verify events | Verifies the X-Webhook-Signature on every delivery. Rotate it on the link's webhook page if it leaks. |
Send a message in your language#
Pick your language — each snippet reads the credentials above and sends a text message through a connected link.
<?php
use GuzzleHttp\Client;
// Credentials from your environment (see Environment variables above).
$base = getenv('WACENTRACONNECT_API_URL'); // https://wacentraconnectapi.com/api/v1
$token = getenv('WACENTRACONNECT_API_TOKEN'); // your link API key
$session = getenv('WACENTRACONNECT_SESSION_ID'); // link uuid
$response = (new Client())->post($base . '/sessions/' . $session . '/whatsapp/messages', [
'headers' => [
'Authorization' => 'Bearer ' . $token,
],
'json' => [
'to' => '+254700000000',
'text' => 'Hello from WaCentra Connect API!',
],
]);
echo $response->getBody();
// Credentials from your environment (see Environment variables above).
const base = process.env.WACENTRACONNECT_API_URL;
const token = process.env.WACENTRACONNECT_API_TOKEN;
const session = process.env.WACENTRACONNECT_SESSION_ID;
const response = await fetch(`${base}/sessions/${session}/whatsapp/messages`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+254700000000',
text: 'Hello from WaCentra Connect API!',
}),
});
console.log(await response.json());
import os
import requests
# Credentials from your environment (see Environment variables above).
base = os.environ['WACENTRACONNECT_API_URL']
token = os.environ['WACENTRACONNECT_API_TOKEN']
session = os.environ['WACENTRACONNECT_SESSION_ID']
response = requests.post(
f'{base}/sessions/{session}/whatsapp/messages',
headers={'Authorization': f'Bearer {token}'},
json={
'to': '+254700000000',
'text': 'Hello from WaCentra Connect API!',
},
)
print(response.json())
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
// Credentials from your environment (see Environment variables above).
var baseUrl = Environment.GetEnvironmentVariable("WACENTRACONNECT_API_URL");
var token = Environment.GetEnvironmentVariable("WACENTRACONNECT_API_TOKEN");
var session = Environment.GetEnvironmentVariable("WACENTRACONNECT_SESSION_ID");
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var payload = JsonSerializer.Serialize(new
{
to = "+254700000000",
text = "Hello from WaCentra Connect API!"
});
var response = await client.PostAsync(
$"{baseUrl}/sessions/{session}/whatsapp/messages",
new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// Credentials from your environment (see Environment variables above).
String baseUrl = System.getenv("WACENTRACONNECT_API_URL");
String token = System.getenv("WACENTRACONNECT_API_TOKEN");
String session = System.getenv("WACENTRACONNECT_SESSION_ID");
String payload = "{\"to\":\"+254700000000\",\"text\":\"Hello from WaCentra Connect API!\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(baseUrl + "/sessions/" + session + "/whatsapp/messages"))
.header("Authorization", "Bearer " + token)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
curl -X POST "$WACENTRACONNECT_API_URL/sessions/$WACENTRACONNECT_SESSION_ID/whatsapp/messages" \
-H "Authorization: Bearer $WACENTRACONNECT_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to":"+254700000000","text":"Hello from WaCentra Connect API!"}'
import 'dart:convert';
import 'package:http/http.dart' as http;
// Credentials from your environment (see Environment variables above).
const base = String.fromEnvironment('WACENTRACONNECT_API_URL');
const token = String.fromEnvironment('WACENTRACONNECT_API_TOKEN');
const session = String.fromEnvironment('WACENTRACONNECT_SESSION_ID');
Future<void> sendMessage() async {
final response = await http.post(
Uri.parse('$base/sessions/$session/whatsapp/messages'),
headers: {
'Authorization': 'Bearer $token',
'Content-Type': 'application/json',
},
body: jsonEncode({
'to': '+254700000000',
'text': 'Hello from WaCentra Connect API!',
}),
);
print(response.body);
}
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
// Credentials from your environment (see Environment variables above).
val base = System.getenv("WACENTRACONNECT_API_URL")
val token = System.getenv("WACENTRACONNECT_API_TOKEN")
val session = System.getenv("WACENTRACONNECT_SESSION_ID")
val payload = """{"to":"+254700000000","text":"Hello from WaCentra Connect API!"}"""
val request = HttpRequest.newBuilder()
.uri(URI.create("$base/sessions/$session/whatsapp/messages"))
.header("Authorization", "Bearer $token")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload))
.build()
val response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString())
println(response.body())
import Foundation
// Credentials from your environment (see Environment variables above).
let base = ProcessInfo.processInfo.environment["WACENTRACONNECT_API_URL"]!
let token = ProcessInfo.processInfo.environment["WACENTRACONNECT_API_TOKEN"]!
let session = ProcessInfo.processInfo.environment["WACENTRACONNECT_SESSION_ID"]!
var request = URLRequest(url: URL(string: "\(base)/sessions/\(session)/whatsapp/messages")!)
request.httpMethod = "POST"
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try! JSONSerialization.data(withJSONObject: [
"to": "+254700000000",
"text": "Hello from WaCentra Connect API!",
])
let task = URLSession.shared.dataTask(with: request) { data, _, error in
if let error = error { print(error); return }
if let data = data { print(String(data: data, encoding: .utf8)!) }
}
task.resume()
Bearer token on every request.
PHP / Laravel#
Integrating from a Laravel app is straightforward with the built-in HTTP client. Each tab below is a drop-in piece: configure the service, drop in the client, then send and receive.
// config/services.php
'wacentraconnect' => [
'url' => env('WACENTRACONNECT_API_URL', 'https://wacentraconnectapi.com/api/v1'), // base URL for every call
'session_id' => env('WACENTRACONNECT_SESSION_ID'), // link uuid
'token' => env('WACENTRACONNECT_API_TOKEN'), // link API key
'webhook_url' => env('WACENTRACONNECT_WEBHOOK_URL'), // your endpoint
'webhook_secret' => env('WACENTRACONNECT_WEBHOOK_SECRET'),// signature key
],
namespace App\Services;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
class WaCentraConnect
{
public function __construct(
private readonly string $baseUrl, // WACENTRACONNECT_API_URL
private readonly string $token, // WACENTRACONNECT_API_TOKEN
private readonly string $sessionId, // WACENTRACONNECT_SESSION_ID
) {}
/** Every call uses the link API key. */
protected function http(): PendingRequest
{
return Http::baseUrl($this->baseUrl)
->withToken($this->token)
->acceptJson()
->timeout(15);
}
public function status(?string $sessionUuid = null): array
{
return $this->http()
->get("/sessions/{$sessionUuid ?? $this->sessionId}/whatsapp")
->throw()
->json();
}
public function sendText(string $to, string $text, ?string $sessionUuid = null): array
{
return $this->http()
->post("/sessions/{$sessionUuid ?? $this->sessionId}/whatsapp/messages", [
'to' => $to,
'text' => $text,
])
->throw()
->json();
}
public function messages(int $limit = 50, ?string $sessionUuid = null): array
{
return $this->http()
->get("/sessions/{$sessionUuid ?? $this->sessionId}/whatsapp/messages", [
'limit' => $limit,
])
->throw()
->json();
}
}
$client = new App\Services\WaCentraConnect(
baseUrl: config('services.wacentraconnect.url'),
token: config('services.wacentraconnect.token'),
sessionId: config('services.wacentraconnect.session_id'),
);
// Confirm the link is connected before sending. The API reports status as one of
// connecting, qr, open, reconnecting, disconnected, logged_out, error or suspended.
$state = $client->status();
if ($state['status'] !== 'open') {
throw new RuntimeException('Link not connected: '.($state['last_error'] ?? $state['status']));
}
// Send a message.
$client->sendText('+254700000000', 'Hello from Laravel');
// Read the latest messages, both directions, newest first.
$messages = $client->messages();
// routes/web.php — this endpoint lives on YOUR app (e.g. https://example.com/webhooks/wacentraconnect),
// not on WaCentra Connect API.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::post('/webhooks/wacentraconnect', function (Request $request) {
// Verify the delivery is genuinely from WaCentra Connect API.
$expected = 'sha256='.hash_hmac(
'sha256',
$request->header('X-Webhook-Event')."\n"
.$request->header('X-Webhook-Timestamp')."\n"
.$request->getContent(),
config('services.wacentraconnect.webhook_secret'),
);
abort_unless(hash_equals($expected, (string) $request->header('X-Webhook-Signature-V2')), 401);
match ($request->input('event')) {
'messages.received' => /* store the incoming message */ null,
'session.status' => /* react to connection changes */ null,
default => null,
};
return response()->noContent();
});
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->validateCsrfTokens(except: ['webhooks/wacentraconnect']);
})
WACENTRACONNECT_API_TOKEN
to authenticate each request.
2xx quickly and make the handler idempotent with
data.message_id. See the full
event catalog.
Node.js / Express#
A small Express-friendly client using the built-in fetch, plus an Express route that
verifies webhook deliveries.
# .env (see Environment variables above)
WACENTRACONNECT_API_URL=https://wacentraconnectapi.com/api/v1
WACENTRACONNECT_API_TOKEN=your_session_api_key
WACENTRACONNECT_SESSION_ID=6f1c1f0e-2b7a-4c8e-9d1a-0b2c3d4e5f60
WACENTRACONNECT_WEBHOOK_SECRET=your_webhook_secret
// wacentraconnect.js
const base = process.env.WACENTRACONNECT_API_URL;
const token = process.env.WACENTRACONNECT_API_TOKEN;
const session = process.env.WACENTRACONNECT_SESSION_ID;
async function request(path, options = {}) {
const response = await fetch(`${base}${path}`, {
...options,
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
...(options.headers || {}),
},
});
if (!response.ok) {
throw new Error(`${response.status} ${await response.text()}`);
}
return response.json();
}
export const status = (id = session) => request(`/sessions/${id}/whatsapp`);
export const sendText = (to, text, id = session) =>
request(`/sessions/${id}/whatsapp/messages`, {
method: 'POST',
body: JSON.stringify({ to, text }),
});
export const messages = (id = session) =>
request(`/sessions/${id}/whatsapp/messages`);
import { status, sendText, messages } from './wacentraconnect.js';
// Confirm the link is connected before sending.
const state = await status();
if (state.status !== 'open') {
throw new Error(`Link not connected: ${state.last_error || state.status}`);
}
await sendText('+254700000000', 'Hello from Node.js');
// Read the latest messages, both directions, newest first.
const latest = await messages();
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.post(
'/webhooks/wacentraconnect',
express.raw({ type: 'application/json' }),
(req, res) => {
// Verify the delivery is genuinely from WaCentra Connect API.
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.WACENTRACONNECT_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
const received = req.get('X-Webhook-Signature') || '';
const ok = received.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
if (!ok) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
// Handle messages.received, session.status, ...
return res.sendStatus(200);
},
);
Python / Flask#
A reusable client module using requests, plus a Flask view that verifies webhook
deliveries.
# .env (see Environment variables above)
WACENTRACONNECT_API_URL=https://wacentraconnectapi.com/api/v1
WACENTRACONNECT_API_TOKEN=your_session_api_key
WACENTRACONNECT_SESSION_ID=6f1c1f0e-2b7a-4c8e-9d1a-0b2c3d4e5f60
WACENTRACONNECT_WEBHOOK_SECRET=your_webhook_secret
# wacentraconnect.py
import os
import requests
BASE = os.environ["WACENTRACONNECT_API_URL"]
TOKEN = os.environ["WACENTRACONNECT_API_TOKEN"]
SESSION = os.environ["WACENTRACONNECT_SESSION_ID"]
def _request(method, path, **kwargs):
response = requests.request(
method,
f"{BASE}{path}",
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=15,
**kwargs,
)
response.raise_for_status()
return response.json()
def status(session_id=SESSION):
return _request("GET", f"/sessions/{session_id}/whatsapp")
def send_text(to, text, session_id=SESSION):
return _request(
"POST",
f"/sessions/{session_id}/whatsapp/messages",
json={"to": to, "text": text},
)
def messages(session_id=SESSION):
return _request("GET", f"/sessions/{session_id}/whatsapp/messages")
from wacentraconnect import status, send_text, messages
# Confirm the link is connected before sending.
state = status()
if state["status"] != "open":
raise RuntimeError(f"Link not connected: {state.get('last_error', state['status'])}")
send_text("+254700000000", "Hello from Flask")
# Read the latest messages, both directions, newest first.
latest = messages()
import hashlib
import hmac
import os
from flask import Flask, request
app = Flask(__name__)
@app.post("/webhooks/wacentraconnect")
def wacentraconnect_webhook():
body = request.get_data()
# Verify the delivery is genuinely from WaCentra Connect API.
expected = "sha256=" + hmac.new(
os.environ["WACENTRACONNECT_WEBHOOK_SECRET"].encode(),
body,
hashlib.sha256,
).hexdigest()
received = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(expected, received):
return "", 401
event = request.get_json()
# Handle messages.received, session.status, ...
return "", 204
Python / Django#
A service module that reads credentials from Django settings, plus a CSRF-exempt view that verifies webhook deliveries.
# myproject/settings.py
WACENTRACONNECT_API_URL = env("WACENTRACONNECT_API_URL")
WACENTRACONNECT_API_TOKEN = env("WACENTRACONNECT_API_TOKEN")
WACENTRACONNECT_SESSION_ID = env("WACENTRACONNECT_SESSION_ID")
WACENTRACONNECT_WEBHOOK_SECRET = env("WACENTRACONNECT_WEBHOOK_SECRET")
# myapp/services/wacentraconnect.py
import requests
from django.conf import settings
BASE = settings.WACENTRACONNECT_API_URL
TOKEN = settings.WACENTRACONNECT_API_TOKEN
SESSION = settings.WACENTRACONNECT_SESSION_ID
def _request(method, path, **kwargs):
response = requests.request(
method,
f"{BASE}{path}",
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=15,
**kwargs,
)
response.raise_for_status()
return response.json()
def status(session_id=SESSION):
return _request("GET", f"/sessions/{session_id}/whatsapp")
def send_text(to, text, session_id=SESSION):
return _request(
"POST",
f"/sessions/{session_id}/whatsapp/messages",
json={"to": to, "text": text},
)
def messages(session_id=SESSION):
return _request("GET", f"/sessions/{session_id}/whatsapp/messages")
from myapp.services.wacentraconnect import status, send_text, messages
# Confirm the link is connected before sending.
state = status()
if state["status"] != "open":
raise RuntimeError(f"Link not connected: {state.get('last_error', state['status'])}")
send_text("+254700000000", "Hello from Django")
# Read the latest messages, both directions, newest first.
latest = messages()
# myapp/views.py
import hashlib
import hmac
import json
from django.conf import settings
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
@csrf_exempt
def wacentraconnect_webhook(request):
if request.method != "POST":
return HttpResponse(status=405)
body = request.body
# Verify the delivery is genuinely from WaCentra Connect API.
expected = "sha256=" + hmac.new(
settings.WACENTRACONNECT_WEBHOOK_SECRET.encode(),
body,
hashlib.sha256,
).hexdigest()
received = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(expected, received):
return HttpResponse(status=401)
event = json.loads(body)
# Handle messages.received, session.status, ...
return HttpResponse(status=204)
# myproject/urls.py
from django.urls import path
from myapp.views import wacentraconnect_webhook
urlpatterns = [
path("webhooks/wacentraconnect", wacentraconnect_webhook),
]
Flutter#
A Dart client for your Flutter app. Pass credentials at build time with
--dart-define so they never live in source control.
# pubspec.yaml
dependencies:
http: ^1.2.0
# Run with credentials injected at build time.
flutter run \
--dart-define=WACENTRACONNECT_API_URL=https://wacentraconnectapi.com/api/v1 \
--dart-define=WACENTRACONNECT_API_TOKEN=your_session_api_key \
--dart-define=WACENTRACONNECT_SESSION_ID=6f1c1f0e-2b7a-4c8e-9d1a-0b2c3d4e5f60
// lib/wacentraconnect.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
class WaCentraConnect {
WaCentraConnect({
required this.baseUrl,
required this.token,
required this.sessionId,
});
final String baseUrl;
final String token;
final String sessionId;
Map<String, String> get _headers => {
'Authorization': 'Bearer $token',
'Content-Type': 'application/json',
};
Future<Map<String, dynamic>> status() async {
final res = await http.get(
Uri.parse('$baseUrl/sessions/$sessionId/whatsapp'),
headers: _headers,
);
return _decode(res);
}
Future<Map<String, dynamic>> sendText(String to, String text) async {
final res = await http.post(
Uri.parse('$baseUrl/sessions/$sessionId/whatsapp/messages'),
headers: _headers,
body: jsonEncode({'to': to, 'text': text}),
);
return _decode(res);
}
Future<Map<String, dynamic>> messages() async {
final res = await http.get(
Uri.parse('$baseUrl/sessions/$sessionId/whatsapp/messages'),
headers: _headers,
);
return _decode(res);
}
Map<String, dynamic> _decode(http.Response res) {
if (res.statusCode >= 400) {
throw Exception('${res.statusCode} ${res.body}');
}
return jsonDecode(res.body) as Map<String, dynamic>;
}
}
final client = WaCentraConnect(
baseUrl: const String.fromEnvironment('WACENTRACONNECT_API_URL'),
token: const String.fromEnvironment('WACENTRACONNECT_API_TOKEN'),
sessionId: const String.fromEnvironment('WACENTRACONNECT_SESSION_ID'),
);
// Confirm the link is connected before sending.
final state = await client.status();
if (state['status'] != 'open') {
throw Exception('Link not connected: ${state['last_error'] ?? state['status']}');
}
await client.sendText('+254700000000', 'Hello from Flutter');
// Read the latest messages, both directions, newest first.
final latest = await client.messages();
Swift#
A Swift client for iOS and macOS using async/await and
URLSession.
// WaCentraConnectConfig.swift
import Foundation
enum WaCentraConnectConfig {
// Inject these from your build settings or a secrets file.
static let apiURL = URL(string: "https://wacentraconnectapi.com/api/v1")!
static let token = "your_session_api_key"
static let sessionID = "6f1c1f0e-2b7a-4c8e-9d1a-0b2c3d4e5f60"
}
// WaCentraConnect.swift
import Foundation
struct WaCentraConnect {
let baseURL: URL
let token: String
let sessionID: String
private func request(
_ path: String,
method: String = "GET",
body: [String: Any]? = nil
) async throws -> [String: Any] {
var request = URLRequest(url: baseURL.appendingPathComponent(path))
request.httpMethod = method
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
if let body = body {
request.httpBody = try JSONSerialization.data(withJSONObject: body)
}
let (data, response) = try await URLSession.shared.data(for: request)
guard let http = response as? HTTPURLResponse,
(200..<300).contains(http.statusCode) else {
throw NSError(domain: "WaCentra Connect API", code: 0, userInfo: [
NSLocalizedDescriptionKey: String(data: data, encoding: .utf8) ?? "",
])
}
return try JSONSerialization.jsonObject(with: data) as? [String: Any] ?? [:]
}
func status() async throws -> [String: Any] {
try await request("sessions/\(sessionID)/whatsapp")
}
func sendText(to: String, text: String) async throws -> [String: Any] {
try await request(
"sessions/\(sessionID)/whatsapp/messages",
method: "POST",
body: ["to": to, "text": text],
)
}
func messages() async throws -> [String: Any] {
try await request("sessions/\(sessionID)/whatsapp/messages")
}
}
let client = WaCentraConnect(
baseURL: WaCentraConnectConfig.apiURL,
token: WaCentraConnectConfig.token,
sessionID: WaCentraConnectConfig.sessionID
)
// Confirm the link is connected before sending.
let state = try await client.status()
if state["status"] as? String != "open" {
throw NSError(domain: "WaCentra Connect API", code: 1)
}
try await client.sendText(to: "+254700000000", text: "Hello from Swift")
// Read the latest messages, both directions, newest first.
let latest = try await client.messages()
Postman & OpenAPI#
The full specification is published at https://wacentraconnectapi.com/openapi.json.
Import it into Postman, Insomnia, or a client generator, then set the base URL to
https://wacentraconnectapi.com/api/v1 and add your Bearer token.
# Download the spec
curl -O https://wacentraconnectapi.com/openapi.json
# Use it with a generator, e.g. openapi-typescript
npx openapi-typescript https://wacentraconnectapi.com/openapi.json -o wacentraconnect.d.ts
© 2026 WaCentra Connect API. All rights reserved.