Empezar con la API de AMAI Voice

De cero a tu primera llamada con éxito. Todo lo que hay debajo describe lo que el código hace hoy, no lo que promete un folleto: las tablas de esta página se generan del propio contrato y de las reglas de autorización que ejecuta el servidor.

• Base URL: https://voice.amai.run — o el dominio de tu proveedor, si contrataste con marca blanca. El contrato es idéntico.
• Autenticación: Authorization: Bearer amai_<key>
• Superficie: 134 operaciones en 29 dominios. 72 servidas siempre, 41 tras el interruptor de escritura y 12 en la superficie de gasto.
• Referencia interactiva: /docs/reference · catálogo completo: /docs/operations

1. Antes de empezar: qué plan necesitas

Emitir una API key es en sí mismo una función de pago. Requiere la capacidad manage_api_keys, y los planes gratuitos no la traen:

Si estás en Free o PAYG y no ves la sección de API Keys en el panel, no es un fallo: es el plan. Habla con tu distribuidor.

2. Emitir tu API key

1. Entra en el panel → API Keys (/app/api-keys).
2. Crea la clave. Se enseña una sola vez: se guarda hasheada y no hay forma de volver a verla. Si la pierdes, emites otra.
3. Guárdala en una variable de entorno. Nunca en el repositorio, nunca en código que llegue al navegador.

export AMAI_API_KEY="amai_..."
export AMAI_API_HOST="voice.amai.run"   # el tuyo, si contrataste con un revendedor

La clave no caduca por tiempo y es revocable al instante desde el mismo panel. Revocarla corta el acceso en la siguiente petición.

3. Tu primera llamada (60 segundos)

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/calls?limit=1"

Si responde 200, ya está: la clave es válida, tiene permiso y tu plan incluye la función. Si responde otra cosa, la sección 5 te dice exactamente cuál de las tres puertas te ha parado.

El tenant sale siempre de la clave. No existe ningún parámetro para consultar los datos de otra cuenta, ni en esta operación ni en ninguna. Es el único control de aislamiento que hay, y por eso no es negociable.

4. La triple puerta

Cada petición atraviesa tres controles independientes. Los tres tienen que decir que sí — con una salvedad sobre el segundo, que está en despliegue y se explica al final de esta sección:

petición → ① ¿la clave es válida?        → 401 si no
         → ② ¿la clave tiene el scope?   → 403 insufficient_scope
         → ③ ¿el plan incluye la función? → 403 capability_required
         → 200

1. La clave. Existe, no está revocada, y llega en Authorization: Bearer amai_…. Un Bearer que no sea una clave válida da 401 — nunca cae de vuelta a la sesión del navegador, para que una clave muerta no parezca viva.
2. El scope. Cada operación exige un permiso concreto (calls:read, whatsapp:send…). Los permisos se conceden al emitir la clave. Catálogo completo en la sección 14.
3. La capacidad del plan. Es una propiedad de la cuenta, no de quien llama. La misma cuenta no puede tener una función por cookie y no tenerla por clave: se comprueba igual en los dos caminos, y sin caché, para que quitar una función corte el acceso de inmediato.

Y hay una cuarta puerta, solo para las operaciones que gastan dinero. Está en la sección 7.

Hasta dónde llega hoy la puerta ②

La puerta ② está en despliegue, y conviene saber dónde deniega ya:

• Deniega hoy en la superficie de escritura, en la de gasto y en la Developer Capsule. Y en estas lecturas: contactos y listas de contactos (listado y ficha), la ficha de una campaña y sus listas, y la ficha de una subcuenta con su marca y su empaquetado. También en las cuatro lecturas nuevas del historial de campaña: sus inscripciones, sus intentos, los veredictos de cualificación y las citas. Ahí, una clave sin el scope recibe 403 insufficient_scope y no pasa. Ojo: el listado de campañas y el listado de subcuentas todavía no, aunque sus fichas sí.
• En el resto de las lecturas —y en las rutas de mensajería que llevan su propio preámbulo— el scope exigido se registra en el uso de la clave, pero todavía no deniega. Una clave válida de la cuenta llega a la operación aunque no lleve ese permiso declarado.

