Start here

Quickstart

Install the SDK, create a Test Mode API key, select a Sender, and accept your first WhatsApp message request.

DevelopersBeginnerAvailable

What this guide covers

Create an API key in an Agent Project and keep it on your server.
Install @yanola/whatsapp and initialize WhatsAppClient with YANOLA_API_KEY.
Use Test Mode first, then switch to a live key when your integration is ready.

Before you begin

This quickstart uses Test Mode so you can exercise the real Yanola API contract without sending a WhatsApp message or spending Yanola Balance.

Use Node.js 20 or newer in a trusted server environment.
Open an Agent Project with at least one connected WhatsApp number.
Confirm your subscription includes Developer Platform Test Mode.

1. Create a Test Mode API key

In Yanola, open your Agent Project, choose API, then API keys. Switch to Test Mode and create a key named Quickstart.

Keep the messages:write and senders:read scopes enabled. Yanola shows the complete secret once; copy it before closing the dialog.

The prefix selects the environment

A Test Mode credential starts with yalo_test_. A Live Mode credential starts with yalo_live_. The SDK has no separate environment switch—the key determines the environment for every request.

2. Install the Node.js SDK

Install the current beta release from your application's server package. The SDK is ESM-first and is not intended for browser bundles.

Terminal

bash

npm install @yanola/whatsapp@beta

3. Configure your server environment

Store the copy-once value in your local secret file or deployment secret manager. Keep that file out of version control.

.env

dotenv

YANOLA_API_KEY=your_copy_once_test_key

src/yanola.ts

import { WhatsAppClient } from "@yanola/whatsapp"

if (!process.env.YANOLA_API_KEY) {
  throw new Error("YANOLA_API_KEY is not configured")
}

export const yanola = new WhatsAppClient({
  apiKey: process.env.YANOLA_API_KEY,
})

Never expose the key

Do not use a browser-exposed variable such as NEXT_PUBLIC_YANOLA_API_KEY. Initialize WhatsAppClient only in server-only modules, route handlers, workers, or backend services.

4. Select an eligible Sender

A send request must name a real WhatsApp number connected to the same Agent Project as the API key. Listing Senders avoids relying on a number that was disconnected or is not API-eligible.

List Senders

import { yanola } from "./yanola"

const { data: senders } = await yanola.senders.list()
const sender = senders.find((candidate) => candidate.apiEligible)

if (!sender) {
  throw new Error("Connect an API-eligible WhatsApp Sender in Yanola")
}

5. Send a synthetic text message

Use an E.164 recipient such as +15551234567. Test Mode validates the request and creates synthetic message, event, and zero-cost usage records without calling the provider. Matching Test Mode webhook endpoints can receive test deliveries.

Send in Test Mode

const accepted = await yanola.messages.sendText({
  from: sender.phoneNumber,
  to: "+15551234567",
  body: "Hello from Yanola Test Mode",
})

console.log({
  id: accepted.id,
  environment: accepted.environment,
  status: accepted.status,
})

Accepted response

json

{
  "id": "msg_test_...",
  "environment": "test",
  "status": "queued",
  "from": "+15557654321",
  "to": "+15551234567",
  "requestId": "req_...",
  "createdAt": "2026-07-29T10:00:00.000Z"
}

Accepted is not delivered

Send methods return after Yanola accepts the asynchronous operation. Use the message ID in logs, retrieval calls, and webhook events to follow later state changes.

Next steps

Configure a Test Mode webhook endpoint and verify signatures against the raw request body.
Handle stable Yanola error codes and preserve idempotency when your own job owns retries.
Create a separate Live Mode key only after your Test Mode flow is complete.