Paso 1
Cómo trabaja el conector
Dieciséis herramientas de solo lectura, siempre sobre una consulta tuya.
Un conector de solo lectura
El conector MCP de Social Alert publica tus consultas de monitoreo como herramientas que un asistente de IA (Claude, ChatGPT, Cursor, etc.) puede llamar. Todas son de lectura: consultan métricas y publicaciones, y ninguna crea, edita ni borra nada en tu cuenta.
En Claude basta con buscar Social Alert en Configuración → Conectores → Descubrir y pulsar Agregar: inicias sesión con tu cuenta y listo. Para ChatGPT, Cursor u otros clientes, o para agregarlo a mano por URL, sigue la guía Conecta Social Alert a ChatGPT y Claude.
El flujo que sigue el asistente
No necesitas llamar herramientas tú: el asistente las elige según lo que pides. Pero ayuda saber el orden en que trabaja, porque explica por qué la primera respuesta tarda un poco más.
| Orden | Herramienta | Para qué |
|---|---|---|
| 1 | list_organizations | Solo si perteneces a varias organizaciones |
| 2 | list_queries | Encontrar la consulta por su nombre |
| 3 | analyze_query | Resolver el contexto de la consulta: periodo, zona horaria, filtros por defecto |
| 4 | Herramientas de datos | Métricas, rankings, audiencia y publicaciones |
Los pasos 1 a 3 ocurren una vez por conversación. A partir de ahí, cada pregunta tuya se traduce en una o varias herramientas de datos con los filtros que indiques.
Las 16 herramientas, en cinco grupos
| Grupo | Herramientas |
|---|---|
| Descubrimiento | list_organizations, list_queries, analyze_query |
| Métricas | get_kpis, get_timeline, get_social_networks, get_publication_types |
| Conversación | get_top_words, get_top_hashtags, get_top_emojis, get_top_verbs |
| Audiencia | get_influencers, get_top_countries, get_age_gender, get_bot_stats |
| Publicaciones | get_posts |
Nota
Los nombres técnicos aparecen aquí para que reconozcas qué herramienta usó el asistente cuando te lo muestre. En la conversación pides en lenguaje natural.
Dónde hacerlo: Ver mis consultas
Preguntas frecuentes
¿Necesito un plan específico?
El conector está incluido en los planes de pago. Con la prueba gratuita la conexión se completa, pero el asistente no recibe herramientas. Puedes revisarlo en Ajustes de la organización → Planes.
¿Qué datos ve el asistente?
Solo las consultas de las organizaciones a las que perteneces, con los mismos límites de tu plan. Cada llamada va autorizada con tu sesión; el servidor rechaza cualquier consulta que no sea tuya.
Paso 2
Descubrimiento: elegir la consulta
Tres herramientas para llegar a la consulta correcta sin buscar identificadores.
list_organizations
Lista las organizaciones a las que perteneces, con su nombre y cuántas consultas tiene cada una. El asistente la usa solo si tienes más de una organización o si lo mencionas.
¿En qué organizaciones estoy y cuántas consultas tiene cada una?
list_queries
Lista tus consultas de monitoreo por nombre, para que nunca tengas que buscar un ID. Acepta un texto de búsqueda (coincidencia parcial, sin distinguir mayúsculas) y, opcionalmente, una organización para acotar.
En Claude, esta herramienta muestra un selector interactivo: haces clic en la consulta y el asistente continúa con ella. En otros clientes, lee la lista y la resuelve por nombre.
Lista mis consultas que tengan "elecciones" en el nombre.
Usa la consulta Marca Acme para todo lo que te pida después.
analyze_query
Resuelve el contexto de la consulta elegida y devuelve lo que las demás herramientas necesitan: la partición de datos, el periodo disponible, la zona horaria y los filtros por defecto del dashboard (incluir republicaciones, rango de autores, cuentas excluidas). Así los números que ves en el chat coinciden con los de tu pantalla.
Acepta un rango relativo (24h, 7d, 30d, 3m, 1y) o deja que las herramientas de datos reciban fechas exactas después. Si no dices nada, el periodo por defecto es las últimas 24 horas.
Analiza la consulta Marca Acme con los últimos 30 días.
| Parámetro | Qué es |
|---|---|
queryId | El ID de la consulta (el segmento tras /dashboard/ en la URL del dashboard). El asistente lo obtiene de list_queries |
dateRange | Rango relativo: {N}h, {N}d, {N}m, {N}y |
timeZone | Tu zona horaria IANA (p. ej. America/Bogota). Es la tuya, no la del país que analizas |
Tip
Si cambias de consulta a mitad de la conversación, dilo de forma explícita: "ahora usa la consulta X". El asistente vuelve a ejecutar analyze_query y a partir de ahí todo sale de la nueva.
Preguntas frecuentes
El asistente dice que el ID de la consulta no es válido
Pídele que liste tus consultas y elija por nombre. Los IDs tienen dos formatos válidos (21 caracteres o 24 hexadecimales) y nunca deben adivinarse; el servidor rechaza cualquier ID que no exista o que no pertenezca a tus organizaciones.
Paso 3
Métricas: cuánto y cuándo
Totales, evolución en el tiempo y reparto por red y por tipo de contenido.
get_kpis · Indicadores
Publicaciones, usuarios únicos, audiencia alcanzada e interacciones (me gusta, comentarios, compartidos) del periodo, con la variación porcentual frente al periodo anterior equivalente.
Dame los indicadores de los últimos 7 días y compáralos con los 7 anteriores. ¿Qué cambió más?
get_timeline · Evolución
Serie por día con publicaciones, audiencia e interacciones. Sirve para picos, tendencias y días más activos.
Muéstrame la evolución diaria del último mes y marca el día con más volumen.
¿Hubo algún pico en interacciones esta semana? ¿Qué día y de qué tamaño?
get_social_networks · Reparto por red
Publicaciones o interacciones por red social (X, Facebook, Instagram, TikTok, YouTube, medios web, prensa, radio y TV, etc.). Se agrupa por volumen (por defecto) o por interacciones.
¿Cómo se repartió la conversación por red? Ordénala por interacciones.
get_publication_types · Tipos de contenido
Conteo por tipo: publicaciones, comentarios, tuits, reels y menciones.
¿Qué proporción de lo captado son comentarios frente a publicaciones originales?
Tip
Las cuatro herramientas aceptan los mismos filtros comunes: fechas, redes, sentimiento, tipo de publicación, género, edad, clasificación de bots, país e idioma. "Indicadores solo de Instagram y TikTok, del 1 al 15, sin republicaciones" es una sola llamada.
Paso 4
Conversación: de qué se habla
Rankings de palabras, hashtags, emojis y verbos.
Las cuatro herramientas devuelven una lista ordenada por frecuencia con el conteo de cada elemento. Responden a la pregunta "qué dice la gente", cada una desde un ángulo.
| Herramienta | Qué devuelve | Para qué sirve |
|---|---|---|
get_top_words | Palabras más frecuentes | Temas principales, vocabulario de la conversación |
get_top_hashtags | Hashtags más usados | Etiquetas en tendencia, campañas |
get_top_emojis | Emojis más usados | Tono emocional expresado con emojis |
get_top_verbs | Verbos más frecuentes | Acciones que se discuten, tono del discurso |
¿Cuáles son las 20 palabras y los 10 hashtags más usados? Agrúpalos por tema y descarta las palabras vacías.
¿Qué emojis aparecen más en las publicaciones negativas y qué dicen del tono?
Compara los verbos más frecuentes de esta semana con los de la anterior. ¿Cambió lo que la gente pide o reclama?
Nota
Los rankings son de texto: una palabra que aparece mucho no es necesariamente positiva ni negativa. Para leerlos con sentido, combínalos con el filtro de sentimiento o con una búsqueda de texto ("solo en publicaciones que mencionen 'precio'").
Paso 5
Audiencia: quién habla y desde dónde
Influencers, países, demografía y autenticidad de las cuentas.
get_influencers · Perfiles con más impacto
Autores ordenados por impacto, con nombre, usuario, red, enlace al perfil y métricas: publicaciones, seguidores, interacciones y audiencia por publicación.
Dame los 10 perfiles más influyentes con su audiencia y número de publicaciones. Señala cuáles son medios y cuáles cuentas personales.
get_top_countries · Países
Países ordenados por volumen de publicaciones (códigos ISO).
¿Desde qué países se habla más? ¿Hay alguno inesperado?
get_age_gender · Edad y género
Conteo de autores por rango de edad cruzado con género. Hay exactamente cuatro rangos (menores de 18, 19 a 29, 30 a 39, más de 40) más "desconocido"; el género es masculino, femenino o desconocido. Ambos se infieren del perfil del autor, nunca son autodeclarados.
¿Cómo es la audiencia por edad y género? ¿Qué segmento domina la conversación negativa?
get_bot_stats · Autenticidad
Conteo de autores por clasificación: humano, posible bot y bot confirmado.
¿Qué porcentaje de cuentas se clasifica como bot o posible bot? Si es alto, dime en qué días se concentra.
Importante
Edad, género y clasificación de bots son estimaciones basadas en señales del perfil y del comportamiento. Úsalas para describir tendencias de la audiencia, no para afirmar algo de una persona concreta.
Paso 6
Publicaciones: el contenido en sí
La única herramienta que devuelve publicaciones completas, paginadas y ordenables.
get_posts
Devuelve publicaciones individuales con texto completo, autor, métricas de interacción, enlaces y multimedia. Es la herramienta para leer menciones concretas, buscar un texto, ver las publicaciones con más alcance o revisar lo que dijo una cuenta.
| Parámetro | Qué hace |
|---|---|
page / pageSize | Paginación. Por defecto 20 publicaciones por página, máximo 200 |
sortBy | Orden: published-at (más recientes, por defecto), interactions, audience, likes, shares, comments, views, followers, rank, network, sentiment |
sortDirection | desc (por defecto) o asc |
authorRank | Ventana de relevancia del autor, de 0 a 10 |
postIds | Recuperar publicaciones concretas por ID |
city | Filtro por ciudad, además de los filtros comunes |
Cada publicación indica cómo tratar su multimedia (mediaPreviewType): video reproducible, miniatura de un video, imagen, o embed de TikTok. Si no trae ese campo, la publicación no tiene multimedia.
Tráeme las 20 publicaciones más recientes con sentimiento negativo y resume los tres reclamos que más se repiten.
¿Cuáles fueron las 5 publicaciones con más interacciones del mes? Dame el texto, el autor y el enlace.
Busca publicaciones que mencionen "factura" o "cobro" y que no digan "resuelto". Ordénalas por audiencia.
Tip
Pide resúmenes, no volcados. "Resume las 50 publicaciones más recientes" es una llamada barata y una respuesta útil; "tráeme las 2.000 publicaciones del mes" satura la conversación y no mejora el análisis.
Preguntas frecuentes
¿Puedo pedir las publicaciones de una sola cuenta?
Sí. Pide primero los influencers o unas publicaciones donde aparezca la cuenta; el asistente obtiene su identificador de autor y lo usa como filtro: "ahora tráeme solo las publicaciones de @cuenta".
¿Los enlaces a las publicaciones funcionan?
Cada publicación trae el enlace a la publicación original y al perfil del autor cuando la red los expone. Las imágenes de algunas redes caducan a los pocos días; el enlace a la publicación es la referencia estable.
Paso 7
Filtros comunes
Los mismos filtros del dashboard, disponibles en todas las herramientas de datos.
Todas las herramientas de datos aceptan estos filtros. Omitir uno significa sin filtro: entran todos los valores de esa dimensión.
| Filtro | Valores | Ejemplo en lenguaje natural |
|---|---|---|
Fechas (dateFrom, dateTo) | Fecha y hora exactas, en tu zona horaria | "del 1 al 15 de este mes" |
Redes (networks) | x, facebook, instagram, tiktok, youtube, twitch, telegram, reddit, web (noticias web), rss, newspaper (portadas de prensa), atl (radio y TV) | "solo Instagram y TikTok" |
Sentimiento (sentiment) | negative, neutral, positive | "solo lo negativo" |
Tipo de publicación (publicationTypes) | publicación, comentario, tuit, reel, mención | "sin comentarios, solo publicaciones" |
Republicaciones (includeReposts) | Incluidas por defecto; false = solo contenido original | "excluye las republicaciones" |
Género (gender) | male, female, unknown | "autoras mujeres" |
Edad (ageRange) | menores de 18, 19 a 29, 30 a 39, más de 40 | "entre 19 y 29 años" |
Bots (botClass) | human, potential, bot | "solo cuentas humanas" |
País (countries) | Códigos ISO de tres letras (COL, MEX, ECU…) | "desde Colombia y México" |
Idioma (language) | Código ISO de dos letras (es, en, pt) | "solo en inglés" |
Autor (author) | Una cuenta concreta | "solo lo que publicó @cuenta" |
Cuentas excluidas (excludedAccounts) | Las que excluiste en el dashboard, aplicadas automáticamente | — |
Zona horaria (timeZone) | IANA, la tuya | "en hora de Lima" |
Búsqueda de texto
El filtro textSearch acepta una sintaxis booleana sencilla que el asistente construye por ti:
| Escribes | El asistente envía |
|---|---|
| que mencionen "bitcoin" | "bitcoin" |
| "bitcoin" o "BTC", pero no "estafa" | ("bitcoin" OR "BTC") AND -"scam" |
| la frase exacta "cambio de gobierno" | ="cambio de gobierno" |
Límites: hasta 5 grupos unidos por AND y hasta 5 términos por grupo OR.
Huella y Sombra
En los planes con acceso confidencial, siete herramientas (get_kpis, get_timeline, get_posts y los cuatro rankings de conversación) aceptan además el filtro contentScope:
- Huella (
FOOTPRINT, por defecto): las publicaciones y comentarios que mencionan los términos de la consulta. Responde "qué dicen de mí". - Sombra (
SHADOW): las respuestas alrededor de esas publicaciones, que no mencionan los términos. Responde "qué contestó la gente".
La Sombra tiene límites propios: ventana máxima de 30 días por pedido (más de 7 es lento), solo existe en Facebook, Instagram y TikTok, en Facebook el autor que aparece es la página, no quien comenta (así que no sirve para rankear personas), y no trae variaciones ni audiencia.
Sin ir al detalle, ¿qué contestó la gente a las publicaciones de la última semana? Usa la Sombra.
Nota
Si tu plan no incluye la Sombra, el filtro simplemente no existe para tu asistente y todo se responde con la Huella.
Paso 8
Casos de uso por equipo
Pedidos listos para copiar, con las herramientas que activan por detrás.
Comunicación y prensa
Con la consulta Marca Acme, prepara el informe semanal: indicadores con variación, evolución diaria, reparto por red, los 5 temas principales y las 3 publicaciones con más alcance. Formato: contexto, hallazgos con cifra, riesgos y próximos pasos.
Herramientas: get_kpis, get_timeline, get_social_networks, get_top_words, get_posts.
¿Hay un pico de conversación negativa hoy? Si lo hay, dime desde qué hora, en qué red, qué cuentas lo impulsan y tráeme las 10 publicaciones más compartidas.
Herramientas: get_timeline, get_social_networks, get_influencers, get_posts con sentimiento negativo.
Marketing y campañas
Durante la campaña (del 1 al 15), ¿qué hashtags ganaron tracción, en qué redes y qué perfiles los movieron? Compáralo con la quincena anterior.
Herramientas: get_top_hashtags, get_social_networks, get_influencers, dos periodos.
Dame los 10 perfiles más influyentes de Instagram y TikTok, con su audiencia por publicación, para evaluar colaboraciones. Excluye medios.
Herramientas: get_influencers con redes filtradas.
Investigación y opinión pública
Describe la audiencia de la conversación: edad, género, países y proporción de cuentas automatizadas. Señala si la conversación negativa tiene un perfil distinto a la positiva.
Herramientas: get_age_gender, get_top_countries, get_bot_stats, cada una con y sin filtro de sentimiento.
¿Qué verbos dominan el discurso sobre el tema y cómo cambiaron en el último mes? Interpreta si la conversación pasó de informar a exigir.
Herramientas: get_top_verbs en dos periodos.
Atención y servicio
De las publicaciones negativas de la última semana, quédate con las de cuentas humanas y resume los reclamos en una tabla: reclamo, frecuencia, ejemplo textual, red.
Herramientas: get_posts con sentimiento negativo y clasificación humana.
Prepara tres respuestas tipo para los reclamos más repetidos, en tono institucional, sin prometer plazos.
Herramientas: ninguna nueva; el asistente redacta sobre los datos ya obtenidos.
Tip
Cuando una respuesta te sirva, pídele el pedido equivalente para reutilizarlo: "resume en una sola instrucción lo que acabas de hacer, para repetirlo cada lunes".
Dónde hacerlo: Ver mis consultas
Paso 9
Buenas prácticas y límites
Cinco hábitos que evitan malentendidos y lo que el conector no hace.
Hábitos que mejoran las respuestas
- Una consulta a la vez. Para comparar dos consultas, pide primero una, luego la otra y después la comparación. Pedirlo todo junto mezcla cifras.
- Di el periodo. Si no lo indicas, el conector usa las últimas 24 horas. "Dime de qué fechas son estos números" es la forma más rápida de detectar que mirabas otra ventana.
- Sé explícito con los filtros. Sin indicaciones, aplica los valores por defecto de la consulta (incluye republicaciones, excluye las cuentas que excluiste en el dashboard).
- Pide resúmenes, no volcados. Las herramientas devuelven lo que pides; 50 publicaciones resumidas valen más que 2.000 sin leer.
- Contrasta lo que vayas a publicar. El asistente lee bien las cifras, pero puede equivocarse al interpretarlas o al redactar, como cualquier chat.
Lo que el conector no hace
- No escribe. No crea consultas, alertas ni informes, ni cambia filtros o configuración. Para eso está la plataforma.
- No inventa datos. Si una consulta no tiene actividad en el periodo, devuelve ceros; si un ID no existe o no es tuyo, devuelve un error claro.
- No guarda tus conversaciones. El servidor registra solo lo técnico de cada llamada (quién, qué herramienta, qué consulta y periodo). Lo que hablas con el asistente queda en el asistente.
Errores frecuentes y qué significan
| Lo que ves | Qué pasa | Qué hacer |
|---|---|---|
| "El conector no tiene herramientas" | Tu plan no incluye el conector, o no está activado en esa conversación | Revisa el plan de la organización; activa el conector en el menú + del chat |
| "ID de consulta inválido" o "sin acceso" | El ID no existe o la consulta es de otra organización | Pide que liste tus consultas y elija por nombre |
| "La Sombra no está disponible" | Tu plan no incluye el acceso confidencial | Repite el pedido sin Sombra: la Huella sigue disponible |
| Cifras que no cuadran con el dashboard | Periodo o filtros distintos | Pide que confirme periodo y filtros y compáralos con tu pantalla |
Revocar el acceso
Puedes desconectar el asistente cuando quieras desde su configuración de conectores (en Claude, Configuración → Conectores → Social Alert → Eliminar). La autorización se revoca en ese momento y el asistente deja de poder llamar a las herramientas.
Dónde hacerlo: Revisar mi plan
Preguntas frecuentes
¿Los números coinciden con los del dashboard?
Sí: el conector lee los mismos datos y aplica por defecto los mismos filtros de la consulta. Si algo no cuadra, casi siempre es el rango de fechas o un filtro distinto.
¿Consume créditos de mi plan?
No gasta créditos de informes ni de imágenes. Lo que aplica es el plan: el conector está disponible desde los planes de pago.