Lo que sí protege esas operaciones hoy son las puertas ① y ③: la clave tiene que ser válida y viva, y la función tiene que estar en el plan de la cuenta.

Qué significa para ti. Si emites una clave para un tercero y necesitas que el recorte de permisos sea efectivo ahora, no te apoyes solo en el scope: el control que ya muerde para todas las operaciones es la capacidad de la cuenta (sección 15), y quien la concede es tu distribuidor. Declara igualmente los scopes al emitir la clave: son los que empezarán a denegar cuando la puerta ② termine de desplegarse, y hacerlo hoy evita que ese día se te caiga una integración.

5. Los dos 403, y cómo distinguirlos

Es la confusión que más tiempo cuesta, así que va con su propia sección. Los dos son 403, los dos dicen «no puedes», y se arreglan en sitios distintos:

{ "error": { "code": "insufficient_scope", "message": "..." } }

→ Le falta el permiso a la clave. Lo arregla quien emitió la clave: emite otra con ese scope. Cambiar de plan no sirve de nada. Ojo al despliegue de la puerta ② (sección 4): hay operaciones que todavía no devuelven este 403 aunque a la clave le falte el permiso.

{ "error": { "code": "capability_required", "message": "Tu plan no incluye esta función (\"...\")..." } }

→ El plan de la cuenta no incluye la función. Emitir una clave nueva no cambia nada: daría el mismo 403. Lo arregla el plan contratado, o un permiso explícito que tu distribuidor puede conceder a tu cuenta.

Ramifica siempre por error.code, nunca por el 403 a secas.

6. El 404 que no es culpa tuya

Las operaciones de escritura y de gasto viven detrás de interruptores de despliegue. Apagados, responden 404 — exactamente igual que si la ruta no existiera. Es deliberado: un endpoint apagado no debe revelar que existe.

Consecuencia práctica: si una operación de escritura te da 404 con un identificador que sabes bueno, no lo depures como bug tuyo. Pregunta si la superficie está encendida en tu entorno. Cada operación del catálogo dice a qué puerta pertenece.

7. Operaciones de gasto: la cuarta puerta, y la idempotencia

Las 12 operaciones que mueven dinero o generan tráfico real (llamar, despachar una campaña, recargar saldo, contratar, comprar troncales) tienen dos condiciones más que el resto:

El alta de la cuenta. Encender el interruptor global dice «este entorno puede»; no dice «este cliente quiso». Sin el alta explícita, la respuesta es 403 money_opt_in_required. No lo arregla ni una clave nueva ni un plan superior: es un consentimiento por cuenta.

La cabecera Idempotency-Key, obligatoria. Sin ella, 400 missing_idempotency_key.

KEY=$(uuidgen)
curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"to":"+34600111222","agent_id":"<uuid>"}' \
  "https://$AMAI_API_HOST/api/v1/calls/dial"

La regla que te ahorra un cobro doble: guarda la clave y repítela en cualquier reintento.

Si cambias la clave en un reintento, la operación se ejecuta dos veces. Ese es todo el riesgo, y es todo evitable.

8. Paginación

Hay dos familias de paginación, y conviene saber en cuál estás antes de escribir el bucle.

8.1 · limit/offset — el resto de la API

Las listas paginan con limit y offset, con los mismos límites:

• limit — por defecto 50, máximo 500. Fuera de rango: 400 invalid_field.
• offset — por defecto 0, entero ≥ 0.

La respuesta trae un bloque pagination:

{ "pagination": { "limit": 50, "offset": 0, "total": 412, "has_more": true } }

Recorre mientras has_more sea true, sumando limit al offset. No te fíes de que una página venga corta para parar: usa has_more.

OFFSET=0
while :; do
  PAGE=$(curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
    "https://$AMAI_API_HOST/api/v1/calls?limit=500&offset=$OFFSET")
  echo "$PAGE" | jq -c '.data[]'
  [ "$(echo "$PAGE" | jq -r '.pagination.has_more')" = "true" ] || break
  OFFSET=$((OFFSET + 500))
