Beta. La API de Automatizaciones está en beta y estamos recopilando comentarios activamente. Los endpoints, las cargas útiles y los límites pueden cambiar a medida que iteramos. Envía comentarios e informes de errores a soporte para que podamos priorizar las mejoras correctas.
sent significa que Meta aceptó el mensaje, no que el destinatario lo haya recibido. La entrega está en última instancia dictada por la configuración de Message requests de Instagram del destinatario: si no permite solicitudes de mensajes de todos, Meta devuelve una respuesta de éxito y descarta silenciosamente el mensaje, y esto es invisible en cada capa de la API. Incluso un DM activado por un comentario y entregado correctamente llega como una solicitud de mensaje que el destinatario debe aceptar (a menos que ya exista una conversación entre las dos cuentas). Consulta DM de automatización enviado pero no entregado para la explicación completa.Cómo funciona
1
Crea una automatización
POST /automations con los disparadores y las acciones que deseas. La automatización se activa de inmediato.2
Un usuario final interactúa
Alguien comenta tu publicación, responde a tu historia, envía un DM o reacciona a un DM. Meta entrega el webhook a Ayrshare.
3
Ayrshare hace coincidir y despacha
El motor busca todas las reglas que coinciden con el evento, verifica la desduplicación por acción y tu límite diario de DM, luego ejecuta cada acción. Se aplica un jitter de 20 a 60 segundos a los envíos de DM para mantenerse dentro de las heurísticas anti-spam de Instagram.
4
Inspecciona qué se activó
GET /automations/:id/activity devuelve el registro de auditoría: cada intento de envío, los resultados por acción y cualquier error.Disparadores
Puedes adjuntar hasta 50 disparadores a una sola automatización. Cada disparador es una unión discriminada por el campotype; los campos específicos del tipo están al mismo nivel. Todos los disparadores son solo para Instagram en la v1.
La coincidencia de palabras clave no distingue entre mayúsculas y minúsculas y es por palabra completa. Un evento satisface un disparador con filtro de palabras clave si contiene alguna de las palabras clave configuradas. Omite
storyId en un disparador de historia para que se active en todas las historias de la cuenta conectada.
Acciones
Puedes adjuntar hasta 50 acciones a una sola automatización. Se ejecutan secuencialmente; cada resultado se registra en la fila de actividad.Ventana de desduplicación por acción
Cada acción, sin importar el tipo, acepta adicionalmente un campodedupWindowMinutes opcional de nivel superior que sobrescribe la ventana de desduplicación por destinatario predeterminada de 7 días solo para esa acción.
- Establécelo en
0para deshabilitar la desduplicación por completo para esa acción (típico parafire_webhook/send_emaildonde el receptor espera cada evento). - Limitado a
525600(un año).
Action with a 24h dedup override
Carga útil de fire_webhook
Cuando se ejecuta fire_webhook, realiza un POST de un cuerpo JSON a tu URL de webhook a nivel de cuenta:
recipientUsername y keyword son null cuando el disparador no los completa (por ejemplo, dm_keyword no incluye un nombre de usuario en la carga útil de Meta; story_reply no tiene una palabra clave).
Variables de plantilla
send_dm.message, send_email.subject y send_email.message admiten sustitución con {{placeholder}}. Los placeholders desconocidos se rechazan en el momento de creación/actualización (como un error de validación 473) para que un error tipográfico nunca deje pasar el literal {{foo}} a un mensaje visible para el cliente.
No hay
sender_email / recipient_email. Estos no se exponen deliberadamente: tu correo electrónico de facturación no tiene lugar legítimo en un DM a un desconocido, y Meta no proporciona el correo electrónico del destinatario en ningún webhook de IG. Evitar los placeholders previene divulgaciones accidentales.Límites de tasa y topes
El tope de automatizaciones activas se cuenta por perfil de usuario, no por cuenta principal. Cada perfil bajo tu cuenta obtiene su propio 10 de Business / 50 de Enterprise, por lo que una cuenta con muchos perfiles puede ejecutar esa cantidad de automatizaciones en cada uno. Cuenta las automatizaciones activas y se aplica tanto en
POST (crear) como en la reactivación con PUT (active: false → true), cada una arrojando el código de error 470. ¿Necesitas un límite por perfil más alto? Contacta a soporte para que se aumente en tu cuenta.
El tope diario de DM se aplica por cuenta principal de Ayrshare, se comparte entre todos tus perfiles y tiene un sub-tope por perfil para que un perfil muy activo no consuma toda la cuota de la cuenta. Cuando se alcanza un tope de DM, la fila de actividad registra el estado rate_limited y no se envía ningún DM.
Topes estructurales en una sola automatización: 1–50 disparadores, 1–50 acciones.
Instagram por sí mismo limita los DMs a aproximadamente 200/hora por cuenta. El motor regula el envío con un jitter de 20 a 60 segundos para mantenerse con seguridad por debajo de este.
Estados de actividad
Una fila enGET /automations/:id/activity lleva un status de nivel superior más un status por acción dentro de actionResults[]:
pending e in_flight son transitorios; todo lo demás es terminal.
sent es un acuse de recepción de aceptación por parte de la plataforma, no un acuse de entrega. Instagram no expone la entrega de mensajes a ninguna API. Una acción send_dm se marca como sent en el momento en que Instagram acepta el mensaje; que el destinatario lo reciba realmente depende de su configuración de Message requests de Instagram, que Ayrshare no puede leer ni modificar. Consulta DM de automatización enviado pero no entregado.Códigos de error
La API devuelve dos formas de error:- Errores de regla de negocio llevan un
codenumerado de automatización (por ejemplo,{ "action": "automation", "code": 469, ... }). - Errores de validación — cualquier cuerpo de solicitud mal formado (campos faltantes o inválidos, variables de plantilla desconocidas, claves no reconocidas) — se devuelven como una única respuesta
473con un objetodetailsque lista los campos ofensivos.detailses la salida del validador (formErrorsmásfieldErrors). Ramifica endetails, no en un código por condición. EnfieldErrors, las claves son los campos de nivel superior de la solicitud (triggers,actions): un problema dentro de una entrada específica, como un disparador al que le faltakeywords, se reporta bajo ese campo (por ejemplo,triggers), mientras queformErrorscontiene problemas de nivel de objeto, como claves no reconocidas.
Lo que Meta NO permite
Algunas capacidades comúnmente solicitadas no se admiten porque Meta no las permite en la API pública de Instagram:- Auto-DM en nuevos seguidores. Instagram no publica un webhook de seguimiento.
- Primeros DMs a desconocidos. Meta requiere que el destinatario haya interactuado primero (comentario, respuesta, DM, reacción) antes de que una cuenta comercial pueda enviarle un mensaje. Cada disparador admitido está anclado a esa interacción, pero ten en cuenta que estar autorizado a enviar no es lo mismo que el mensaje sea entregado: la configuración de Message requests de Instagram del destinatario aún puede provocar que Meta acepte y después descarte silenciosamente el mensaje (consulta DM de automatización enviado pero no entregado).
- Campañas masivas de salida. Los topes de DM por hora y las heurísticas anti-abuso se aplican a nivel de plataforma.
Uso multi-perfil
Los endpoints respetan el encabezadoprofileKey. Pasa la clave de un perfil secundario y la automatización se crea/gestiona bajo ese perfil. Los límites de tasa se dividen entre perfiles mediante un sub-tope por perfil, para que un perfil muy conversador no drene la cuota de la cuenta principal.
Preguntas frecuentes
¿Puedo activar en un nuevo seguidor?
¿Puedo activar en un nuevo seguidor?
No. Instagram no publica un webhook de seguimiento, y Meta no permite que las aplicaciones de terceros envíen un DM a un usuario que no ha interactuado primero. Cada disparador admitido (
comment_keyword, story_reply, dm_reaction, dm_keyword) está anclado a una interacción de ese tipo, que es lo que hace admisible el envío.¿Por qué una actividad dice `sent` pero el destinatario nunca recibió el DM?
¿Por qué una actividad dice `sent` pero el destinatario nunca recibió el DM?
sent significa que Instagram aceptó el mensaje, no que se haya entregado. La entrega depende de la configuración de Message requests de Instagram del destinatario — si no permite solicitudes de mensajes de todos, Meta devuelve una respuesta de éxito y descarta silenciosamente el mensaje, sin error, webhook ni ninguna otra señal en ninguna superficie de la API. Un DM activado por un comentario y entregado correctamente también llega como una solicitud de mensaje que el destinatario debe aceptar (a menos que ya exista una conversación). Esta es una limitación permanente de la plataforma Instagram. Consulta DM de automatización enviado pero no entregado.¿Qué sucede si mi token de acceso no es válido cuando se activa una automatización?
¿Qué sucede si mi token de acceso no es válido cuando se activa una automatización?
La fila de actividad registra el estado
auth_error y el DM no se reintenta. Vuelve a vincular la cuenta; a continuación, la siguiente interacción coincidente se activará normalmente.¿Por qué hay un retraso antes de que se envíe el DM?
¿Por qué hay un retraso antes de que se envíe el DM?
Cada envío de
send_dm se programa entre 20 y 60 segundos después de la interacción para parecer orgánico ante los sistemas anti-spam de Instagram. Las acciones fire_webhook y send_email NO tienen jitter. La marca de tiempo created de la fila de actividad es cuando coincidió el disparador; completedAt es cuando terminó el envío.¿Las filas de actividad se conservan para siempre?
¿Las filas de actividad se conservan para siempre?
Las filas de actividad se conservan de forma indefinida para trazabilidad y analíticas. El endpoint
GET /automations/:id/activity devuelve las filas de los últimos 30 días por rendimiento. (La protección de desduplicación usa su propia ventana por acción — con un valor predeterminado de 7 días — que no está relacionada con el retroactivo de actividad.)¿Eliminar una automatización elimina su historial de actividad?
¿Eliminar una automatización elimina su historial de actividad?
No. La eliminación es un borrado lógico: la fila maestra se marca como
deleted, no se producen nuevos envíos, pero las filas de actividad históricas siguen siendo legibles a través del endpoint de actividad.Endpoints
POST /automations— crea una nueva automatizaciónGET /automations— lista tus automatizacionesGET /automations/:id— obtén una automatización con sus disparadores y accionesPUT /automations/:id— actualización parcial; pausa conactive: falseDELETE /automations/:id— borrado lógicoGET /automations/:id/activity— registro de auditoría de envíos paginado por cursor