Guía de configuración de SosoAPI

Elige tu punto de partida

SosoAPI da al agente que ya usas una conexión con tus cuentas sociales. Tu agente ayuda a redactar y revisar contenido; SosoAPI gestiona las operaciones de cuenta compatibles, la programación y los resultados de publicación. Puedes revisar las mismas publicaciones en la app o usar la API desde tu propio código.

Esta guía empieza con una persona y una cuenta social. Conectarás un cliente MCP local o alojado, elegirás acceso, comprobarás una cuenta social, prepararás y aprobarás una publicación y leerás su resultado real. El recorrido avanzado cubre la CLI y la API HTTP. La configuración en sí no exige una publicación de prueba.

• Deja que Claude Code o Codex configure todo: paso 1
• Configura tú mismo un cliente MCP: paso 3
• Usa un terminal o backend: paso 9
• Repara una conexión: paso 10

Antes de empezar

Necesitas un cliente de IA compatible con MCP, una cuenta SosoAPI y una cuenta social que puedas gestionar. Puedes crear la cuenta SosoAPI cuando se abra el inicio de sesión. Ten en mente un contenido real.

MCP local requiere Node.js 20 o posterior con npm/npx y tu cliente de IA elegido. MCP alojado requiere un cliente compatible con MCP remoto, OAuth y registro automático de clientes; no necesita una instalación local de Node.js. Las funciones del cliente pueden depender del plan y los ajustes del administrador.

SosoAPI conecta Instagram, Threads, Facebook Pages, YouTube y X. Elige una cuenta cuyo tipo, permisos y formato de publicación encajen con tu tarea. Una cuenta Threads apta es un buen primer ejemplo de solo texto. Instagram y YouTube necesitan medios adecuados para sus formatos compatibles. Que una plataforma aparezca en el menú de conexión no significa que todas las acciones estén disponibles para cada cuenta.

Comprueba las funciones específicas de la cuenta durante la configuración. Consulta tu plan y cuota actuales en la app antes de programar un lote; X tiene un cupo de créditos separado de la Organization. Un ejemplo para una plataforma no demuestra compatibilidad con otra.

• Plataformas compatibles
• Funciones de publicación y requisitos de las cuentas

1. Da a tu agente la solicitud de configuración

Pega esto en tu conversación existente con Claude Code o Codex.

El agente debe buscar primero una conexión SosoAPI que funcione y reutilizarla. Si no existe, sigue la receta de configuración e indica cuándo hace falta iniciar sesión en el navegador o reiniciar el cliente. Resultado esperado: las herramientas SosoAPI se pueden usar en esta conversación. Un mensaje de instalación no lo demuestra por sí solo. Continúa con inicio de sesión y comprobación de cuenta, o usa el paso 3 para configuración manual.

Configura SosoAPI desde https://sosoapi.ai/setup.md. Conserva mi contenido y tarea actuales. Iniciaré sesión y aprobaré el acceso cuando se me solicite. No publiques nada durante la configuración.

2. Inicia sesión y elige el acceso de tu agente

Usa tu cuenta prevista: continúa con Google o regístrate por correo y completa la verificación. Completa la configuración de cuenta o Workspace que aparezca. Si perteneces a varios Workspaces, elige la marca o proyecto previstos. Revisa los Workspaces y acciones solicitados antes de aprobar y vuelve a la misma conversación.

Conserva el enlace de inicio de sesión del agente para que el navegador vuelva a la autorización pendiente. Puedes empezar en la app y luego volver al agente. No sustituyas un enlace de aprobación pendiente por otro enlace de inicio de sesión.

Los roles del Workspace y permisos de plataforma siguen vigentes: un viewer no se convierte en editor porque el agente tenga acceso de publicación. Ese acceso continúa dentro del alcance concedido; SosoAPI no exige una nueva aprobación de navegador por cada publicación. Indica al agente cuándo detenerse para revisar contenido. La configuración OAuth normal no requiere pegar contraseñas sociales ni claves API en el agente.

Resultado esperado: el inicio de sesión termina con tu identidad prevista y el agente puede obtener los Workspaces autorizados. Consulta la solución de problemas si se abre el perfil de navegador incorrecto.

• Empieza en la app SosoAPI

3. Conecta tu agente manualmente, si hace falta

Elige un método de conexión. Omite esta sección si tu agente ya configuró una conexión que funciona. Para MCP local, comprueba primero Node.js y npx. Node.js debe ser la versión 20 o posterior.

node --version
npx --version

MCP local: Claude Code o Codex

