Send your first test message with Buddy

Connect your application, send a simulated WhatsApp message and follow its status. Test mode works without a WhatsApp number and never sends to a real person.

Before you start

Accept your customer invitation, create your account and complete workspace setup. Test mode needs no WhatsApp connection. Node.js and Python examples below use the published Buddy SDKs; cURL calls the HTTP API directly. All three use https://usebuddy.app/api/v1.

Run examples on your server or development computer. Choose a language tab for its installation and run instructions. The endpoint reference also provides dependency-free HTTP examples.

1. Create a test key

Open the developer dashboard, choose test mode and create a key with subscribers:read, subscribers:write, templates:read, messages:send, messages:read and webhooks:write scopes. Copy the secret when it is shown, then store it in your server environment as BUDDY_API_KEY.

Never put an API key in browser JavaScript, a mobile app, a public repository or a screenshot.

For a local test in bash or zsh, set the key in your terminal. Replace the placeholder with your test key; do not commit it to a file.

Set your test key

export BUDDY_API_KEY="YOUR_TEST_KEY"

In PowerShell, use $env:BUDDY_API_KEY="YOUR_TEST_KEY".

2. Check your connection

The response identifies your workspace, scopes and mode. The response is wrapped in data. Check that data.livemode is false before continuing.

Run in bash or zsh with curl 7.76 or newer. Set BUDDY_API_KEY in the same terminal first.

curl --fail-with-body --request GET 'https://usebuddy.app/api/v1/me' \
  --header "Authorization: Bearer $BUDDY_API_KEY"

3. Send a sandbox message

Use the sandbox template and test number below. Choose a unique Idempotency-Key for this operation. A 202 response means the message is queued; use its returned id with GET /messages/{id} to follow delivery and read status.

Set a unique operation ID before sending. Keep the same value and body when retrying this send; change it only for a deliberately new message.

Identify this operation (bash or zsh)

export BUDDY_OPERATION_ID="$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"

Without Node.js, use export BUDDY_OPERATION_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')". In PowerShell, use $env:BUDDY_OPERATION_ID=[guid]::NewGuid().ToString().

Run in bash or zsh with curl 7.76 or newer. Set BUDDY_API_KEY in the same terminal first.

curl --fail-with-body --request POST 'https://usebuddy.app/api/v1/messages' \
  --header "Authorization: Bearer $BUDDY_API_KEY" \
  --header "Idempotency-Key: $BUDDY_OPERATION_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "to": "+15550000001",
  "template": "buddy_test_hello",
  "language": "en",
  "variables": [
    "Amira"
  ],
  "transactional": true
}'

The returned message is under data: save data.id and inspect data.status. It starts queued and progresses asynchronously. The sandbox number above simulates delivery and a read receipt.

4. Receive a webhook

In test-mode Webhooks, add an HTTPS endpoint you control and subscribe to message.delivered and message.read. Save its signing secret on your server. Verify the signature against the raw request body, store the event id to deduplicate retries, then return a 2xx response promptly.

Follow the webhook guide and use “Send test event” to check delivery. Your dashboard shows each attempt and response status.

Build the real journey

Use the integration workflows to plan notifications, OTPs, campaigns or event-driven journeys. Collect consent, connect your WhatsApp account and choose an approved template. Keep live credentials separate from test credentials. See consent and messaging windows before sending.