Guia de configuração do SosoAPI

Escolha seu ponto de partida

O SosoAPI oferece ao agente que você já usa uma conexão com suas contas sociais. Seu agente ajuda a escrever e revisar conteúdo; o SosoAPI cuida das operações de conta compatíveis, do agendamento e dos resultados de publicação. Você pode revisar os mesmos posts no app ou usar a API no seu próprio código.

Este guia começa com uma pessoa e uma conta social. Você conectará um cliente MCP local ou hospedado, escolherá o acesso, verificará uma conta social, preparará e aprovará um post e lerá o resultado real. O passo a passo avançado cobre a CLI e a API HTTP. A configuração em si não exige um post de teste.

• Deixe Claude Code ou Codex cuidar da configuração: etapa 1
• Configure um cliente MCP por conta própria: etapa 3
• Use um terminal ou backend: etapa 9
• Corrija uma conexão: etapa 10

Antes de começar

Você precisa de um cliente de IA compatível com MCP, uma conta SosoAPI e uma conta social que tenha autorização para gerenciar. É possível criar a conta SosoAPI quando o login abrir. Tenha um conteúdo real em mente.

MCP local exige Node.js 20 ou posterior com npm/npx e o cliente de IA escolhido. MCP hospedado exige um cliente compatível com MCP remoto, OAuth e registro automático de clientes; não precisa de instalação local do Node.js. Os recursos do cliente podem depender do plano e das configurações de administrador.

O SosoAPI conecta Instagram, Threads, Facebook Pages, YouTube e X. Escolha uma conta cujo tipo, permissões e formato de post correspondam à tarefa. Uma conta Threads elegível é um bom primeiro exemplo apenas com texto. Instagram e YouTube precisam de mídia adequada aos formatos de publicação compatíveis. Uma plataforma no menu de conexão não significa que toda ação esteja disponível para todas as contas.

Verifique os recursos específicos da conta durante a configuração. Leia seu plano e sua cota atuais no app antes de agendar um lote; o X tem uma cota separada de créditos da Organization. Um exemplo de uma plataforma não comprova compatibilidade em outra.

• Plataformas compatíveis
• Recursos de publicação e requisitos das contas

1. Envie a solicitação de configuração ao agente

Cole isto na sua conversa existente com Claude Code ou Codex.

O agente deve primeiro procurar uma conexão SosoAPI funcional e reutilizá-la. Caso contrário, segue a receita de configuração e avisa quando é necessário entrar pelo navegador ou reiniciar o cliente. Resultado esperado: ferramentas SosoAPI utilizáveis nesta conversa. Uma mensagem de instalação não comprova isso. Continue com login e verificação da conta ou use a etapa 3 para configuração manual.

Configure o SosoAPI a partir de https://sosoapi.ai/setup.md. Mantenha meu conteúdo e minha tarefa atuais. Farei login e aprovarei o acesso quando solicitado. Não publique nada durante a configuração.

2. Entre e escolha o acesso do seu agente

Use a conta pretendida: continue com Google ou registre-se por e-mail e conclua a verificação. Conclua qualquer configuração de conta ou Workspace exibida. Se você participa de vários Workspaces, escolha a marca ou o projeto pretendido. Revise os Workspaces e ações solicitados antes de aprovar e volte à mesma conversa.

Mantenha o link de login fornecido pelo agente para que o navegador volte à autorização pendente. Você pode começar no app e depois voltar ao agente. Não substitua um link de aprovação pendente por outro link de login.

Os papéis do Workspace e as permissões da plataforma continuam valendo: um viewer não vira editor porque um agente tem acesso de publicação. Esse acesso continua no escopo concedido; o SosoAPI não exige nova aprovação no navegador para cada post. Diga ao agente quando pausar para revisão de conteúdo. A configuração OAuth normal não exige colar senha social ou chave API no agente.

Resultado esperado: o login termina com sua identidade pretendida e o agente consegue buscar os Workspaces autorizados. Use a solução de problemas se abrir o perfil errado do navegador.

• Comece no app SosoAPI

3. Conecte seu agente manualmente, se necessário

Escolha um método de conexão. Pule esta seção se o agente já configurou uma conexão funcional. Para MCP local, verifique Node.js e npx primeiro. O Node.js deve ser versão 20 ou posterior.

node --version
npx --version

MCP local: Claude Code ou Codex