done

Un detalle que ahorra un malentendido: donde hay un bloque summary, es del rango filtrado completo, no de la página. Aunque pidas limit=1, los totales siguen siendo los del periodo.

8.2 · Cursor — la sección Conversations

/api/v1/conversations, sus mensajes y /api/v1/whatsapp/connections no tienen offset, y no es un descuido: una bandeja se reordena mientras la lees, así que paginar por posición se salta hilos y repite otros, en silencio y con un 200 delante.

• limit — por defecto 50, máximo 200 (aquí no es 500).
• cursor — se copia tal cual de page.next_cursor. Es opaco: no lo interpretes, y no lo reutilices entre listas distintas (te responde 400).
• No hay total: contar un conjunto que se mueve da un número ya falso cuando lo lees.

{ "page": { "limit": 50, "has_more": true, "next_cursor": "eyJ2IjoxLC..." } }

CURSOR=""
while :; do
  PAGE=$(curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
    "https://$AMAI_API_HOST/api/v1/whatsapp/connections?limit=50${CURSOR:+&cursor=$CURSOR}")
  echo "$PAGE" | jq -c '.data[]'
  [ "$(echo "$PAGE" | jq -r '.page.has_more')" = "true" ] || break
  CURSOR=$(echo "$PAGE" | jq -r '.page.next_cursor')
done

La condición de parada es page.has_more, en las tres listas, y se calcula leyendo una fila de más — no se deduce del tamaño de la página.

9. Filtros y fechas

• Las fechas son ISO-8601: 2026-07-01 o 2026-07-01T00:00:00Z. Nada relativo, nada local.
• Los rangos son inclusivos por los dos extremos: end_date=2026-07-31 incluye el 31 entero.
• Los enumerados se validan de forma estricta. Un valor no reconocido es 400, nunca un filtro ignorado en silencio: un filtro que se ignora devuelve datos de más y nadie se entera.
• Un identificador que no tenga forma de UUID es 400 invalid_id_format antes de tocar la base de datos.

10. Límites de peticiones

El presupuesto que cuenta va por clave, no por IP: rotar de dirección no te da cuota nueva, y el tráfico de un cliente nunca gasta el presupuesto de otro.

Al pasarte recibes 429 con las cabeceras Retry-After y X-RateLimit-Reset, ambas en segundos. Respétalas: reintentar antes solo consume el presupuesto siguiente.

11. Los dos sobres de error

Esta API responde los errores con dos formas distintas, y hay que saberlo antes de escribir el manejador:

{ "error": { "code": "invalid_field", "message": "..." } }

Es el sobre tipado, el de toda la superficie nueva.

{ "error": "member_not_found" }

Es el sobre legado — error como cadena —, y lo devuelven las 9 operaciones más antiguas, que ya tienen clientes en producción cuyo parseo no controlamos:

• GET /api/v1/calendar
• GET /api/v1/calendar/check
• PUT /api/v1/calls/{call_id}/member
• DELETE /api/v1/calls/{call_id}/member
• POST /api/v1/contacts/identify
• POST /api/v1/email/send
• GET /api/v1/members
• GET /api/v1/team/mention-list
• GET /api/v1/whatsapp/messages

Una línea cubre las dos, para siempre:

const code = typeof body.error === "string" ? body.error : body.error?.code

Y normaliza a minúsculas antes de comparar: en el sobre legado conviven unauthorized, Unauthorized y UNAUTHORIZED para el mismo fallo.

12. Tabla completa de errores

Todos los códigos que la API puede devolver, con qué hacer ante cada uno. Se extrae del código fuente, no de la memoria de nadie: hay un test que se pone rojo si una ruta empieza a devolver un código que no esté en esta tabla.

13. Ejemplos por dominio

Un curl copiable por cada uno de los 29 dominios. Exportadas AMAI_API_KEY y AMAI_API_HOST (sección 2), todos funcionan tal cual.

Agentes

Listar los agentes de voz del tenant, ver uno y editar su contenido (saludo, prompt, voz). Crear y borrar agentes NO está abierto por API: se hace desde el panel. 4 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/agents?limit=10"