Ejecuta solo el comando de tu cliente: el primero es para Claude Code y el segundo para Codex. El perfil core cubre la publicación cotidiana. Los perfiles cambian las herramientas visibles, pero no conceden permisos. Conserva una conexión que funcione con el perfil full si ya la tienes.

Reconecta o reinicia si el cliente lo pide y comprueba que las herramientas SosoAPI están disponibles en la conversación actual. La primera llamada autenticada inicia el acceso por navegador cuando hace falta.

claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

Otros clientes MCP locales

Para clientes con JSON mcpServers, añade esta entrada a la configuración existente y conserva los otros servidores. En otros formatos, introduce el mismo comando, argumentos y variable de entorno mediante los ajustes MCP propios del cliente.

{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}

• Referencia de instalación y opciones de paquetes

MCP alojado: clientes de navegador o remotos compatibles

En los ajustes de conector personalizado o MCP remoto del cliente, añade una conexión llamada SosoAPI con la URL de servidor siguiente. Elige OAuth con registro automático de clientes cuando se ofrezca. Inicia sesión en SosoAPI, elige Workspaces y acciones permitidos, vuelve a la conversación y activa la conexión si hace falta. Pide al agente que compruebe las cuentas autorizadas.

Usa https://sosoapi.ai para una nueva conexión alojada. El endpoint anterior https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp sigue siendo compatible. Conserva una conexión local o alojada que funcione; no hace falta sustituirla solo para cambiar su URL.

No hace falta pegar una clave API, ID de cliente ni secreto de cliente. Las apps MCP personalizadas de ChatGPT dependen del plan, modo desarrollador y ajustes de administrador del cliente. Estas instrucciones describen una conexión personalizada, no una entrada en el directorio de apps. MCP alojado no puede leer archivos locales; usa una importación de URL pública o MCP local para cargarlos.

https://sosoapi.ai

• Registro de cliente OAuth personalizado y procedimiento de token

Comprobación opcional de inicio de sesión en terminal

Para una conexión local, ejecuta primero auth status. Usa auth login solo si indica que no has iniciado sesión. Completa el flujo del navegador y vuelve a comprobar el estado. No se imprimen tokens. Esto comprueba la autenticación local de la CLI, no el inicio de sesión de un conector alojado aparte.

npx -y sosoapi auth status

npx -y sosoapi auth login

4. Conecta tu cuenta social

Abre Conecta cuentas o usa el comando local siguiente. Sustituye threads por instagram, facebook, youtube o x según corresponda. Esto abre el flujo de conexión; no publica contenido.

Comprueba la Organization y el Workspace mostrados. Elige la plataforma, inicia sesión en su página de autorización y selecciona la cuenta, Page o canal exactos. Completa el consentimiento y cualquier confirmación de selección al volver. Luego pide al agente que actualice las cuentas conectadas del Workspace previsto.

Reutiliza una conexión existente que funcione. Si pertenece a otra Organization o Workspace, resuelve esa elección en la app; la configuración habitual no debe desconectarla ni moverla. Resultado esperado: la cuenta correcta aparece en el Workspace previsto con información actual de estado y funciones. Un callback correcto por sí solo no demuestra permiso de publicación.

npx -y sosoapi connect threads

• Conecta cuentas

5. Verifica el acceso sin publicar

Pega lo siguiente en la conversación con el agente conectado.

El agente puede usar sosoapi_get_workspace_context y sosoapi_list_connected_accounts, reutilizar el contexto conocido y pasar explícitamente el workspace_id elegido. La inicialización puede crear tu primer Workspace; esta comprobación de configuración no crea ninguna publicación social.

Antes de seguir, confirma Workspace y destino, tu rol y acceso del agente, y la compatibilidad del destino con el formato propuesto. Usa la solución de problemas si falla alguna comprobación. Reinstalar un paquete no corrige un permiso de plataforma ausente.

Comprueba mi configuración de SosoAPI sin publicar ni programar nada.
Muestra los Workspaces que puedo usar y las cuentas sociales del Workspace que elija.
Para la cuenta que elija, muestra la plataforma, etiqueta de cuenta, estado de conexión y funciones de publicación para mi formato propuesto.
Si varios Workspaces o cuentas podrían coincidir, pregúntame cuál usar.
Conserva los ID internos para llamadas a herramientas; no me pidas que los busque o invente.

6. Prepara y aprueba tu primera publicación

Empieza con una publicación real y un destino. Sustituye los campos entre corchetes de esta solicitud de borrador. El agente redacta; SosoAPI aporta la conexión y las operaciones de publicación. Revisa tú mismo afirmaciones, ortografía, enlaces y medios.

