Quickstart

This walks you from zero to a delivered template message.

Prerequisites

An OonoBox workspace with a connected WhatsApp number (Settings → Numbers).
An approved template (Settings → Templates). For this guide we'll use one named order_update with two variables.
An API key with the messages.send scope (Settings → API keys). See Authentication.

1. Set your key

export OONO_KEY="oono_sk_live_xxxxxxxxxxxxxxxx"

2. Send a template

Templates can be sent at any time (no 24-hour window restriction).

curl -X POST https://api.oonobox.co.zw/api/v1/messages/template \
  -H "Authorization: Bearer $OONO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "263771234567",
    "template": "order_update",
    "variables": { "1": "Tariro", "2": "shipped" }
  }'

{ "messageId": "msg_01k...", "conversationId": "conv_01k...", "status": "sent" }

That's it — the message is delivered and appears in your OonoBox inbox under the contact's conversation.

In your language

Node.js (18+)

const OONO_KEY = process.env.OONO_KEY;
const BASE = "https://api.oonobox.co.zw/api";

async function sendTemplate(to, template, variables = {}) {
  const res = await fetch(`${BASE}/v1/messages/template`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${OONO_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, template, variables }),
  });
  if (!res.ok) throw new Error(`Send failed: ${res.status} ${await res.text()}`);
  return res.json();
}

await sendTemplate("263771234567", "order_update", { "1": "Tariro", "2": "shipped" });

Python 3.8+

import os, requests

OONO_KEY = os.environ["OONO_KEY"]
BASE = "https://api.oonobox.co.zw/api"

def send_template(to, template, variables=None):
    r = requests.post(
        f"{BASE}/v1/messages/template",
        json={"to": to, "template": template, "variables": variables or {}},
        headers={"Authorization": f"Bearer {OONO_KEY}", "Content-Type": "application/json"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

send_template("263771234567", "order_update", {"1": "Tariro", "2": "shipped"})

Media-header templates

If your template has an image, video, or document header, pass a public https link to the file:

curl -X POST https://api.oonobox.co.zw/api/v1/messages/template \
  -H "Authorization: Bearer $OONO_KEY" -H "Content-Type: application/json" \
  -d '{
    "to": "263771234567",
    "template": "receipt",
    "variables": { "1": "Tariro" },
    "headerMediaLink": "https://example.com/receipt.pdf"
  }'

Replying with free text

Once a customer messages you, you can reply with free-form text for 24 hours:

curl -X POST https://api.oonobox.co.zw/api/v1/messages/text \
  -H "Authorization: Bearer $OONO_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "263771234567", "body": "Thanks! Anything else I can help with?" }'

Outside that window, free text is rejected (WINDOW_CLOSED) — send a template instead.

Next steps

Browse the full API reference for every field and response.
Read about Errors so your integration handles failures cleanly.