Quickstart

This guide starts from an empty Wabery project and sends your first WhatsApp reply. A new project can use the shared Wabery sandbox immediately: register your test phone with the project’s join code, send one normal inbound message, then reply from the SDK, CLI, or API.

Before you start

You need:

• a Wabery project; new signups get one during onboarding
• the sandbox join code for that project
• a phone with WhatsApp installed
• either wabery login completed, or a server-side key from Access → API keys

You do not need a dedicated WhatsApp Business number for this quickstart. The shared sandbox is enough to send your first reply.

Note

The join-code message only connects your phone to the project. It is not shown as a chat bubble. After WhatsApp confirms the code was sent, send a normal message like “hello from quickstart”; that creates the conversation you can reply to.

1. Create or pick a project

If you just signed up, Wabery creates your first project during onboarding and shows:

• the project join code, formatted like wab-ABC123
• a default API key, shown once
• the shared sandbox WhatsApp number

If you skipped that step, open the dashboard, create a project, then find its join code in Project settings. From the CLI, wabery projects list and wabery projects get "project_id" also return join_code plus the effective enrollment_channel.phone_number to message.

2. Sign in or set the API key

Install the CLI and run wabery login. It opens your browser, asks you to authorize the CLI, asks you to choose a project, creates a key scoped to that project, then shows the key once so you can paste it back into the waiting terminal. The CLI stores it in your local config:

npm i -g @wabery/cli
wabery login          # opens the browser; use --no-open on a headless box
wabery doctor         # confirms the saved key, project, and base URL work

No global install needed — run it on demand instead: npx wabery login (or pnpm dlx wabery login, bunx wabery login).

Want files for your app too? After login, run:

wabery init --name "My project"

That creates .env.wabery, wabery.config.json, and a wabery-webhook-handler.ts stub without overwriting existing files. You can skip it for this quickstart; it is just a scaffold for your real app.

Note

Prefer to manage the key yourself? Create one under Access → API keys (live keys are prefixed wab_live_) and set WABERY_API_KEY — it overrides the CLI config. Never ship a wab_live_ key to the browser or commit it to git. See Authentication.

3. Connect a test phone

Send the project’s join code to the shared Wabery sandbox number from the phone you want to test with. If the dashboard gives you a WhatsApp button, use it; it opens WhatsApp with the code prefilled.

CLI/agent path:

wabery projects list
wabery projects get "project_id"     # read join_code + enrollment_channel.phone_number

After the phone is connected, send a normal message to the same sandbox chat:

hello from quickstart

Now verify that the project has a channel and inspect the latest conversation:

wabery channels list
wabery conversations list
wabery conversations messages "conversation_..."

Use the sandbox channel_id and the new conversation_id in the send call below. If the conversation exists but has no inbound message yet, the join code registered the phone but the normal test message has not arrived; send one more WhatsApp message to the sandbox chat.

Note

Building customer onboarding instead of testing your own phone? Use registration intents to mint browser-safe WhatsApp links, or contacts.enroll when your server already has the phone number and opt-in evidence.

4. Choose a client

Use the TypeScript SDK, a normal HTTP library, the CLI, or cURL:

SDK

npm install @wabery/sdk

PHP

PHP 8.1 or newer with the cURL extension is sufficient. No Wabery package is required.

Python

python -m pip install requests

CLI

The wabery CLI installed in step 2 is ready.

cURL

cURL is already available on most development systems.

5. Reply to the conversation

Use the conversation_id from the inbound message you just sent. WhatsApp free-form replies require an open messaging window; outside that window, send an approved template instead.

SDK

send.ts

import { Wabery } from "@wabery/sdk";

const wabery = new Wabery();

await wabery.messages.send({
  channelId: "channel_...",
  conversationId: "conversation_...",
  text: "Thanks for your message",
});

PHP

send.php

<?php

$apiKey = getenv("WABERY_API_KEY");
if ($apiKey === false || $apiKey === "") {
    throw new RuntimeException("WABERY_API_KEY is not set");
}

$payload = json_encode([
    "channel_id" => "channel_...",
    "conversation_id" => "conversation_...",
    "text" => "Thanks for your message",
], JSON_THROW_ON_ERROR);

$handle = curl_init("https://api.wabery.com/v1/messages");
if ($handle === false) {
    throw new RuntimeException("Could not initialize cURL");
}

curl_setopt_array($handle, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$responseBody = curl_exec($handle);
if ($responseBody === false) {
    throw new RuntimeException(curl_error($handle));
}

$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
if ($status !== 202) {
    throw new RuntimeException("Wabery returned HTTP {$status}: {$responseBody}");
}

$message = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);
echo $message["id"] . PHP_EOL;

Python

send.py

import os

import requests

response = requests.post(
    "https://api.wabery.com/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['WABERY_API_KEY']}",
    },
    json={
        "channel_id": "channel_...",
        "conversation_id": "conversation_...",
        "text": "Thanks for your message",
    },
    timeout=(10, 30),
)
response.raise_for_status()

print(response.json()["id"])

CLI

wabery messages send \
  --channel-id "channel_..." \
  --conversation-id "conversation_..." \
  --text "Thanks for your message"

curl

curl https://api.wabery.com/v1/messages \
  -H "Authorization: Bearer $WABERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_...",
    "conversation_id": "conversation_...",
    "text": "Thanks for your message"
  }'

A successful call returns 202 Accepted with the queued message id. Delivery happens asynchronously. Within a few seconds, the reply should appear in the same WhatsApp sandbox chat where you sent the normal test message. Inspect it with wabery.messages.get("msg_..."), wabery messages get "msg_...", or the message.status webhook. For proactive WhatsApp sends to a phone number, use a dedicated channel and record contact opt-in first.

For reusable clients, error handling, media, and webhook verification, see PHP, Python, and API clients.

6. Receive the next message

Replies (and delivery statuses) arrive at your webhook as signed events — no polling required:

{
  "event": "message.received",
  "payload": {
    "object": "message",
    "content": "do you ship internationally?"
  }
}

Point an endpoint at Wabery and verify the signature — see Webhooks.

Next steps

Authentication

API keys and webhook signing secrets.

PHP, Python, and API clients

Reusable REST clients and the importable OpenAPI contract.

Sending messages

Text, templates, and the full send reference.

Registration intents

Link customers from your app with single-use WhatsApp onboarding links.

WhatsApp Flows

Collect structured data with in-chat forms.

Hosted functions

Run server-side TypeScript for workflow and tool logic.

CLI

Ship from your terminal.

WhatsApp MCP Server

Ship by describing it to Claude, ChatGPT, Cursor, or Codex.

Get your API key — free