Ir al contenido
AI-SNS.IO — CHAT SUPPORTAI-SNS.IO — CHAT SUPPORT
Usar AI SNS CHAT

Amplía AI SNS CHAT con la API REST: guía práctica

Redacción de AI SNS CHATPublicado 6 min de lectura

Cuándo usar la API REST de AI SNS CHAT, qué piezas necesitas, cómo respetar los límites y proteger tus webhooks antes de salir a producción.

Tu agente ya responde bien en WhatsApp, pero necesitas que consulte tu ERP, que avise a tu CRM propio o que se muestre dentro de tu aplicación móvil. Para eso existe la API REST. En este artículo te explicamos cuándo conviene usarla, qué piezas la componen, qué límites debes respetar y cómo llevar tu integración a producción con seguridad.

Cuándo la API es la herramienta adecuada (y cuándo no)

Antes de abrir el editor de código, conviene preguntarse si de verdad hace falta. Muchas necesidades que parecen "de desarrollo" ya tienen una vía integrada, y esa vía suele ser más barata de mantener.

La API tiene sentido cuando:

  • Quieres mostrar las respuestas del agente en tu propia interfaz: una app de pedidos, un portal de clientes o un panel interno.
  • Necesitas reaccionar a eventos en tu sistema, por ejemplo registrar cada conversación en un CRM a medida.
  • Tu canal no está en la lista de canales ya disponibles y quieres conectarlo tú.
  • Buscas automatizar tareas repetitivas alrededor del agente desde tus propios procesos.

No la necesitas cuando:

  • Solo quieres poner el agente en WhatsApp, Instagram, Messenger o en el chat web de tu tienda. Eso se hace desde el panel, sin código.
  • Quieres consultar herramientas habituales (hojas de cálculo, CRM conocidos, plataformas de tickets). Hay integraciones ya preparadas.
  • Tu equipo no tiene a nadie que pueda mantener el código a largo plazo.
Vía integrada
API REST propia
Activar WhatsApp, Instagram o chat web desde el panel
Mostrar el agente dentro de tu app o portal
Conectar un CRM o una herramienta del catálogo
Sincronizar con un sistema interno a medida
Sin código ni servidor propio
Requiere desarrollo, servidor y mantenimiento
Cambios en minutos desde el dashboard
Cambios con despliegues y pruebas
¿Vía integrada o API propia?Ejemplo ilustrativo

Las piezas básicas

La API de AI SNS CHAT es REST con JSON, y se apoya en tres elementos que conviene entender bien.

Claves de API

Se crean en los ajustes del espacio de trabajo. La clave se muestra una sola vez, así que guárdala en un gestor de secretos en el momento. Se puede revocar cuando quieras, y si sospechas de una fuga, revócala y genera otra.

Respuestas en streaming

Si quieres que el texto aparezca poco a poco, como en un chat moderno, la API admite SSE (server-sent events) con el parámetro stream=1. Es útil en interfaces propias, donde esperar la respuesta completa se siente lento.

Webhooks firmados

Tu sistema puede recibir avisos de AI SNS CHAT mediante webhooks firmados con HMAC, y hay un registro de entregas para revisar qué se envió y qué respondió tu servidor. La firma sirve para comprobar que el aviso viene realmente de la plataforma y no de un tercero.

La referencia completa de endpoints está en la documentación de la API; aquí nos centramos en cómo diseñar bien la integración.

  1. 01Tu app o sistema
  2. 02API REST con clave
  3. 03Agente de AI SNS CHAT
  4. 04Webhook firmado a tu servidor
Cómo encaja una integración propiaEjemplo ilustrativo

Respeta los límites de uso publicados

La documentación de la API publica límites por defecto que debes tener en cuenta al diseñar:

  • Autenticación: 20 solicitudes cada 5 minutos por IP.
  • Chat público: 30 por minuto por IP.
  • Consulta periódica (poll): 120 por minuto.

Tres consecuencias prácticas:

  1. No hagas polling agresivo. Si esperas un evento, usa webhooks en lugar de preguntar cada segundo.
  2. Cuidado con la IP compartida. Si todas las peticiones salen de un único servidor, los límites por IP se consumen juntos. Piensa en esto si tienes mucho tráfico.
  3. Reintenta con calma. Ante un rechazo por exceso de peticiones, espera y vuelve a intentar con retroceso progresivo, no con un bucle inmediato.

Un ejemplo hipotético: si tu aplicación consulta el estado cada segundo para 10 usuarios a la vez, genera unas 600 consultas por minuto, muy por encima del límite de poll. Con webhooks, el problema desaparece.

Patrones de diseño que funcionan

Webhook primero, polling como último recurso

Recibe los eventos en un endpoint tuyo, responde rápido con un 200 y procesa el trabajo pesado en segundo plano. Así evitas tiempos de espera y reenvíos innecesarios.

Idempotencia

Los webhooks pueden llegar más de una vez. Guarda un identificador de cada evento procesado y descarta los duplicados. Si no, podrías crear dos pedidos o dos contactos por el mismo mensaje.

Streaming en la interfaz, no en el servidor intermedio

Si muestras las respuestas en tu app, deja que el navegador o la aplicación móvil consuma el flujo SSE lo más directamente posible, siempre sin exponer la clave de API en el cliente. La clave debe vivir en tu backend.

Un puente fino hacia tus sistemas