Execute apenas o comando do seu cliente: o primeiro é para Claude Code e o segundo para Codex. O perfil core cobre publicações do dia a dia. Perfis alteram as ferramentas exibidas, mas não concedem permissões. Mantenha uma conexão funcional com perfil full se já tiver uma.

Reconecte ou reinicie se o cliente solicitar e verifique se as ferramentas SosoAPI estão disponíveis na conversa atual. A primeira chamada autenticada inicia o login no navegador quando necessário.

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

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

Outros clientes MCP locais

Para clientes que usam JSON mcpServers, adicione esta entrada à configuração existente e preserve os outros servidores. Em outros formatos, forneça o mesmo comando, argumentos e variável de ambiente pelas configurações MCP do próprio cliente.

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

• Referência de instalação e opções de pacotes

MCP hospedado: clientes de navegador ou remotos compatíveis

Nas configurações de conector personalizado ou MCP remoto do cliente, adicione uma conexão chamada SosoAPI com a URL do servidor abaixo. Escolha OAuth com registro automático de clientes quando oferecido. Entre no SosoAPI, escolha Workspaces e ações permitidos, volte à conversa e ative a conexão se necessário. Peça ao agente para verificar as contas autorizadas.

Use https://sosoapi.ai para uma nova conexão hospedada. O endpoint anterior https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp continua compatível. Preserve uma conexão local ou hospedada funcional; não é preciso substituí-la apenas para mudar a URL.

Não é preciso colar chave API, ID de cliente ou segredo de cliente. Apps MCP personalizados do ChatGPT dependem do plano, modo de desenvolvedor e configurações de administrador do cliente. Estas instruções descrevem uma conexão personalizada, não uma listagem no diretório de apps. O MCP hospedado não lê arquivos locais; use importação de URL pública ou MCP local para uploads locais.

https://sosoapi.ai

• Registro de cliente OAuth personalizado e procedimento de token

Verificação opcional de login no terminal

Para uma conexão local, execute auth status primeiro. Execute auth login apenas se o status indicar que você não entrou. Conclua o fluxo do navegador e verifique o status novamente. Tokens não são exibidos. Isso verifica a autenticação local da CLI, não o login de um conector hospedado separado.

npx -y sosoapi auth status

npx -y sosoapi auth login

4. Conecte sua conta social

Abra Conecte contas ou use o comando local abaixo. Substitua threads por instagram, facebook, youtube ou x conforme necessário. Isso abre o fluxo de conexão; não publica conteúdo.

Verifique a Organization e o Workspace exibidos. Escolha a plataforma, entre pela página de autorização dela e selecione a conta, Page ou canal exatos. Conclua o consentimento e qualquer confirmação de seleção de conta ao retornar. Depois peça ao agente para atualizar as contas conectadas do Workspace pretendido.

Reutilize uma conexão existente saudável. Se ela pertencer a outra Organization ou Workspace, resolva essa escolha no app; a configuração comum não deve desconectá-la nem movê-la. Resultado esperado: a conta correta aparece no Workspace pretendido com informações atuais de saúde e recursos. Um callback bem-sucedido, por si só, não comprova permissão de publicação.

npx -y sosoapi connect threads

• Conecte contas

5. Verifique o acesso sem publicar

Cole o seguinte na conversa com o agente conectado.

O agente pode usar sosoapi_get_workspace_context e sosoapi_list_connected_accounts, reutilizar o contexto conhecido e passar explicitamente o workspace_id selecionado. A inicialização da conta pode criar seu primeiro Workspace; essa verificação de configuração não cria um post social.

Antes de prosseguir, confirme Workspace e destino, seu papel e acesso do agente, e a compatibilidade do destino com o formato proposto. Use a solução de problemas se uma verificação falhar. Reinstalar um pacote não corrige falta de permissão na plataforma.

Verifique minha configuração do SosoAPI sem publicar nem agendar nada.
Mostre os Workspaces que posso usar e as contas sociais no Workspace que eu selecionar.
Para a conta que eu escolher, mostre a plataforma, o rótulo da conta, a saúde da conexão e os recursos de publicação para o formato proposto.
Se vários Workspaces ou contas puderem corresponder, pergunte qual usar.
Mantenha IDs internos para chamadas de ferramentas; não peça que eu os encontre ou invente.

6. Prepare e aprove seu primeiro post

