Sending text messages

Send a text message

Use client.messages.sendText from a trusted server. The API key needs messages:write, and from must be an API-eligible Sender connected to the key's Agent Project.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const accepted = await yanola.messages.sendText({
  from: "+15557654321",
  to: "+15551234567",
  body: "Your order is ready for pickup.",
  previewUrl: false,
})

console.log(accepted.id)

Request fields

Customer Service Window

In Live Mode, a text, media, location, or contact-card send is allowed only when Yanola has evidence that the recipient sent an inbound message to the same Sender during the previous 24 hours. Activity with another Sender does not open this window.

When no active window is known, Yanola returns 422 service_window_required before queueing the message or making a provider call. The error is not retryable: repeating the same non-template request cannot create a window.

1. Send an approved template that is appropriate for the business intent.
2. After the customer replies, use non-template messages during the new 24-hour window.
3. Do not catch the error and silently substitute unrelated template content.

{
  "error": {
    "type": "business_state_error",
    "code": "service_window_required",
    "message": "A text, media, location, or contact-card message requires an active Customer Service Window. Send an approved template instead.",
    "requestId": "req_...",
    "retryable": false,
    "details": {
      "from": "+15557654321",
      "to": "+15551234567"
    }
  }
}

Handle service_window_required

Catch YanolaBusinessStateError and branch on the stable code. This error means policy evidence is missing; it is not a transient network failure.

import {
  WhatsAppClient,
  YanolaBusinessStateError,
} from "@yanola/whatsapp"

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

try {
  await yanola.messages.sendText({
    from: "+15557654321",
    to: "+15551234567",
    body: "Your order is ready.",
  })
} catch (error) {
  if (
    error instanceof YanolaBusinessStateError &&
    error.code === "service_window_required"
  ) {
    // Start the conversation with the appropriate approved template.
    // Do not retry this text request unchanged.
  } else {
    throw error
  }
}

Asynchronous acceptance

Every send method returns a queued response after Yanola accepts the operation. A 202 response is not proof of provider delivery.

Live message IDs start with msg_; Test Mode IDs start with msg_test_. Keep the returned ID and request ID so you can correlate message retrieval, webhook events, logs, failures, and support requests.

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

Safe retries and idempotency

The SDK generates a unique Idempotency-Key for every send call and preserves it across automatic transport retries. If your job system owns retry identity, pass a stable idempotencyKey as the second argument.

The same key and request body return the original accepted response. Reusing the key with a different body returns 409 idempotency_key_reused. Yanola retains send idempotency records for at least 24 hours.

const accepted = await yanola.messages.sendText(
  {
    from: "+15557654321",
    to: "+15551234567",
    body: "Your order is ready for pickup.",
  },
  {
    idempotencyKey: "order-123-ready-notification",
  }
)