Analítica

Los mismos agregados que pinta el panel: el resumen del dashboard y las estadísticas de llamadas por periodo. 2 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/analytics/dashboard?start_date=2026-07-01&end_date=2026-07-31"

Anuncios

Los comunicados internos de la cuenta: los mismos que ve el equipo en el panel. Solo lectura por API — publicarlos y retirarlos se hace desde el panel. 2 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/announcements?limit=20"

Auditoría

El registro de actividad del tenant: quién hizo qué y cuándo. 1 operación.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/audit-log?limit=50"

Avisos

Configurar, silenciar o descartar los avisos del sistema. 1 operación.

curl -sS -X PATCH \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"<uuid>","dismissed":true}' \
  "https://$AMAI_API_HOST/api/v1/alerts"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Base de conocimiento

Gestionar las colecciones de documentos que consultan los agentes. La LECTURA de esas bases vive en el dominio «Knowledge Base» — son dos etiquetas para la misma cosa, y está anotado como defecto conocido en la ficha de la guía. 1 operación.

curl -sS -X PATCH \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Manual de producto 2026"}' \
  "https://$AMAI_API_HOST/api/v1/kb/collections/<collection_id>"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Calendario

El horario laboral del tenant y sus excepciones. GET /api/v1/calendar/check responde si un instante concreto cae dentro del horario — es lo que consulta un agente antes de prometer una devolución de llamada. 4 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/calendar/check?at=2026-07-28T10:30:00Z"

Campañas

Crear y editar campañas y asociarles listas de contactos. Lanzarlas no está aquí: el despacho gasta saldo y vive en el dominio «Gasto». 8 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Recordatorio julio","agent_id":"<uuid>"}' \
  "https://$AMAI_API_HOST/api/v1/campaigns"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Canal

Solo para cuentas de tipo agencia o partner: el árbol de subcuentas y sus estadísticas agregadas. 2 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/agency/stats"

Una cuenta cliente recibe 403 capability_required aquí, y es correcto: no tiene canal.

Claves de API

Rotar tu propia credencial por programa: se emite una nueva con el mismo nombre y los mismos permisos, y la anterior queda revocada en el acto — sin periodo de gracia, porque se rota cuando una clave se ha filtrado. key_id tiene que ser el id de la clave con la que llamas (el que ves en el panel, no el secreto); cualquier otro responde 404, incluidas las demás claves de tu cuenta. El valor nuevo viaja una sola vez, en esa respuesta. Listar, crear y revocar otras claves sigue siendo del panel. 1 operación.

curl -sS -X POST -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/api-keys/$AMAI_API_KEY_ID/rotate"

Contactos

El directorio del tenant. POST /api/v1/contacts/identify es el que usa un agente en mitad de una llamada para saber con quién habla. 8 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+34600111222"}' \
  "https://$AMAI_API_HOST/api/v1/contacts/identify"

Conversations

La bandeja unificada de WhatsApp: hilos, mensajes, cesión humana y los números conectados, sin entrar nunca en Meta ni manejar un token suyo. Las tres listas —hilos, mensajes y números conectados— se paginan por cursor y no por offset, porque una bandeja se reordena mientras se lee y paginar por posición se salta hilos en silencio; la condición de parada es page.has_more, que se calcula leyendo una fila de más. Toda la sección exige el interruptor CONVERSATIONS_API_ENABLED: apagado responde 404. Y POST .../messages registra la intención de enviar, no envía: quien llama al proveedor es la pasarela. 9 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/conversations?status=open&limit=25"

Documentos

El archivo documental de la cuenta: listar y filtrar por tipo, etiqueta, texto y rango de fechas. Las fechas son inclusivas por los dos extremos. 1 operación.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/documents?date_from=2026-07-01&date_to=2026-07-31&limit=25"

Exige que la cuenta tenga el archivo CONECTADO, no solo el plan que lo incluye. Si el plan lo incluye y la integración no está configurada, responde 503 integration_not_configured — y eso no lo arregla ni la clave ni un cambio de plan, sino tu distribuidor.