Comece com um post real e um destino. Substitua os campos entre colchetes nesta solicitação de rascunho. O agente escreve; o SosoAPI fornece a conexão e as operações de publicação. Revise você mesmo as afirmações, a ortografia, os links e a mídia.

Use uma data, hora local e fuso IANA explícitos para um post futuro. Se o horário de verão tornar a hora local ambígua, escolha a ocorrência pretendida antes do envio. Resultado esperado nesta etapa: um rascunho exato para revisão, sem solicitação de publicação enviada.

Ajude-me a preparar um anúncio de produto usando SosoAPI.

Produto: [nome público do produto]
Fatos verificados: [o que está disponível hoje]
Público: [quem isso ajuda]
Destino: [rótulo da conta e plataforma]
Idioma: [idioma]
Data e horário locais preferidos: [YYYY-MM-DD HH:mm]
Fuso horário: [fuso IANA, por exemplo Asia/Hong_Kong]
Mídia: [nenhuma, um arquivo local ou uma URL pública de mídia]

Use apenas os fatos que forneci. Verifique os requisitos de formato do destino.
Mostre o rascunho exato, a mídia, o destino, a data, o horário e o fuso horário para revisão.
Ainda não agende nem publique.

Aprove o post exato antes de agendar

Quando todos os detalhes estiverem corretos, dê uma instrução específica com o modelo abaixo. Isso cria um agendamento real que pode publicar publicamente. Use conteúdo e uma conta em que pretende publicar. A publicação imediata também precisa de uma instrução explícita após revisar os mesmos detalhes.

Resultado esperado: um ID de Scheduled Post, destino pretendido, horário aceito e status atual. Um agendamento aceito não significa que o provedor o publicou.

Agende o post exato aprovado abaixo na conta indicada, na data, no horário e no fuso informados.

[Cole o conteúdo final, a mídia, o destino, a data, o horário e o fuso horário.]

Verifique primeiro se já existe um agendamento correspondente. Envie este post uma vez e leia o resultado salvo. Retorne seu ID, destino, horário aceito e status atual. Se o resultado for incerto, verifique a solicitação existente antes de outra ação.

7. Verifique o resultado, reagende ou cancele

Peça ao agente para ler o mesmo Scheduled Post usando sosoapi_get_scheduled_post. Você também pode abrir https://app.sosoapi.ai/scheduled-posts/<post-id> após entrar com uma conta autorizada. Verifique cada destino separadamente quando a solicitação envolver várias contas; alguns podem ter sucesso e outros precisar de atenção.

Leia o resultado atual do Scheduled Post [ID retornado].
Mostre o destino, o horário agendado, o status atual e o resultado da publicação.
Se a publicação estiver confirmada, inclua o link ao vivo quando disponível.
Não tente novamente, reagende ou crie outro post.

Gerencie um post pendente e volte depois

Para alterar um post pendente, informe seu ID e os novos detalhes. O agente deve ler a versão atual e as ações disponíveis antes de uma atualização ou cancelamento compatível. O cancelamento depende da etapa de entrega e pode deixar de estar disponível quando ela começa. Cancelar um agendamento não remove um post já publicado no provedor.

Após receber os detalhes salvos de um agendamento futuro, você pode sair da conversa e voltar ao mesmo post depois. Uma conversa fechada do agente não promete se reativar nem notificar você, a menos que isso tenha sido configurado separadamente.

8. Adicione imagens ou vídeo e reutilize o fluxo

Faça o fluxo de um único post funcionar antes de preparar um lote maior. Diga ao agente se a mídia é um arquivo local, uma URL pública ou um recurso SosoAPI existente.

Arquivos locais: o MCP local pode usar sosoapi_upload_asset. O arquivo precisa estar em uma pasta de upload permitida; a ferramenta informa os locais permitidos para caminhos fora dos limites. O MCP hospedado não pode ler arquivos do seu computador.

URLs públicas: use sosoapi_import_asset_url e depois sosoapi_get_asset_import_status com include_asset=true. Aguarde o recurso ficar pronto. Para um recurso existente, verifique se pertence ao Workspace pretendido e está pronto para o formato escolhido.

A solicitação normal de agendamento usa juntos o ID do recurso registrado e sua URL canônica. Uma URL temporária de prévia ou a URL externa original não os substitui. No fluxo compatível de uma URL de imagem, sosoapi_post_image_url combina importação e envio. É uma operação de publicação: aprove primeiro o post completo. Mantenha o ID do post aceito durante o processamento; não inicie outra importação para continuá-lo.

