API de Alttos

La API pública te deja hacer desde tus propios sistemas lo que ya haces desde el panel: avisarle a un cliente por WhatsApp cuando algo pasa en tu software, y consultar los datos que necesitas para hacerlo.

El flujo es siempre en la misma dirección: tú empujas contra nuestra API. Alttos no se conecta a tus sistemas ni los consulta; tu software decide cuándo hay algo que avisar y hace la llamada.

Para qué sirve

El caso que motiva esta API son las alertas transaccionales: tu sistema de citas confirma un turno, tu ERP despacha un pedido, tu plataforma académica abre una matrícula. En todos esos casos el dato vive en tu software y el cliente final está en WhatsApp.

Un envío por API no es un mensaje suelto: abre una conversación real en tu bandeja de Alttos. Si el cliente responde, la respuesta cae en ese mismo hilo y la atiende quien atienda ese canal (tu agente de IA si está encendido, o tu equipo si el canal está en modo manual). No tienes que hacer nada extra para que eso funcione.

Qué incluye la versión 1

Y lo que todavía no hace, para que no lo busques: no hay webhooks salientes (el estado de entrega se consulta con GET /v1/messages/{id}), no hay carga de catálogo, no hay campañas masivas por API (los grupos se listan para que recorras sus integrantes y les envíes uno por uno, ver Grupos; el envío masivo con tablero de progreso se lanza desde Marketing en el panel), las plantillas se listan pero no se crean ni se editan por API (eso se hace desde el panel), no hay operaciones para crear ni editar contactos (un envío sí crea el contacto si no existía, pero no puedes modificarlo desde la API), y el único canal con envío es WhatsApp. Instagram y el webchat aparecen en GET /v1/channels con capabilities.send vacío.

URL base

https://api.alttos.ai/api/public/v1

Todas las rutas de esta documentación cuelgan de ahí. Por ejemplo, el envío de mensajes es https://api.alttos.ai/api/public/v1/messages.

Tu primera llamada

Crea una clave en Configuración → API del panel (necesitas ser administrador) con el permiso channels:read, y pídele a la API tus canales:

curl https://api.alttos.ai/api/public/v1/channels \
  -H "Authorization: Bearer $ALTTOS_API_KEY"

{
  "data": [
    {
      "id": "1b1a6d68-6e78-4717-aa04-5ace8614e907",
      "kind": "whatsapp",
      "name": "Avisos",
      "status": "active",
      "phone_number": "+57 300 000 0000",
      "capabilities": { "send": ["template", "text_in_window"] }
    }
  ],
  "next_cursor": null
}

El id de ese canal es el channel_id que vas a usar para enviar. capabilities.send te dice qué admite: template para plantillas aprobadas y text_in_window para texto libre dentro de la ventana de 24 horas. Un canal con status: "inactive" y send: [] es un canal que hay que reconectar desde el panel antes de poder usarlo.

Esta lista se pagina igual que la de contactos: mientras next_cursor no sea null, hay más canales. Ver paginación.

Genera tu cliente desde el esquema

Publicamos el contrato completo en formato OpenAPI 3.1:

https://api.alttos.ai/api/public/v1/openapi.json

Es el mismo contrato que describe esta documentación, pero en un archivo que las herramientas entienden. No hace falta leerlo: sirve para que no escribas el cliente a mano.

Un SDK tipado, en un comando

npx @openapitools/openapi-generator-cli generate \
  -i https://api.alttos.ai/api/public/v1/openapi.json \
  -g typescript-fetch \
  -o ./alttos-client

Cambia -g por el lenguaje que uses: python, java, csharp, go, php, ruby. Los métodos del cliente salen con los nombres de las operaciones — sendMessage, listChannels, getMessage, listContacts, getContact — y los tipos de request y respuesta vienen generados, así que un campo mal escrito lo atrapa tu compilador en vez de nuestro 422.

O impórtalo en tu cliente HTTP

Postman, Insomnia, Bruno y similares importan ese mismo archivo y te dejan las cinco operaciones listas para probar, con sus parámetros y ejemplos. En Postman: Import → Link y pegas la URL.

Cómo seguir

• Autenticación: cómo se crean las claves, qué son los permisos y cómo rotarlas sin cortar el servicio.
• Envío de mensajes: el recorrido completo con ejemplos, la ventana de 24 horas y la idempotencia.
• Errores y límites: la lista completa de códigos de error con qué hacer ante cada uno, los límites de uso y la paginación.

Compatibilidad

Dentro de /v1 solo hacemos cambios aditivos: podemos agregar campos nuevos a una respuesta o parámetros opcionales nuevos a una request, nunca quitar ni cambiar el significado de lo que ya existe.

De ahí salen las dos reglas que tu integración debe cumplir, y que apuntan en direcciones opuestas a propósito:

1. Al leer, sé tolerante: ignora los campos que no conozcas. Si tu parser falla ante una clave nueva, un cambio compatible se te va a ver como una caída. Lo mismo con los valores: kind, status y capabilities.send pueden crecer, así que trata como no soportado el valor que no reconozcas en vez de reventar.
2. Al escribir, sé exacto: nosotros no ignoramos nada. Un campo que el contrato no declara, o un parámetro de query inventado, responden 422 validation_error con el nombre del campo. Es deliberado: un "nmae" ignorado en silencio envía el mensaje sin el dato que creías estar mandando, y eso lo descubre tu cliente final, no tú.

Un cambio que sí rompa contrato saldría bajo un prefijo nuevo (/v2), nunca dentro de /v1.