Sender validation

The from field identifies a Sender

Every send request requires from. Use the connected WhatsApp number in E.164 format, including the leading plus sign and country code. Yanola does not support from: "default" and does not require a provider phone-number ID.

The API key supplies the Agent Project boundary, so the same phone number cannot be borrowed from another project or account.

Select an API-eligible Sender

List Senders using the same API key that will perform the send. The response reflects the key environment, Agent Project, key restrictions, and effective platform controls.

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 { data: senders } = await yanola.senders.list()
const sender = senders.find((item) => item.apiEligible)

if (!sender) {
  throw new Error("No API-eligible Sender is available")
}

console.log(sender.phoneNumber)

Validation performed before a send

1. The key must have messages:write and an active Developer Platform entitlement.
2. from and to must be valid E.164 phone numbers.
3. The Sender must belong to the key's Yanola Account and Agent Project.
4. If the key is restricted to selected Senders, the Sender must be in that set.
5. The Sender must be active and the public API operation must not be disabled.
6. Live Mode also requires usable stored provider credentials; Test Mode does not access provider credentials.
7. Non-template Live Mode sends must pass the Customer Service Window check.

Sender errors

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"
    }
  }
}