O X aceita um Post TEXT original sem mídia, ou VIDEO com exatamente um recurso de vídeo MP4 registrado e pronto, com pelo menos 0.5 segundos e dentro do limite de upload de 500 MiB. Vídeo exige can_publish_video verificado para a conta exata; acesso a texto não basta. Uma conexão antiga pode precisar da sua aprovação para reconectar com permissão de upload de vídeo. Texto, hashtags e link devem caber no limite ponderado do X. Fotos, respostas, citações, republicações e sequências não são compatíveis. A aceitação do upload ou processamento de vídeo não é um resultado publicado.

Antes de um envio ao X, leia sosoapi_get_x_usage para o workspace_id pretendido e o texto final. Sua cota e custo são separados da cota geral do plano. Não contorne um limite de créditos com envios repetidos; concilie uma publicação incerta antes de outro envio.

Prepare um lote revisado e leia o desempenho com honestidade

Após seu primeiro post bem-sucedido, tente a solicitação de lançamento de produto abaixo. Depois de aprovar a tabela exata, verifique o lote em relação aos limites do plano. Informe destinos aceitos e rejeitados separadamente e mantenha a identidade de cada post aceito.

O acesso à publicação e à análise pode ser diferente. Se depois você pedir uma avaliação de desempenho, as métricas indisponíveis devem ser informadas como indisponíveis. Não invente zeros nem deduza que toda métrica pode ser lida porque um post foi publicado.

Com a mesma configuração verificada, prepare sete rascunhos de anúncio de produto, um por dia, a partir dos fatos públicos que eu fornecer. Mostre uma tabela de revisão com rascunho, destino, mídia, data local, horário e fuso em cada linha. Mantenha os sete como rascunhos até eu aprovar a tabela exata.

9. Passo a passo da CLI e API

Use este caminho opcional para arquivos explícitos de solicitação ou uma integração de backend. Usuários de agentes podem pular. Os exemplos usam as mesmas permissões de conta, Workspace e publicação do MCP.

Examine primeiro a ajuda e o contrato incorporado do pacote instalado; consultar o contrato não exige login. Ele mostra as operações e esquemas fornecidos com esse pacote. Use esses nomes de campo em vez do formato de solicitação de outro provedor.

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

CLI: faça sua primeira solicitação de contexto autenticada

Conclua auth login. Com um editor de texto, salve workspaces.json com o JSON abaixo e execute o comando. Use arquivos para corpos de solicitação em vez de interpolar conteúdo em comandos de shell.

A CLI retorna schema_version, http_status e body. Uma resposta bem-sucedida inclui body.active_workspace_id e body.workspaces. Escolha o Workspace pretendido nessa resposta; o Workspace ativo não decide silenciosamente o destino de uma nova tarefa. A primeira chamada de uma nova conta pode inicializar seu primeiro Workspace.

Verifique http_status e body, não apenas o código de saída do shell. Um comando pode retornar um envelope de erro HTTP sem a operação API ter sucesso.

{}

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

CLI: selecione a conta social conectada

Salve accounts.json com o ID do Workspace retornado para sua conta e execute o comando. Selecione a conta pretendida em body.accounts. O ID de conta SosoAPI dela é o social_account_id usado no agendamento; um nome de usuário ou ID de Page do provedor não o substitui.

{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}

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

CLI: agende um texto aprovado no Threads

Este é um modelo de solicitação, não um post pronto para executar. Salve post.json com um editor e substitua cada valor entre colchetes pelos seus valores autorizados. Escolha um timestamp ISO futuro com deslocamento UTC explícito, ou Z para UTC. display_timezone é um fuso IANA para exibição; ele não completa um timestamp local ambíguo.

Gere um idempotency_key exclusivo, como um UUID, e mantenha-o com o corpo exato da solicitação. Repita uma solicitação idêntica com a mesma chave; uma resposta demorada não justifica gerar outra. Um post alterado é outra solicitação: verifique o resultado original antes de escolher uma nova identidade.

Após confirmar conteúdo, conta, horário, permissões e cota atual, execute o comando create. Isso agenda um post real. Ao ser aceito, mantenha body.post.id e leia body.post.status, body.post.scheduled_at e body.post.destination. body.deduped informa se uma solicitação existente foi reutilizada. Aceitação não é publicação confirmada pelo provedor.

