WhatsApp agents

from niadra import Niadra, phone, system_id, whatsapp, whatsapp_bsuid

niadra = Niadra(channel="whatsapp")

def on_message(msg):
    niadra.track({
        "conversation_id": "wa-8812",
        "idempotency_key": msg["id"],  # wamid.HBgL...
        "handles": [
            whatsapp(msg["from"]),  # 14155550123
            whatsapp_bsuid(msg["user_id"], "waba-301"),
        ],
        "speaker": {"role": "customer"},
        "content": {"text": msg["text"]["body"]},
        "occurred_at": msg["timestamp_iso"],
    })

import { Niadra, handles } from "@niadra/sdk";

const niadra = new Niadra();

function onMessage(msg: WhatsAppMessage) {
  niadra.track({
    channel: "whatsapp",
    conversation_id: "wa-8812",
    idempotency_key: msg.id, // wamid.HBgL...
    handles: [handles.waId(msg.from), handles.waBsuid(msg.userId, "waba-301")],
    speaker: "customer",
    text: msg.text.body,
    occurred_at: msg.timestampIso,
  });
}

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/batch" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "type": "event",
      "kind": "message",
      "idempotency_key": "wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQzQUQ",
      "channel": "whatsapp",
      "conversation_id": "wa-8812",
      "handles": [
        { "type": "wa_id", "value": "14155550123" },
        { "type": "wa_bsuid", "value": "US.1098341", "scope": "waba-301" }
      ],
      "speaker": { "role": "customer" },
      "direction": "inbound",
      "content": { "type": "text", "text": "The technician never showed up. I am calling you." },
      "occurred_at": "2026-09-22T17:02:11Z"
    }]
  }'

niadra.identify(
    [whatsapp("14155550123"), phone("+14155550123"), system_id("crm", "48213")],
    method="system_import",
)

await niadra.identify({
  handles: [handles.waId("14155550123"), handles.phone("+14155550123"), handles.systemId("48213", "crm")],
  method: "system_import",
});

with niadra.conversation("wa-8812", subject=whatsapp("14155550123"), view="chat") as conversation:
    ctx = conversation.context()
    reply = llm.reply(system=[AGENT_INSTRUCTIONS, ctx.system_block], messages=history, suffix=ctx.turn_block)
    conversation.agent(reply)

const conversation = niadra.conversation({
  subject: handles.waId("14155550123"),
  channel: "whatsapp",
  conversation_id: "wa-8812",
});
const ctx = await conversation.context();
const reply = await llm.reply({ system: [AGENT_INSTRUCTIONS, ctx.text], messages: history, suffix: ctx.suffix });
conversation.agent(reply);

niadra.verify(
    "otp_whatsapp",
    "V3",
    handle=whatsapp("14155550123"),
    conversation_id="wa-8812",
)
ctx = conversation.context(verification="V3")

await conversation.verify({ method: "otp_whatsapp", level: "V3" });
const ctx = await conversation.context(); // re-pinned at the new level

media = niadra.upload_media(voice_note_bytes, "audio/ogg", subject=whatsapp("14155550123"))

if media:
    niadra.track({
        "conversation_id": "wa-8812",
        "idempotency_key": "wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQ0QkE",
        "handles": [whatsapp("14155550123")],
        "speaker": {"role": "customer"},
        "content": {
            "type": "audio",
            "media_ref": media.media_ref,
            "media_sha256": media.media_sha256,
            "transcript": "He was supposed to come between eight and noon.",
            "stt_confidence": 0.93,
        },
    })

const { data: media } = await niadra.uploadMedia({
  data: voiceNote,
  content_type: "audio/ogg",
  subject: handles.waId("14155550123"),
});

if (media) {
  conversation.track({
    idempotency_key: "wamid.HBgLMTQxNTU1NTAxMjMVAgASGBQ0QkE",
    speaker: "customer",
    content: {
      type: "audio",
      media_ref: media.media_ref,
      media_sha256: media.media_sha256,
      transcript: "He was supposed to come between eight and noon.",
      stt_confidence: 0.93,
    },
  });
}

# 1. Reserve the upload; the answer carries upload_url and upload_headers
curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/media/uploads" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content_type": "audio/ogg", "size_bytes": 48213, "sha256": "a3f1c2d4e5b6978812ab34cd56ef7890a1b2c3d4e5f60718293a4b5c6d7e8f90",
        "subject": { "type": "wa_id", "value": "14155550123" } }'

# 2. PUT the bytes with exactly the headers of upload_headers
curl -X PUT "$UPLOAD_URL" -H "Content-Type: audio/ogg" -H "x-amz-checksum-sha256: <value from upload_headers>" --data-binary @note.ogg