Email

Las identidades de envío de correo dadas de alta en la cuenta: desde qué direcciones puede enviar, y cuáles están verificadas. Útil para elegir remitente ANTES de llamar al envío. 1 operación.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/email/connections"

Solo lectura, y a propósito: no devuelve ninguna credencial de la conexión (ni contraseña, ni token de OAuth). Dar de alta o revocar una identidad se hace desde el panel.

Equipo

La administración del equipo: invitaciones pendientes, plazas contratadas y ocupadas, y los roles personalizados del tenant. Se puede revocar una invitación. 4 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/team/seats"

Las tres lecturas comparten el scope members:read. La revocación (DELETE /api/v1/team/invites/{invite_id}) es otra autorización — invites:revoke — y además exige PUBLIC_API_WRITE_ENABLED.

Espacio de trabajo

Lo que el panel enseña en su bandeja: recados, avisos y el listado de campañas. Es la vista de lectura del día a día. 3 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/recados?limit=20"

Facturación

Consulta de saldo, suscripción, consumo, movimientos y facturas. Todo de LECTURA: contratar y recargar viven en «Gasto». 8 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/billing/balance"

Gasto

Todo lo que mueve dinero o genera tráfico real: lanzar una llamada, despachar una campaña, recargar saldo, contratar plan o add-on, crear troncales SIP y gestionar subcuentas. Es la superficie con más condiciones de toda la API — cuatro, y hacen falta las cuatro. 13 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"+34600111222","agent_id":"<uuid>"}' \
  "https://$AMAI_API_HOST/api/v1/calls/dial"

Guarda el UUID que generes: si la petición da timeout, reintenta con el mismo o pagarás dos llamadas. Ver la sección de idempotencia de la guía de inicio.

Inbox

La bandeja de correo de la cuenta, de fuera adentro: buzones, carpetas de un buzón, mensajes de una carpeta, un mensaje, sus adjuntos y el hilo al que pertenece. Todo lectura. 7 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/inbox/mailboxes"

La descarga de un adjunto corta en 15 MiB con 413 attachment_too_large; por encima de ese tamaño la ficha del adjunto sigue estando en el listado, pero el binario no se sirve por esta vía.

Knowledge Base

Listar las bases de conocimiento y buscar dentro de una. Es la LECTURA; la gestión de colecciones está bajo «Base de conocimiento». 2 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"horario de atención"}' \
  "https://$AMAI_API_HOST/api/v1/knowledge-bases/<kb_id>/search"

Listas

Listas de contactos: crearlas, renombrarlas y meter o sacar miembros. 7 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clientes activos"}' \
  "https://$AMAI_API_HOST/api/v1/contact-lists"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Llamadas

El historial con desglose de coste y los agregados del periodo completo — el sustituto por API del CSV del panel — más las anotaciones sobre una llamada (miembro asignado, etiquetas). 8 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/calls?start_date=2026-07-01&end_date=2026-07-31&limit=50"

Guía completa, con paginación de un mes entero: /docs/calls.

Marca blanca

Dar de alta clientes con tu marca, sin ratón. El alta ya existía (POST /api/v1/agency/subaccounts, que cuelga la cuenta nueva de la tuya); esto es la otra mitad: leer y escribir cómo se ve el panel de esa cuenta —nombre, logo, colores, dominio propio— y las tres verjas que deciden si admite altas (allow_signup) y qué puede contratar (hide_plans, hide_addons). El identificador tiene que colgar de ti; cualquier otro responde 404 sin decirte si existe. 6 operaciones.

curl -sS -X PATCH -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Mi Marca","primary_color":"#00a86b","custom_domain":"panel.miempresa.com"}' \
  "https://$AMAI_API_HOST/api/v1/subaccounts/$AMAI_SUBACCOUNT_ID/branding"

custom_domain_verified no se puede escribir. Se gana publicando el registro TXT que devuelve la lectura (_amai-verify.<dominio> → amai-verify=<account_id>) y llamando a POST …/branding/verify-domain, que lo comprueba contra el DNS. Y cambiar el dominio revoca la verificación en la misma escritura: si no, apuntar el dominio a otro sitio heredaría un sello que no se ha ganado.