{
  "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: leia o post salvo e seu resultado

Salve post-status.json com o ID retornado. Leia body.post, body.delivery, body.actions e body.outcomes. Confirme um resultado publicado antes de informar sucesso. Se a resposta de create foi perdida, recupere a solicitação original com a identidade salva; não crie outro agendamento com uma nova chave.

{
  "id": "<RETURNED_POST_ID>"
}

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

CLI: cancele apenas quando o resultado atual permitir

Se a leitura mais recente permite cancelar e você quer cancelar, salve cancel.json com o ID retornado e o valor numérico atual de body.post.version. O 1 do exemplo é ilustrativo: substitua pela versão que acabou de ler. Depois execute o comando e confirme o resultado.

Se a versão mudou ou o cancelamento não está disponível, leia o mesmo post novamente e use as ações realmente disponíveis. Não contorne um conflito de versão nem confunda cancelamento com exclusão de um post já publicado.

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

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

HTTP: chame pelo seu próprio backend

Para uma integração no servidor, crie uma chave API em Connection → API e armazene o segredo na configuração de segredos do servidor. A tela atual pede um nome; não oferece seletores de Workspace ou recursos. Uma chave criada pelo usuário tem operate, publish e engage por padrão nos Workspaces que ele pode acessar. Verifique se essa autoridade é adequada à integração. O contrato API permite limitar explicitamente capabilities e workspace_ids para uma chave com escopo restrito.

A configuração normal do agente usa OAuth e não precisa desta etapa de chave API. No exemplo, SOSOAPI_ACCESS_TOKEN é sua variável de exemplo no servidor contendo a chave; não é uma configuração da CLI SosoAPI. A variável opcional de token de acesso pessoal da CLI é VICKY_API_KEY.

Use o arquivo workspaces.json acima. HTTP direto retorna o corpo do endpoint sem o envelope http_status/body da CLI; leia o status HTTP real e o JSON. Mantenha credenciais no backend e fora do código do navegador, prompts, capturas e arquivos de solicitação compartilhados.

Incorporar a conexão social em um produto para seus próprios clientes é uma tarefa de integração separada. Este passo a passo de uma única conta não comprova que esse fluxo de integração de clientes está pronto.

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'

• Gerencie chaves API: Connection → API
• Referência da API
• Criação de chave API e autoridade explícita
• Autenticação e permissões
• Referência da CLI

10. Solução de problemas

Use o erro real e a conexão que está diagnosticando. Ampliar permissões ou repetir um envio não corrige toda falha.

Atualize, revogue o acesso ou peça ajuda

O primeiro comando abaixo verifica a ajuda do pacote mais recente sem iniciar o servidor MCP. Se o cliente fixa uma versão no comando salvo, atualize esse comando deliberadamente. Atualizar uma instalação global separada não atualiza a cópia fixada do cliente.

Para revogar um dispositivo local, use Connection → Agent ou o comando auth logout abaixo. Para um conector hospedado, revogue a autorização hospedada correspondente em Connection → Agent. Chaves API são gerenciadas separadamente em Connection → API. Revogar o acesso do agente não cancela agendamentos já aceitos; gerencie esses posts separadamente.

Para obter ajuda, informe a versão do cliente e pacote, a etapa que falhou, o erro exibido e o horário/fuso. Compartilhe IDs relevantes de solicitação ou post em particular com o suporte quando necessário. Não envie credenciais, links de autorização ou logs brutos que possam conter tokens.

npx -y sosoapi@latest --help

npx -y sosoapi auth logout

• Gerencie clientes de agente: Connection → Agent
• Gerencie chaves API: Connection → API
• Referência de solução de problemas
• Entre em contato com o suporte SosoAPI

Lista de verificação da configuração

Você pode concluir a conexão sem enviar um post. Se publicar, use a verificação separada do resultado para confirmar esse primeiro fluxo de publicação.

• Meu cliente pode usar ferramentas SosoAPI, ou minha CLI/API pode fazer uma solicitação autorizada.
• Entrei com a conta pretendida e selecionei o Workspace correto.
• Minha conta social aparece com os recursos necessários à tarefa.
• Entendo se meu agente pode preparar trabalho ou também agendar e publicar.
• Posso preparar um rascunho e revisar o destino, o conteúdo e o horário exatos.
• Se enviei um post, mantive seu ID e sei distinguir aceitação de publicação confirmada.
• Sei como investigar uma falha, gerenciar um agendamento pendente e revogar o acesso.