Usa una fecha, hora local y zona IANA explícitas para una publicación futura. Si el horario de verano vuelve ambigua la hora local, elige la ocurrencia prevista antes del envío. Resultado esperado en esta fase: un borrador exacto para revisión, sin solicitud de publicación enviada.

Ayúdame a preparar un anuncio de producto con SosoAPI.

Producto: [nombre público del producto]
Datos verificados: [qué está disponible hoy]
Público: [a quién ayuda]
Destino: [etiqueta de cuenta y plataforma]
Idioma: [idioma]
Fecha y hora locales preferidas: [YYYY-MM-DD HH:mm]
Zona horaria: [zona IANA, por ejemplo Asia/Hong_Kong]
Medios: [ninguno, un archivo local o una URL pública de medios]

Usa solo los datos que proporcioné. Comprueba los requisitos de formato del destino.
Muestra el borrador exacto, los medios, el destino, la fecha, la hora y la zona horaria para revisión.
No programes ni publiques todavía.

Aprueba la publicación exacta antes de programarla

Cuando todos los datos sean correctos, da una instrucción concreta con la plantilla siguiente. Esto crea una programación real que puede publicar públicamente. Usa contenido y una cuenta en la que quieras publicar. La publicación inmediata también exige una instrucción explícita tras revisar los mismos datos.

Resultado esperado: un ID de Scheduled Post, destino previsto, horario aceptado y estado actual. Una programación aceptada no significa que el proveedor la haya publicado.

Programa la publicación exacta aprobada abajo en la cuenta indicada, con la fecha, hora y zona horaria establecidas.

[Pega el contenido final, los medios, el destino, la fecha, la hora y la zona horaria.]

Comprueba primero si existe una programación coincidente. Envía esta publicación una vez y lee el resultado guardado. Devuelve su ID, destino, horario aceptado y estado actual. Si el resultado es incierto, comprueba la solicitud existente antes de otra acción.

7. Comprueba el resultado, reprograma o cancela

Pide al agente que lea el mismo Scheduled Post mediante sosoapi_get_scheduled_post. También puedes abrir https://app.sosoapi.ai/scheduled-posts/<post-id> tras iniciar sesión con una cuenta autorizada. Comprueba cada destino por separado si la solicitud se dirige a varias cuentas; algunos pueden completarse y otros necesitar atención.

Lee el resultado actual de Scheduled Post [ID devuelto].
Muestra su destino, horario programado, estado actual y resultado de publicación.
Si se confirma la publicación, incluye el enlace público cuando esté disponible.
No reintentes, reprogrames ni crees otra publicación.

Gestiona una publicación pendiente y vuelve más tarde

Para cambiar una publicación pendiente, indica su ID y los nuevos datos. El agente debe leer su versión actual y las acciones disponibles antes de una actualización o cancelación compatible. La cancelación depende de la fase de entrega y puede dejar de estar disponible al iniciarse esta. Cancelar una programación no elimina una publicación ya publicada en el proveedor.

Tras recibir los datos guardados de una programación futura, puedes salir de la conversación y volver a la misma publicación después. Una conversación cerrada del agente no promete reactivarse ni avisarte salvo que se haya configurado aparte.

8. Añade imágenes o video y reutiliza el flujo

Haz funcionar el flujo de una publicación antes de preparar un lote mayor. Indica al agente si el medio es un archivo local, una URL pública o un recurso SosoAPI existente.

Archivos locales: MCP local puede usar sosoapi_upload_asset. El archivo debe estar en una carpeta de carga permitida; la herramienta indica las ubicaciones permitidas si la ruta queda fuera de ellas. MCP alojado no puede leer archivos de tu equipo.

URL públicas: usa sosoapi_import_asset_url y después sosoapi_get_asset_import_status con include_asset=true. Espera a que el recurso esté listo. Si ya existe, comprueba que pertenece al Workspace previsto y está listo para el formato elegido.

La solicitud normal de programación usa juntos el ID del recurso registrado y su URL canónica. Una URL temporal de vista previa o la URL externa original no los sustituye. En el flujo compatible de una URL de imagen, sosoapi_post_image_url combina importación y envío. Es una operación de publicación: aprueba primero la publicación completa. Conserva el ID aceptado durante el procesamiento; no inicies otra importación para continuar.

X admite un Post TEXT original sin medios, o VIDEO con exactamente un recurso de video MP4 registrado y listo, de al menos 0.5 segundos y dentro del límite de carga de 500 MiB. El video requiere can_publish_video verificado para esa cuenta exacta; el acceso a texto no basta. Una conexión antigua puede necesitar tu aprobación para reconectar con permiso de carga de video. Texto, hashtags y enlace deben caber en el límite ponderado de X. No se admiten fotos, respuestas, citas, republicaciones ni hilos. La aceptación de la carga o del procesamiento de video no significa que esté publicado.