Plantillas

Plantillas de email reutilizables en campañas y secuencias. 4 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bienvenida","subject":"Hola {{first_name}}","body":"<p>Gracias por confiar en nosotros.</p>"}' \
  "https://$AMAI_API_HOST/api/v1/email-templates"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Secuencias

Secuencias de seguimiento automatizadas: crearlas y editarlas. 5 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Seguimiento a 3 días"}' \
  "https://$AMAI_API_HOST/api/v1/sequences"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Telefonía

Los números del tenant y las tarifas de venta propias de la cuenta, con el catálogo de países disponibles. 6 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/numbers"

/api/v1/rates devuelve tus tarifas de venta, las de tu cuenta. No expone el coste de proveedor de AMAI ni ningún multiplicador.

Utilidades

Las piezas sueltas que un flujo de agente necesita: calendario, envío de email e histórico de email y de SMS. 7 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"cliente@ejemplo.com","subject":"Tu cita","body":"Confirmada para el martes."}' \
  "https://$AMAI_API_HOST/api/v1/email/send"

Operación de escritura: 404 mientras PUBLIC_API_WRITE_ENABLED esté apagado.

Webhooks

Tu suscripción a los eventos de la plataforma —un destino por cuenta— y el registro de cada intento de entrega. El ejemplo es la consulta, que es lo primero que se necesita: hasta ahora se entregaba a ciegas y el único sitio donde se veía si algo había llegado era la pantalla del panel. 5 operaciones.

curl -sS -H "Authorization: Bearer $AMAI_API_KEY" \
  "https://$AMAI_API_HOST/api/v1/webhooks/deliveries?success=false&limit=20"

El secreto de firma no viaja en ninguna lectura: GET /api/v1/webhooks solo dice si lo hay. Se enseña una única vez, en el POST que lo emite. Si lo pierdes, rotate_secret emite otro — y las firmas anteriores dejan de validar.

WhatsApp

Enviar texto y plantillas, leer el histórico y consultar las plantillas aprobadas. El token de Meta lo custodia y rota AMAI: nunca lo manejas tú. 4 operaciones.

curl -sS -X POST \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+34600111222","type":"text","text":"Hola desde la API de AMAI"}' \
  "https://$AMAI_API_HOST/api/v1/whatsapp/send"

Guía completa, con la ventana de 24 h y los webhooks: /docs/whatsapp.

14. Scopes: el catálogo completo

Un scope es recurso:acción. Una concesión recurso:* cubre todas las acciones de ese recurso; la concesión * cubre todo y solo se da a claves de primera parte.

La columna «Planes que la traen» es la capacidad de serie del plan. Un administrador puede conceder cualquier capacidad a una cuenta concreta, así que «Ninguno de serie» significa «hay que pedirlo», no «imposible».

15. Qué alcanza cada plan

Una capacidad concedida por el plan ✅ abre todas las operaciones que la exigen. La última columna cuenta cuántas son.

16. Lo que el código no concede

Esta sección existe porque una integración que se construye contra una promesa comercial y choca con el código pierde semanas.

43 de las 134 operaciones no las alcanza de serie ningún plan comercial — tampoco Enterprise. Existen, están documentadas y funcionan; simplemente su capacidad no viene en ningún nivel de plan y hay que pedirla expresamente para la cuenta:

Si tu integración depende de alguna, habla con tu distribuidor antes de escribir una línea. Es un permiso que se concede por cuenta y se resuelve en minutos, pero no se resuelve solo, y ninguna clave nueva lo arregla.

17. Dónde seguir

• Referencia interactiva — todos los esquemas y una consola para probar.
• Catálogo de operaciones — las 134, con su scope, su plan y su puerta.
• Historial de llamadas — la guía larga del dominio más usado.
• WhatsApp — enviar, recibir, plantillas y webhooks firmados.
• El documento OpenAPI en crudo: /api/openapi.json.

¿Dudas o necesitas más límite? Escríbenos a info@amai.solutions.