Sample Integration

const TRYVOX_AUTH_ID = process.env.TRYVOX_AUTH_ID;
const TRYVOX_AUTH_TOKEN = process.env.TRYVOX_AUTH_TOKEN;
const CHANNEL_ID = process.env.TRYVOX_CHANNEL_ID;

const authHeader = "Basic " + Buffer.from(`${TRYVOX_AUTH_ID}:${TRYVOX_AUTH_TOKEN}`).toString("base64");

async function sendMessage(body) {
  const res = await fetch("https://api.tryvox.io/v1/messaging/messages", {
    method: "POST",
    headers: { Authorization: authHeader, "Content-Type": "application/json" },
    body: JSON.stringify({ channel_id: CHANNEL_ID, ...body }),
  });

  const parsed = await res.json();
  if (!res.ok) {
    const err = new Error(parsed?.error?.message || `TryVox returned ${res.status}`);
    err.status = res.status;
    err.code = parsed?.error?.code;
    throw err;
  }
  return parsed.data;
}

async function sendTemplateMessage(to, templateName, templateParams = []) {
  return sendMessage({
    to,
    message_type: "template",
    template_name: templateName,
    // A real array of Meta's component objects — never a JSON-stringified
    // string, and never wrapped as {language, components}. TryVox reads
    // the template's language from what you registered; you don't send
    // it here.
    template_params: templateParams,
  });
}

// Only works inside the 24-hour customer service window — see step 3.
// Outside it, TryVox returns 403 OUTSIDE_CS_WINDOW; send a template instead.
async function sendTextMessage(to, content) {
  return sendMessage({ to, message_type: "text", content });
}

try {
  const message = await sendTemplateMessage("+14155551234", "hello_world");
  console.log(`Accepted — message_id=${message.id}, status=${message.status}`);
} catch (err) {
  if (err.status === 422) {
    // Meta looked at the request and rejected it (bad params, permission or
    // verification issue, recipient not opted in, ...). Fix the request —
    // retrying unchanged fails the same way. err.message has Meta's reason.
    console.error(`Rejected: ${err.message}`);
  } else if (err.status === 502) {
    // TryVox couldn't reach Meta at all — transient, safe to retry with backoff.
    console.error(`Upstream unavailable: ${err.message}`);
  } else {
    console.error(`Send failed (${err.status}): ${err.message}`);
  }
}

const res = await fetch("https://api.tryvox.io/v1/notifications/webhooks", {
  method: "POST",
  headers: { Authorization: authHeader, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://your-app.example.com/webhooks/tryvox",
    events: ["message.sent", "message.received", "message.delivered", "message.read", "message.failed"],
  }),
});
const { data } = await res.json();
console.log(`Subscribed. Save this secret — it won't be shown again: ${data.secret}`);

import crypto from "node:crypto";
import express from "express";

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; // from step 2

function verifySignature(rawBody, req) {
  const header = req.header("X-TryVox-Signature"); // t=<timestamp>,v1=<hex>
  if (!header) return false;
  const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header);
  if (!match) return false;
  const [, timestamp, v1] = match;

  // Reject stale deliveries — defeats replay attacks with a captured signature.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const signedContent = Buffer.concat([Buffer.from(timestamp), Buffer.from("."), rawBody]);
  const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(signedContent).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