Piensa en un caso habitual en España o Latinoamérica: una tienda con pedidos en su propio sistema de gestión. Tu backend recibe el aviso, consulta el estado del pedido y lo devuelve al flujo. Mantén esa capa pequeña y con una sola responsabilidad; será más fácil de depurar.

Separa entornos

Usa un espacio de trabajo y un agente de pruebas distintos de los reales, con claves diferentes. Un error en desarrollo no debería tocar conversaciones de clientes.

Lista de seguridad antes de salir a producción

  • Claves solo en el servidor. Nunca en código de la app, en repositorios ni en el navegador.
  • Verifica la firma HMAC de cada webhook antes de procesarlo, comparando con tu secreto en tiempo constante.
  • Rota las claves de forma periódica y revoca las que ya no uses.
  • Usa HTTPS en todos tus endpoints.
  • Registra sin exponer datos. No guardes claves ni datos personales innecesarios en tus logs.
  • Mínimo privilegio. Crea claves separadas por integración para poder revocar una sin afectar a las demás.
  • Revisa el registro de actividad del espacio de trabajo para saber quién creó o modificó qué.
  • Piensa en la privacidad de tus clientes. Las prácticas de AI SNS CHAT están diseñadas con referencia al RGPD y a la APPI japonesa, pero tu integración también debe cumplir la normativa que te aplique.

Pruebas y despliegue

  1. Prueba en el Playground el comportamiento del agente antes de conectar nada: así separas los fallos de la conversación de los fallos de la integración.
  2. Simula webhooks contra un entorno de pruebas, incluyendo duplicados, firmas inválidas y respuestas lentas.
  3. Revisa el registro de entregas para confirmar qué se envió y cómo respondió tu servidor.
  4. Despliega por fases: primero con un grupo reducido de usuarios o un solo canal.
  5. Vigila los primeros días: errores de tu servidor, rechazos por límites y conversaciones valoradas negativamente en los registros de chat.
  6. Ten un plan de vuelta atrás: puedes revocar la clave o desactivar tu endpoint, y el agente seguirá funcionando en sus canales normales.

Cómo hacerlo en AI SNS CHAT

Este es el recorrido práctico dentro de la plataforma.

  1. Comprueba tu plan. Las claves de API están disponibles desde el plan Hobby. Con el plan Free no podrás crearlas. Consulta los detalles en /pricing.
  2. Crea la clave. Entra en los ajustes del espacio de trabajo, sección de claves de API, y genera una nueva. Cópiala en ese momento: no se vuelve a mostrar. Puedes revocarla cuando quieras.
  3. Prepara el agente. Configura persona, fuentes de conocimiento y modelo en el dashboard, y pruébalo en el Playground. Así llegas a la integración con un agente que ya responde bien.
  4. Consulta la referencia. La documentación de la API describe los endpoints, el streaming con stream=1 y los webhooks firmados con HMAC.
  5. Configura los webhooks apuntando a tu servidor, verifica la firma y revisa el registro de entregas mientras pruebas.
  6. Revisa las conversaciones. Las de canales distintos del correo aparecen en Actividad, Registros de chat, donde puedes filtrar, valorar y exportar. Si corriges una respuesta y la conviertes en la respuesta ideal, el agente aprende de ella.

Si tu objetivo es solo llevar el agente a WhatsApp, Instagram, Messenger o al chat web, no necesitas la API: se conectan desde la barra lateral, en Canales. Puedes ver todas las conexiones en /connections y el resto de funciones en /features.

Para integraciones sin código propio, mira antes las acciones integradas y las herramientas de consulta: incluyen opciones como HubSpot, Google Sheets, Airtable o WooCommerce, y las acciones por agente dependen del plan.

Conclusión

La API REST es la puerta para llevar AI SNS CHAT a tu propia aplicación o a sistemas a medida, pero no siempre es el primer paso. Usa las vías integradas para lo estándar, reserva la API para lo diferenciador, respeta los límites publicados, verifica cada firma y despliega por fases. Así tendrás una integración sólida y fácil de mantener.

Preguntas frecuentes

¿Qué plan necesito para usar la API REST?

Las claves de API están disponibles desde el plan Hobby. En el plan Free no se pueden crear. Los precios pueden cambiar, así que confirma los vigentes en /pricing.

¿Puedo mostrar las respuestas en streaming en mi propia interfaz?

Sí. La API admite streaming mediante SSE con el parámetro stream=1, de modo que el texto aparece de forma progresiva. Haz la llamada desde tu backend o mediante un puente seguro para no exponer la clave en el cliente.

¿Cómo sé que un webhook viene realmente de AI SNS CHAT?

Los webhooks van firmados con HMAC. Calcula la firma con tu secreto, compárala con la recibida y descarta la petición si no coincide. Además, el registro de entregas te permite revisar lo enviado.

¿Cuáles son los límites de uso?

Los publicados son: autenticación, 20 solicitudes cada 5 minutos por IP; chat público, 30 por minuto por IP; y poll, 120 por minuto. Diseña con webhooks y reintentos con espera para no toparte con ellos.

¿Necesito la API para poner un agente en WhatsApp o Messenger?

No. Esos canales se conectan desde el panel, en Canales, sin escribir código. La API es para casos a medida, como interfaces propias o integraciones con sistemas internos.

#API REST#integraciones#webhooks#automatización#desarrollo

Ponlo en práctica con AI SNS CHAT

Crea un agente de IA entrenado con tu propio contenido y conéctalo a tu web, WhatsApp, Messenger y más. Gratis para empezar, sin tarjeta de crédito.