Antes de un envío a X, lee sosoapi_get_x_usage para el workspace_id previsto y el texto final. Su cupo y costo son independientes de la cuota general del plan. No eludas un límite de créditos repitiendo envíos; concilia una publicación incierta antes de volver a enviar.

Prepara un lote revisado y evalúa el rendimiento con honestidad

Tras tu primera publicación exitosa, prueba la solicitud de lanzamiento de producto siguiente. Cuando apruebes la tabla exacta, comprueba el lote frente a los límites del plan. Informa por separado de los destinos aceptados y rechazados y conserva la identidad de cada publicación aceptada.

El acceso a publicación y a analítica puede diferir. Si luego pides una revisión del rendimiento, las métricas no disponibles deben indicarse como tales. No inventes ceros ni deduzcas que toda métrica se puede leer porque se publicó un post.

Con la misma configuración verificada, prepara siete borradores de anuncio de producto, uno por día, con los datos públicos que aporte. Muestra una tabla de revisión con borrador, destino, medios, fecha local, hora y zona horaria en cada fila. Conserva los siete como borradores hasta que apruebe la tabla exacta.

9. Recorrido por CLI y API

Usa esta vía opcional para archivos de solicitud explícitos o una integración de backend. Los usuarios de agentes pueden omitirla. Los ejemplos usan los mismos permisos de cuenta, Workspace y publicación que MCP.

Examina primero la ayuda y el contrato integrado del paquete instalado; consultar el contrato no requiere iniciar sesión. Muestra las operaciones y esquemas incluidos en ese paquete. Usa esos nombres de campo en vez del formato de otro proveedor.

npx -y sosoapi --help
npx -y sosoapi api contract --summary
npx -y sosoapi api contract --route /studio-api/scheduled-posts/

CLI: realiza tu primera solicitud de contexto autenticada

Completa auth login. Con un editor de texto, guarda workspaces.json con el JSON siguiente y ejecuta el comando. Usa archivos para los cuerpos de solicitud en lugar de interpolar contenido en comandos de shell.

La CLI devuelve schema_version, http_status y body. Una respuesta correcta incluye body.active_workspace_id y body.workspaces. Elige el Workspace previsto de esa respuesta; el Workspace activo no decide silenciosamente el destino de una tarea nueva. La primera llamada de una cuenta nueva puede inicializar su primer Workspace.

Comprueba http_status y body, no solo el código de salida del shell. Un comando puede devolver un sobre de error HTTP sin que la operación API haya tenido éxito.

{}

npx -y sosoapi api post /identity-api/workspace/list < workspaces.json

CLI: selecciona la cuenta social conectada

Guarda accounts.json con el ID de Workspace devuelto para tu cuenta y ejecuta el comando. Selecciona la cuenta prevista en body.accounts. Su ID de cuenta SosoAPI es el social_account_id usado al programar; un nombre de usuario o ID de Page del proveedor no lo sustituye.

{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}

npx -y sosoapi api post /identity-api/user/social-accounts/list < accounts.json

CLI: programa un texto de Threads aprobado

Es una plantilla de solicitud, no una publicación lista para ejecutar. Guarda post.json con un editor y sustituye cada valor entre corchetes por tus valores autorizados. Elige una fecha ISO futura con desplazamiento UTC explícito, o Z para UTC. display_timezone es una zona IANA para mostrar la hora; no completa una fecha local ambigua.

Genera un idempotency_key único, como un UUID, y guárdalo con el cuerpo exacto de la solicitud. Repite una solicitud idéntica con la misma clave; una respuesta tardía no justifica generar otra. Una publicación modificada es otra solicitud: comprueba el resultado original antes de elegir una nueva identidad.

Tras confirmar contenido, cuenta, horario, permisos y cuota actual, ejecuta el comando create. Esto programa una publicación real. Si se acepta, conserva body.post.id y lee body.post.status, body.post.scheduled_at y body.post.destination. body.deduped indica si se reutilizó una solicitud existente. La aceptación no es una publicación confirmada por el proveedor.