app.post(
  "/webhooks/tryvox",
  express.raw({ type: "application/json" }), // raw bytes — the signature covers the exact bytes TryVox sent
  (req, res) => {
    if (!verifySignature(req.body, req)) {
      return res.status(401).json({ error: "invalid signature" });
    }

    const event = JSON.parse(req.body.toString("utf8")); // flat payload, no {event, data} wrapper
    const type = req.header("X-TryVox-Event");

    // Acknowledge immediately — TryVox retries on anything but 2xx, and
    // doesn't wait for your business logic to finish.
    res.status(200).json({ received: true });

    switch (type) {
      case "message.sent":
        console.log(`Sent to ${event.phone_number}: whatsapp_message_id=${event.whatsapp_message_id}`);
        break;
      case "message.delivered":
        console.log(`Delivered: message_id=${event.message_id}`);
        break;
      case "message.read":
        console.log(`Read: message_id=${event.message_id}`);
        break;
      case "message.failed":
        console.log(`Failed: message_id=${event.message_id} — ${event.error_code} ${event.error_message}`);
        break;
      case "message.received":
        // The webhook only tells you a message arrived, not what it says —
        // see step 4 for handleInboundMessage().
        handleInboundMessage(event).catch((err) => console.error("failed to handle inbound message:", err));
        break;
    }
  }
);

app.listen(4000, () => console.log("Webhook receiver listening on :4000/webhooks/tryvox"));

async function getMessage(conversationId, messageId) {
  // Messages come back newest-first, so the one the webhook just told you
  // about is normally index 0 — but fetch a few and match by id in case
  // another message landed in the moment between the webhook firing and
  // this call.
  const res = await fetch(
    `https://api.tryvox.io/v1/messaging/conversations/${conversationId}/messages?limit=5`,
    { headers: { Authorization: authHeader } }
  );
  const { data } = await res.json();
  return data.find((m) => m.id === messageId) ?? data[0];
}

async function downloadMedia(messageId) {
  const res = await fetch(`https://api.tryvox.io/v1/messaging/messages/${messageId}/media`, {
    headers: { Authorization: authHeader },
  });
  if (!res.ok) throw new Error(`media not ready or not found (${res.status})`);
  return { contentType: res.headers.get("content-type"), bytes: Buffer.from(await res.arrayBuffer()) };
}

// TryVox broadcasts message.received as soon as the message row exists —
// deliberately before media finishes downloading from Meta, so the
// notification isn't held up by a slow transfer. That means has_media is
// very often still false the instant your webhook fires, for a message
// that succeeds moments later. Poll briefly rather than downloading once
// and giving up.
async function waitForMediaReady(conversationId, messageId, { retries = 5, delayMs = 1500 } = {}) {
  for (let i = 0; i < retries; i++) {
    const message = await getMessage(conversationId, messageId);
    if (message.has_media) return true;
    if (message.media_download_status === "failed") return false; // won't resolve on its own
    await new Promise((r) => setTimeout(r, delayMs));
  }
  return false; // still pending after all retries — check back later
}

async function handleInboundMessage(event) {
  const message = await getMessage(event.conversation_id, event.message_id);
  if (!message) return;

  switch (message.message_type) {
    case "text":
      console.log(`Text from ${event.phone_number}: "${message.content}"`);
      // Real reply, not the webhook receiver's ack — this actually messages
      // the customer back, and only works inside the 24-hour window.
      await sendTextMessage(event.phone_number, `Got it: "${message.content}"`);
      break;

    case "image":
    case "video":
    case "audio":
    case "document": {
      const ready = await waitForMediaReady(event.conversation_id, message.id);
      if (!ready) {
        // Either still downloading past your retry budget, or Meta's fetch
        // failed — POST /v1/messaging/messages/{id}/media/retry-download
        // forces another attempt on a failed one.
        console.log(`Media not ready for message ${message.id} (status: ${message.media_download_status})`);
        break;
      }
      const { contentType, bytes } = await downloadMedia(message.id);
      console.log(`Received ${message.message_type} (${contentType}, ${bytes.length} bytes)`);
      // e.g. fs.writeFileSync(...) or upload to your own storage here.
      break;
    }

    case "interactive":
      // content is a human-readable summary (e.g. the button's label);
      // interactive_payload has the full structured reply if you need to
      // branch on a button/list id rather than the label text.
      console.log(`Button/list reply: "${message.content}"`, message.interactive_payload);
      break;

    default:
      console.log(`Unhandled message_type: ${message.message_type}`);
  }
}