API de WhatsApp — AMAI Voice (referencia para desarrolladores)

curl -X POST https://voice.amai.run/api/v1/whatsapp/send \
  -H "Authorization: Bearer amai_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+34600111222", "type": "text", "text": "Hola desde AMAI Voice" }'

{ "success": true, "message_id": "<connectionId>:wamid.HBg..." }

Authorization: Bearer amai_TU_API_KEY

curl -X POST https://voice.amai.run/api/v1/whatsapp/send \
  -H "Authorization: Bearer amai_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+34600111222", "type": "text", "text": "Este es un mensaje de prueba" }'

curl -X POST https://voice.amai.run/api/v1/whatsapp/send \
  -H "Authorization: Bearer amai_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+34600111222",
    "type": "template",
    "template_name": "recordatorio_reunion",
    "template_language": "es",
    "template_components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Juan" },
        { "type": "text", "text": "15 de julio a las 14:30" }
      ] }
    ]
  }'

async function sendWhatsApp(to, text) {
  const res = await fetch("https://voice.amai.run/api/v1/whatsapp/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, type: "text", text }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data; // { success: true, message_id }
}

import os, requests

def send_whatsapp(to, text=None, template_name=None):
    payload = {"to": to, "type": "template" if template_name else "text"}
    if template_name:
        payload["template_name"] = template_name
        payload["template_language"] = "es"
    else:
        payload["text"] = text
    r = requests.post(
        "https://voice.amai.run/api/v1/whatsapp/send",
        headers={"Authorization": f"Bearer {os.environ['AMAI_API_KEY']}"},
        json=payload,
    )
    data = r.json()
    if r.status_code != 200:
        raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
    return data

curl -H "Authorization: Bearer amai_TU_API_KEY" \
  "https://voice.amai.run/api/v1/whatsapp/messages?direction=inbound&limit=20"

{
  "messages": [
    {
      "id": "…uuid…",
      "connection_id": "…uuid…",
      "distributor_id": "…uuid…",
      "wamid": "<connId>:wamid.HBg…",
      "direction": "inbound",
      "from_number": "+34600111222",
      "to_number": "+34 912 91 87 50",
      "contact_name": "Juan García",
      "message_type": "text",
      "body": "Hola, necesito ayuda",
      "media_url": null,
      "media_mime_type": null,
      "template_name": null,
      "template_language": null,
      "status": "delivered",
      "timestamp": "2026-07-11T14:23:45+00:00"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

{
  "event": "whatsapp.message.received",
  "timestamp": "2026-07-11T14:23:45.123Z",
  "data": {
    "connection_id": "…",
    "message_id": "<connId>:wamid…",
    "wamid": "wamid…",
    "direction": "inbound",
    "from_number": "+34600111222",
    "to_number": "+34 912 91 87 50",
    "contact_name": "Juan García",
    "message_type": "text",
    "body": "Hola, necesito ayuda",
    "media_mime_type": null,
    "timestamp": "2026-07-11T14:23:45+00:00"
  }
}

import crypto from "node:crypto";
// req.body debe ser el buffer CRUDO (express.raw), no el objeto parseado.
function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

curl -H "Authorization: Bearer amai_TU_API_KEY" \
  "https://voice.amai.run/api/v1/whatsapp/templates?status=APPROVED"

{
  "templates": [
    {
      "name": "recordatorio_reunion",
      "status": "APPROVED",
      "category": "UTILITY",
      "language": "es",
      "variables": 2,
      "body_text": "Hola {{1}}, te recordamos tu reunion con AMAI programada para {{2}}."
    }
  ]
}

res = send_whatsapp(to, text="Gracias por tu mensaje")
if res is None: ...  # (según tu wrapper)
# o, capturando el 422:
#   si error.code == "outside_24h_window": send_whatsapp(to, template_name="bienvenida_cliente")

POST /api/v1/whatsapp/check

curl -sS -X POST https://voice.amai.run/api/v1/whatsapp/check \
  -H "Authorization: Bearer amai_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"recipients":["+34612345678","+34912345678","612345678"],"default_country":"ES"}'

{
  "checked": 3,
  "contactable": 2,
  "results": [
    {
      "input": "+34612345678",
      "contactable": true,
      "line_type": "mobile",
      "whatsapp_registered": "unknown",
      "send_mode": "template_required",
      "window_expires_at": null,
      "reason": null
    },
    {
      "input": "+34912345678",
      "contactable": false,
      "line_type": "fixed_line",
      "whatsapp_registered": "unknown",
      "send_mode": null,
      "reason": "fixed_line",
      "message": "Es un número fijo. WhatsApp vive en numeración móvil..."
    }
  ]
}

{ "error": { "code": "<slug>", "message": "<texto>", "meta_code": <número|null> } }

import os, json, hmac, hashlib
from flask import Flask, request
import requests

app = Flask(__name__)
API = "https://voice.amai.run/api/v1/whatsapp"
KEY = os.environ["AMAI_API_KEY"]
SECRET = os.environ["AMAI_WEBHOOK_SECRET"]
seen = set()

def verify(raw, sig):
    exp = "sha256=" + hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    return sig and hmac.compare_digest(sig, exp)

def send(to, text=None, template=None):
    p = {"to": to, "type": "template" if template else "text"}
    if template: p["template_name"] = template; p["template_language"] = "es"
    else: p["text"] = text
    return requests.post(f"{API}/send", headers={"Authorization": f"Bearer {KEY}"}, json=p).json()

@app.post("/webhook/whatsapp")
def hook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("X-AMAI-Signature")):
        return {"error": "bad signature"}, 401
    dl = request.headers.get("X-AMAI-Delivery")
    if dl in seen: return {"ok": True}, 200
    seen.add(dl)
    p = json.loads(raw)
    if p.get("event") == "whatsapp.message.received":
        d = p["data"]
        txt = (d.get("body") or "").lower()
        reply = "En que puedo ayudarte?" if "hola" in txt else "Gracias por tu mensaje."
        r = send(d["from_number"], text=reply)
        if r.get("error", {}).get("code") == "outside_24h_window":
            send(d["from_number"], template="bienvenida_cliente")
    return {"ok": True}, 200

[Webhook node]  <- recibe whatsapp.message.received
      |
[Code]  verifica X-AMAI-Signature (HMAC-SHA256 sobre el body crudo)
      |
[IF]  data.direction == "inbound"
      |
[HTTP Request]  POST https://voice.amai.run/api/v1/whatsapp/send
      headers: Authorization: Bearer amai_TU_API_KEY
      body:    { "to": "{{ $json.data.from_number }}", "type": "text", "text": "..." }

Automatizas WhatsApp con AMAI Voice. Base: https://voice.amai.run
Auth: Authorization: Bearer <AMAI_API_KEY>   (env var AMAI_API_KEY; no hay token de Meta)
Enviar:  POST /api/v1/whatsapp/send
  texto:     { "to":"+34...", "text":"..." }
  plantilla: { "to":"+34...", "type":"template", "template_name":"...", "template_language":"es",
               "template_components":[{"type":"body","parameters":[{"type":"text","text":"..."}]}] }
Recibir: GET /api/v1/whatsapp/messages?direction=inbound&limit=20   (dedupe por id)
Plantillas: GET /api/v1/whatsapp/templates   (usa los name aprobados)
Push: evento whatsapp.message.received con firma HMAC en X-AMAI-Signature (verifícala).
Errores: envelope { error:{ code, message, meta_code } }. 422 code=outside_24h_window => manda plantilla.
Regla 24h: texto libre solo dentro de 24h del ultimo inbound del cliente; fuera, plantilla.
Limites: ~60 req/min; enviar solo a quien dio opt-in; la clave solo ve tu tenant.