API y webhooks (conectar tu propio sistema)
Claves de API para que tu propio sistema lea o cree contactos y prospectos, consulte métricas o chatee con tu agente, y webhooks que avisan a tu servidor cuando pasa algo.
Para qué sirve
Si tienes un sistema propio (tu página, tu punto de venta, una herramienta como n8n), tu programador lo puede conectar con tu agente. Por ejemplo: que cada prospecto que capta tu agente de WhatsApp aparezca solo en tu sistema, o que tu página web mande mensajes a tu agente.
Dónde está
Menú izquierdo → sección 🤖 ASC — Tu Servicio al Cliente → Integraciones (icono de webhook). El título de la pantalla es API & Webhooks. Tiene las pestañas Claves de acceso, Automatizaciones, Uso y Docs.
No la confundas con Integraciones de la sección AAE (Mercado Pago y sistemas conectados).
Cómo se usa
- Crear una clave: en Claves de acceso pulsa + Nueva clave, ponle un nombre (ej. "Mi App") y marca los Permisos: Leer contactos, Escribir contactos, Leer leads, Escribir leads, Leer analíticas, Chat con agente, Gestionar webhooks. Pulsa Crear.
- Copia y guarda la clave en ese momento: no se vuelve a mostrar.
- Crear un webhook: en la pestaña Automatizaciones pulsa + Nueva automatización, escribe la URL de tu servidor y marca los Eventos: Nuevo lead, Lead actualizado, Nueva conversación, Solicitud de escalado, Bot desconectado, Workflow ejecutado, Contacto creado. Pulsa Crear y guarda el Secret que aparece.
- Pásale a tu programador la pestaña Docs: dirección base
https://agentesvirtuales.mx/v1y la clave en el encabezadoAuthorization: Bearer AVAPI_...(también aceptax-api-key). - En cada clave puedes Revocar o Eliminar; en cada webhook, Eliminar. En Uso ves las peticiones totales, las claves activas, el tiempo promedio de respuesta y los endpoints más usados de los últimos 30 días.
Alcances
- Funciones disponibles por API: listar y crear contactos, listar y crear leads, consultar métricas y enviar un mensaje a tu agente para recibir su respuesta.
- Las claves empiezan con
AVAPI_y cada una tiene sus propios permisos. - Límite de peticiones: 10 por minuto y 500 al día; en Premium, AAE Pro (con o sin Cowork) y Combo, 30 por minuto y 2,000 al día.
- Los webhooks llevan una firma (HMAC-SHA256) en el encabezado
X-Webhook-Signature, hecha con tu Secret, para que tu servidor compruebe que el aviso es real. - Cada mensaje por API es una conversación nueva: el agente no recuerda los mensajes anteriores de esa clave.
- Incluido en ASC Profesional, ASC Premium, AAE Pro, AAE Pro + Cowork y Combo.
Limitaciones
- No está en Emprendedor ni en AAE Lite.
- Requiere a alguien que sepa programar; no hay conexiones "de un clic" en esta pantalla.
- Solo las funciones de la lista: esta API no tiene funciones para cotizaciones, productos, citas ni para mandar WhatsApp a un número.
- La pestaña Automatizaciones de esta pantalla son webhooks; no es la sección Automatizaciones del menú AAE.
Problemas comunes
- "La pantalla dice 'Tu sesión expiró' o 'No autorizado'." Tu sesión del portal se cerró; vuelve a iniciar sesión y entra otra vez a Integraciones.
- "Cerré el aviso y no copié la clave (o el Secret)." No se vuelve a mostrar. Elimina esa clave (o ese webhook) y crea uno nuevo.
- "Mi sistema recibe 'API Key inválida o inactiva'." La clave fue revocada o está mal copiada; crea una nueva.
- "Mi sistema recibe 'Scope requerido'." A esa clave le falta el permiso de esa función; crea una con el permiso marcado.
- "Mi sistema recibe 'Rate limit excedido'." Superó las peticiones por minuto de tu plan (10, o 30 en Premium, AAE Pro y Combo); espera los segundos que indica y reintenta.
¿Te quedó alguna duda? Escríbenos y te guiamos paso a paso con tu caso, al instante.
PreguntarnosProbar gratis
Agentes Virtuales