{
  "workspace_id": "<YOUR_WORKSPACE_ID>",
  "social_account_id": "<YOUR_THREADS_ACCOUNT_ID>",
  "caption": "<YOUR_APPROVED_POST_TEXT>",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<FUTURE_ISO_8601_TIME_WITH_OFFSET>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<NEW_STABLE_REQUEST_KEY>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/create < post.json

CLI: lee la publicación guardada y su resultado

Guarda post-status.json con el ID devuelto. Lee body.post, body.delivery, body.actions y body.outcomes. Confirma un resultado publicado antes de informar de éxito. Si se perdió la respuesta de create, recupera la solicitud original mediante su identidad guardada; no crees otra programación con una clave nueva.

{
  "id": "<RETURNED_POST_ID>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/get < post-status.json

CLI: cancela solo si el resultado actual lo permite

Si la última lectura permite cancelar y quieres hacerlo, guarda cancel.json con el ID devuelto y el valor numérico actual de body.post.version. El 1 del ejemplo es ilustrativo: sustitúyelo por la versión que acabas de leer. Luego ejecuta el comando y confirma el resultado.

Si cambió la versión o no se puede cancelar, vuelve a leer la misma publicación y usa las acciones realmente disponibles. No eludas un conflicto de versión ni confundas cancelar con eliminar una publicación ya publicada.

{
  "id": "<RETURNED_POST_ID>",
  "expected_version": 1
}

npx -y sosoapi api post /studio-api/scheduled-posts/cancel < cancel.json

HTTP: llama desde tu propio backend

Para una integración de servidor, crea una clave API en Connection → API y guarda el secreto en la configuración de secretos del servidor. La pantalla actual pide un nombre; no ofrece selectores de Workspace ni de funciones. Una clave creada por el usuario incluye por defecto operate, publish y engage en los Workspaces a los que puede acceder. Comprueba si esos permisos encajan con tu integración. El contrato API permite limitar explícitamente capabilities y workspace_ids para una clave acotada.

La configuración normal del agente usa OAuth y no necesita este paso de clave API. En el ejemplo, SOSOAPI_ACCESS_TOKEN es tu variable de ejemplo del servidor que contiene la clave; no es un ajuste de la CLI de SosoAPI. La variable opcional de token de acceso personal de la CLI es VICKY_API_KEY.

Usa el archivo workspaces.json anterior. HTTP directo devuelve el cuerpo del endpoint sin el sobre http_status/body de la CLI; lee el estado HTTP real y el JSON. Guarda las credenciales en el backend, fuera del código de navegador, prompts, capturas y archivos de solicitud compartidos.

Integrar la conexión social en un producto para tus propios clientes es una tarea de integración aparte. Este recorrido de una sola cuenta no demuestra que ese flujo de incorporación de clientes esté listo.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${SOSOAPI_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @workspaces.json \
  'https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/workspace/list'

• Gestiona claves API: Connection → API
• Referencia de API
• Creación de claves API y permisos explícitos
• Autenticación y permisos
• Referencia de CLI

10. Solución de problemas

Usa el error real y la conexión que estás diagnosticando. Ampliar permisos o repetir un envío no soluciona todos los fallos.

Actualiza, revoca el acceso o pide ayuda

El primer comando consulta la ayuda del paquete más reciente sin iniciar el servidor MCP. Si el cliente fija una versión en su comando guardado, actualiza ese comando expresamente. Actualizar una instalación global separada no actualiza la copia fijada del cliente.

Para revocar un dispositivo local, usa Connection → Agent o el comando auth logout siguiente. Para un conector alojado, revoca la autorización alojada correspondiente en Connection → Agent. Las claves API se gestionan por separado en Connection → API. Revocar el acceso del agente no cancela programaciones ya aceptadas; gestiona esas publicaciones aparte.

Para pedir ayuda, facilita la versión del cliente y paquete, paso fallido, error mostrado y hora/zona horaria. Comparte en privado con soporte los ID de solicitud o publicación pertinentes cuando haga falta. No envíes credenciales, enlaces de autorización ni registros sin procesar que puedan contener tokens.

npx -y sosoapi@latest --help

npx -y sosoapi auth logout

• Gestiona clientes de agentes: Connection → Agent
• Gestiona claves API: Connection → API
• Referencia de solución de problemas
• Contacta con soporte de SosoAPI

Lista de comprobación de la configuración

Puedes completar la conexión sin enviar una publicación. Si publicas, usa la comprobación de resultado por separado para confirmar ese primer flujo de publicación.

• Mi cliente puede usar herramientas SosoAPI o mi CLI/API puede realizar una solicitud autorizada.
• Inicié sesión con la cuenta prevista y elegí el Workspace correcto.
• Mi cuenta social aparece con las funciones necesarias para la tarea.
• Entiendo si mi agente puede preparar trabajo o también programar y publicar.
• Puedo preparar un borrador y revisar el destino, contenido y horario exactos.
• Si envié una publicación, conservé su ID y sé distinguir aceptación de publicación confirmada.
• Sé cómo revisar un fallo, gestionar una programación pendiente y revocar el acceso.