Os seus canais.
O seu assistente de IA.

Ligue em três passos.

O MCP permite a um cliente de IA compatível usar as ferramentas SocialBlaze. Não precisa de escrever GraphQL para ler publicações, criar rascunhos ou agendar através das ferramentas específicas.

https://backend.socialblaze.ai/api/developer/mcp

As funcionalidades dos clientes e a disponibilidade das contas variam. Uma ligação MCP personalizada não significa que exista um conector publicado num marketplace. Para uma aplicação pessoal de servidor, use a Introdução rápida à API; para outros utilizadores, use Registo de aplicações OAuth.

Ligar ao Claude

1. Abra Personalizar > Conectores, escolha Add e depois Add custom connector. Dê-lhe o nome SocialBlaze, cole o URL do servidor MCP acima e continue.
2. Reveja as definições de autenticação detetadas. Escolha Sign in now e, em OAuth client, Register automatically. A SocialBlaze usa registo automático em vez da identidade publicada do Claude. Inicie sessão na SocialBlaze, reveja as permissões pedidas e selecione os canais; termine com Add. Esta ligação OAuth não exige chave API.
3. Numa nova conversa, abra +, depois Connectors e ative SocialBlaze. Se o Claude indicar que o servidor já está ligado, use a entrada existente em Yours em vez de criar outro conector.

Os administradores do espaço de trabalho podem ter de adicionar primeiro o conector. Consulte o Guia de conector personalizado do Claude para os ecrãs atuais e requisitos de conta.

Falta um canal ligado no meu assistente de IA

Confirme que o canal está desbloqueado e acessível na SocialBlaze. Depois volte a ligar a SocialBlaze na aplicação de IA, reveja as permissões pedidas e selecione o canal em falta. Adicionar ou desbloquear um canal não o acrescenta a uma ligação de IA existente; atualizar essa ligação mantém a seleção de canais. Mantenha a ligação atual até a nova funcionar. Não precisa de voltar a ligar o Instagram ou Facebook apenas para mudar os canais da ligação de IA.

Se tem permissão de estatísticas e o canal está visível, mas não há relatório guardado, trata-se de um problema separado de disponibilidade de dados. Alterar a seleção de canais não recolhe nem atualiza estatísticas.

Experimente pedidos úteis e delimitados

Para as «últimas 10 publicadas», mantenha separada cada publicação de canal devolvida, mesmo quando as legendas ou ligações para artigos coincidem. Os resultados abrangem os canais autorizados, não necessariamente a conta inteira. Um relatório guardado em falta ou uma métrica desconhecida não é zero; ler um relatório não atualiza uma rede. Os cartões de pré-visualização estão em fase de pré-visualização. No ChatGPT, a primeira apresentação pode falhar; escolha Try again para carregar os cartões. Se uma imagem não carregar, abra a publicação guardada na SocialBlaze. A disponibilidade noutras aplicações de IA varia. Imagens alojadas externamente podem estar indisponíveis; uma pré-visualização não corrige a origem. Publicações agendadas ou aceites não são entregas confirmadas; verifique o estado devolvido antes de comunicar sucesso.

O estado do serviço tem uma página própria.

Consulte as provas atuais dos serviços principais, API e MCP e publicação nas redes na Página de estado do serviço.

Acompanhe o que estamos a desenvolver.

Veja o trabalho disponibilizado, as melhorias atuais e os planos na Página do plano de desenvolvimento.

Crie o seu primeiro pedido à API.

Inicie sessão na conta SocialBlaze, abra a consola de programador e crie uma chave. Escolha os canais e permissões necessários à integração. Copie o segredo uma vez e guarde-o no servidor.

curl -A 'SocialBlazeDeveloperClient/0.1 (+https://socialblaze.ai/api)' 'https://backend.socialblaze.ai/api/developer/graphql' \
  -H "Authorization: Bearer $SOCIALBLAZE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ channels { id name service connected } }"}'

Os IDs de canal devolvidos pertencem ao acesso selecionado. Use-os ao criar publicações. A consola inclui um explorador executável que mantém a credencial em memória durante a sessão.

Prepare. Reveja. Agende. Publique.

mutation Publish($key: String!, $channels: [ID!]!, $text: String!) {
  createPost(requestKey: $key, channelIds: $channels, text: $text,
    mode: publishNow) {
    accepted published
    posts { id channelId status publishingState publishedUrl
      failure { code message automaticRetrySafe } }
  }
}

Aceite não significa entregue. Leia post.allowedActions para orientações delimitadas de edição/cancelamento local; cada mutação volta a verificar a versão atual e o estado de publicação. Leia cada ID devolvido para verificar estado, URL publicado e detalhes de falha. Um lote misto inválido não guarda nada. Nunca repita uma escrita incerta com uma chave nova.

Preserve contentItemId de createPost ou createThread. Eliminar um destino pode preservar o rascunho de origem. Para remover o grupo de conteúdo local completo, leia a versão atual do item de conteúdo e use deleteContentItem; confirme depois que o grupo e as respetivas publicações já não existem.

Escolha uma data ou posição na fila

Use mode: schedule com uma data futura explícita em dueAt para uma hora fixa. Use addToQueue ou prioritize sem data para colocação na fila nativa do canal. As ações de fila exigem a funcionalidade de filas inteligentes do plano e permissão de publicação. Para mover uma publicação futura existente, use movePostInQueue ou a ferramenta MCP move_post_in_queue com a versão mais recente e uma chave de pedido estável.

Mover publicações na fila pode alterar as horas de outras publicações. Após uma alteração, volte a ler as publicações agendadas do canal e as versões. Mover uma publicação elegível criada na fila para o fim pode compactar a fila sob controlo seguro nos horários existentes; uma publicação com data fixa não passa a integrar essa fila só por partilhar uma hora. Titularidade mista, estado de publicação inseguro ou horários fixos ocupados podem impedir a reordenação. A aceitação devolvida não é um comprovativo de entrega.

mutation MoveInQueue($id: ID!, $version: String!, $key: String!) {
  movePostInQueue(id: $id, version: $version, requestKey: $key,
    position: "bottom") { id version deleted }
}
# Read the post's current version first. Use "top" for priority placement.
# Then read this channel's scheduled posts again to check actual due times.

Ler publicações entregues sem combinar canais

Leia cada publicação de rede separadamente, mantendo ID, canal e URL devolvido. A ordenação predefinida por ID de registo decrescente corresponde ao feed do site nos canais autorizados da credencial. Uma autorização para canais selecionados não expõe todos os canais do espaço de trabalho. Para uma cronologia baseada em provas elegíveis de entrega registada, peça sort: [{field: publishedAt, direction: desc}] e, opcionalmente, publishedAfter/publishedBefore. Leia o campo anulável publishedAt e publishedAtBasis. native_terminal_delivery_observed é a primeira hora local de confirmação terminal, não uma hora original de publicação do fornecedor verificada independentemente; datas agendadas, de criação e edição nunca preenchem uma hora de publicação desconhecida. Horas desconhecidas são ordenadas no fim e não permitem afirmar uma cronologia completa das últimas dez. Reinicie os cursores quando mudar filtros ou ordenação.

query {
  posts(first: 10, status: "delivered") {
    nodes { id channelId text publishedUrl publishedAt publishedAtBasis }
    pageInfo { endCursor hasNextPage }
  }
}
# Default order matches the website feed's descending record IDs.
# For known recorded publication times, use sort:[{field:publishedAt,direction:desc}].

Filtrar e paginar listas de publicações

Omita statuses para deixar o estado sem restrições. Um valor explicitamente vazio de statuses: [] não seleciona publicações; em GraphQL, statuses: null também deixa o filtro sem restrições. Se fornecer o valor singular status com statuses, os seus valores formam uma única seleção, pelo que um estado singular continua a aplicar-se juntamente com um array vazio. Estas regras também se aplicam à contagem de publicações correspondente. Com dueAt em ordem crescente, as publicações sem data agendada aparecem primeiro; em ordem decrescente, aparecem no fim. publishedAt mantém horas desconhecidas no fim em qualquer direção. Use dueAtPresence: present quando quiser apenas datas agendadas. Continue com o valor devolvido pageInfo.endCursor; recomece sem after quando filtros, ordenação ou acesso selecionado mudam, ou um cursor é rejeitado. Um cursor guardado antes da atualização de ordenação por data prevista não pode ser reutilizado numa ordenação com dueAt em ordem crescente.

Imagens, vídeo e documentos

Anexe imagens JPEG, PNG ou WebP dentro do limite de cada destino, ou um vídeo MP4/MOV. Publicações normais aceitam até 10 imagens no Facebook, Instagram, Tumblr e WordPress; 20 no LinkedIn e Threads; 35 no TikTok; 4 no Bluesky, Mastodon e Google Business Profile; e 1 no Pinterest. O YouTube exige vídeo. O Tumblr aceita um vídeo H.264 MP4/MOV até dez minutos, dentro do mesmo limite de importação de 50 MB. Uma publicação partilhada tem de cumprir as regras de todos os destinos. Grupos de várias publicações e fios mantêm um total de oito anexos por pedido. As imagens podem incluir uma pré-visualização protegida separada em thumbnailUrl para a pré-visualização SocialBlaze; não substitui a imagem enviada para uma rede. As imagens também aceitam uma pré-visualização protegida separada em animatedThumbnail: uma pré-visualização pública GIF ou WebP até 1 MiB. As pré-visualizações estáticas e animadas usam limites de importação próprios e mantêm URLs separados. A imagem original continua a ter de cumprir as regras do destino. As leituras de recursos expõem ambos os URLs; isAnimated permanece null até a animação ser medida, pelo que um URL de pré-visualização não prova que a imagem original é animada. O LinkedIn também aceita um PDF com título e thumbnailUrl HTTPS opcional para a pré-visualização SocialBlaze. As imagens de pré-visualização são ficheiros JPEG, PNG ou WebP validados até 1 MB; o LinkedIn apresenta as suas próprias páginas do documento. As imagens têm limite de 8 MB cada, os vídeos de 50 MB e os PDFs de 20 MB. Continua a aplicar-se a validação específica do canal; consulte configuration e channel.capabilities.

Os recursos PDF guardados expõem campos anuláveis numPages (número de páginas medido) e filesize (bytes da importação validada). Os recursos antigos ou com contagem de páginas indisponível mantêm null, nunca um zero inventado; o tamanho medido pode continuar disponível quando o número de páginas é desconhecido. Estes valores descrevem o PDF importado guardado, não uma cópia apresentada pelo fornecedor. A leitura não volta a transferir o ficheiro nem preenche dados de recursos antigos. As ferramentas MCP get_post e list_posts incluem os campos. Para o cliente Node 0.1.14 imutável, use uma seleção GraphQL explícita quando precisar destes campos mais recentes.

query SavedDocument($postId: ID!) {
  post(id: $postId) {
    id version
    assets { type title mimeType numPages filesize }
  }
}

Agendar uma publicação com multimédia e sem legenda

Para um destino suportado, createPost e a ferramenta create_post aceitam text: "" com imagens válidas ou um vídeo. Texto vazio sem multimédia é rejeitado. Continuam a aplicar-se títulos obrigatórios, escolhas específicas de rede e limites de multimédia; um exemplo de rascunho só de texto não demonstra este fluxo. Numa ligação interativa de publicação, o cartão preparado também pode manter uma legenda vazia com multimédia: reveja as contas e o conteúdo antes de escolher Schedule ou Post.

mutation ScheduleVideo($key: String!, $channel: ID!, $url: String!,
    $when: String!) {
  createPost(requestKey: $key, channelIds: [$channel], text: "",
    video: {url: $url}, mode: schedule, dueAt: $when) {
    contentItemId accepted published posts { id channelId status dueAt version }
  }
}
# Use a direct public HTTPS MP4/MOV URL and an eligible video channel.
# Choose a future ISO 8601 time with an explicit UTC offset.
# Check that channel's required publishing options before submitting.

Editar e pedir revisão em conjunto

Para um rascunho simples de um único canal, pertencente à integração, num canal que exige aprovação, use updatePost com approvalChange: request ou revert. A ferramenta MCP edit_post suporta estas escolhas sem texto. Forneça a versão mais recente, uma chave estável, drafts:write e posts:review. O conteúdo e os anexos mudam atomicamente com o pedido de revisão. A aprovação, por si só, não publica; submeta depois explicitamente o rascunho aprovado sem alterações. Conteúdo aprovado que seja alterado precisa de nova revisão.

Alterar o método de uma publicação futura

Use updatePost(publishingMethod: automatic) ou reminder, ou a ferramenta edit_post, para alterar uma publicação futura segura, mantendo o ID. Indique a versão atual e uma chave de pedido estável. São necessárias permissões de rascunho e de publicação. As publicações automáticas têm de ter um único agendamento futuro; os lembretes têm de estar na fila e ainda não ter sido notificados. Publicações com tentativas de publicação, requisitos de revisão ou pertencentes a fios não podem ser convertidas. Um lembrete exige um dispositivo móvel ativo com sessão iniciada e notificações. A conversão volta a verificar destino, plano, multimédia e acesso atual; não confirma a entrega na rede.

Acompanhar a origem da composição

createDraft, createPost, createThread e cada entrada de createContentItemVariants aceitam um valor anulável em source, uma etiqueta de acompanhamento declarada pelo chamador, com até 250 caracteres. As ferramentas MCP de criação correspondentes suportam-na, incluindo publicações para revisão. Um fio partilha a etiqueta entre as entradas; as variantes podem usar etiquetas diferentes. Leia-a através de post.provenance.composerSource e composerSourceBasis; a ferramenta get_post e Node getPost incluem proveniência. As leituras normais de listas também a incluem; listas com métricas guardadas omitem proveniência e metadados de pré-visualização animada para respeitar o mesmo limite de consulta. Leia publicações individuais para obter ambos. Omissão ou null na criação deixa a etiqueta desconhecida. Edições de rascunhos e publicações futuras também a aceitam: omissão preserva e null limpa. Esta etiqueta não altera o meio de criação registado, concede permissões nem prova autoria por IA.

Declarar assistência de IA

As edições de rascunhos e publicações futuras aceitam um valor anulável em aiAssisted, incluindo a ferramenta MCP edit_post. False continua false, null limpa a declaração do chamador e a omissão preserva-a. Isto não altera o meio de criação nem deteta quem escreveu o texto. Use a versão mais recente e a mesma chave para repetir um pedido sem alterações.

Regras de cada formato

Leia configuration.services.contentRules ou channel.capabilities.contentRules para cada formato automático de publicação e tipo de anexo. As regras incluem contagem de legendas e títulos, número de anexos, tipos de ficheiro e limites de bytes, escolhas obrigatórias de canal e suporte de primeiro comentário. Este catálogo descreve a validação SocialBlaze. Continuam a aplicar-se o plano, as permissões atuais, as dimensões e as verificações do fornecedor; não confirma a entrega. Reels exigem um vídeo; Stories automáticas exigem uma imagem ou um vídeo.

Metadados dos canais e menções

Leia os totais de membros do espaço de trabalho e os limites nativos do plano através de account.organizations. Os canais incluem IDs de destino do fornecedor, URLs de perfil seguros, ícones de rede e capacidades de publicação. Use paginação em seleções grandes com channels(first, afterId); MCP list_channels devolve metadados de paginação.

Os recursos de publicações e da biblioteca devolvem os valores guardados de mimeType, width e height quando conhecidos; valores desconhecidos permanecem null. Não é necessário transferir multimédia para os ler. Menções estruturadas de Facebook Page e LinkedIn usam channelOptions.mentions com posições de início/comprimento em pontos de código Unicode e uma etiqueta correspondente. Leia post.annotations para menções validadas e ligações literais. Intervalos inválidos ou sobrepostos são rejeitados; legendas alteradas têm de fornecer posições de menção atualizadas.

Proveniência registada e estado da conta

Leia post.provenance para o meio de criação registado e a assistência opcional de IA declarada pelo chamador. Defina aiAssisted explicitamente quando conhecido; o desconhecido permanece null. Um pedido através de um cliente de IA não prova que a IA escreveu a legenda. A declaração de vídeo ao fornecedor usa uma definição separada do canal.

account.preferences devolve os códigos guardados de apresentação de calendário e hora quando conhecidos. As leituras de canais distinguem queuePaused, workspacePublishingPaused e credentialsExpired; suspender a publicação não significa, por si só, que a credencial do fornecedor expirou.

Contagem de texto por rede

O Bluesky usa etiquetas visíveis de URL compactas, mantendo os destinos completos em facetas de ligação indexadas por bytes UTF-8. As legendas guardadas mantêm os URLs originais. O Mastodon usa os metadados configurados da instância e as regras oficiais de grafemas, URLs reservados e menções remotas; avisos de conteúdo são contados literalmente. Leia textLimitsBasis, textLimitsMetadataAvailable e charactersReservedPerUrl nas capacidades de publicação para distinguir metadados atuais da instância de uma alternativa conservadora. As leituras de metadados são limitadas e mantidas em cache.

Fotografias, vídeo e entrega no TikTok

As legendas de fotografias permitem 4,000 unidades UTF-16, com título opcional até 90 unidades. As legendas de vídeo permitem 2,200 unidades. Defina channelOptions.isAiGenerated explicitamente para a declaração de vídeo; true é rejeitado para fotografias. Edições futuras de metadados de vídeo preservam um false explícito. Leia tiktokPostingChoices(channelId) ou MCP get_tiktok_posting_choices para as escolhas reais de privacidade, restrições de interação e duração de vídeo do criador selecionado. Estas leituras podem usar cache com até 60 segundos; a publicação volta a validá-las. Escolha público e consentimento explicitamente. Um ID de publicação devolvido confirma aceitação: publicações de programador permanecem em processamento até um retorno verificado do fornecedor ou uma leitura limitada do estado confirmar a entrega para a mesma tentativa original. Verificar o estado não submete outra publicação. O URL público pode continuar desconhecido.

Menções em imagens do Instagram

Defina images[].userTags com um valor público em handle sem @ e com coordenadas numéricas x/y como posições entre 0 e 1. Use até vinte nomes de utilizador únicos por imagem. Imagens de feed e elementos de carrossel suportam menções posicionadas; carrosséis principais e Stories automáticas não. Remova menções posicionadas antes de agendar uma Story automática. Estes campos são exclusivos do Instagram; nomes e coordenadas inválidos ou duplicados são rejeitados. Os modelos da biblioteca preservam menções de imagem quando reutilizados. Não são etiquetas internas de conteúdo.

Lembretes de publicação manual

Defina publishingMethod: reminder para os canais selecionados. Cada um recebe o seu lembrete. Ative primeiro as notificações na aplicação móvel SocialBlaze com sessão iniciada. O lembrete mantém um rascunho preparado e abre o conteúdo na hora prevista; nunca publica automaticamente. São suportados data explícita, próximo horário da fila manual e prioridade. changeReminder reagenda ou cancela, ou regista a sua própria confirmação de publicação. Para lembretes do Instagram, stickerFields podem conter música, produtos, texto, tópicos e outras instruções finais, até 2,000 caracteres cada. O ecrã de lembrete com sessão iniciada apresenta-as e permite copiá-las. Acrescente estes detalhes no Instagram; a publicação automática rejeita campos de finalização preenchidos. Uma notificação enviada ou confirmação manual não é um comprovativo de entrega na rede. Um pedido multicanal partilha multimédia importada e guarda o grupo inteiro ou nada. Eliminar o item de conteúdo cancela todos os lembretes pendentes. Para revisão da equipa, defina também requestApproval: true com posts:review e consentimento explícito posts:publish. O lembrete aguarda aprovação nativa, permanece protegido contra publicação automática e é cancelado se a revisão for retirada ou a aprovação deixar de ser válida.

Definições de vídeo YouTube

Escolha privacy e madeForKids explicitamente. Consulte configuration.youtubeCategories para IDs de categoria do fornecedor e defina categoryId quando necessário. As opções embeddable, license (youtube ou creativeCommon), notifySubscribers e isAiGenerated chegam ao carregamento nativo do YouTube. Valores false explícitos são preservados. Pode editar estas definições numa publicação futura através de updatePost.channelOptions sem substituir o vídeo. A declaração de IA refere-se a conteúdo realista alterado ou sintético; siga os requisitos de declaração do YouTube.

Capas de vídeo

Para um vídeo do Instagram, TikTok ou Pinterest, defina thumbnailOffset nas opções do canal para o desvio, em milissegundos, do fotograma de capa. Tem de estar dentro da duração do vídeo importado. Para uma publicação futura segura, updatePost pode alterar a capa de uma importação existente pertencente à conta ou substituir o vídeo e escolher a capa no mesmo pedido. Publicações nativas existentes podem usar esta edição quando a multimédia é uma importação suportada pertencente à conta; URLs externos arbitrários de vídeo não são elegíveis para editar apenas a capa. Omitir multimédia e agendamento mantém o recurso e a hora guardados. Reutilize a mesma chave após uma resposta incerta. O Pinterest recebe o desvio do fotograma em segundos inteiros e aceita um vídeo MP4/MOV importado até 50 MB; o vídeo é carregado e processado antes de criar o Pin. Os Reels do Instagram também aceitam shareToFeed, incluindo um false explícito. Os outros canais e as Stories do Instagram rejeitam estas opções.

As edições futuras exigem a versão atual da publicação e um agendamento a mais de dois minutos. Publicações em curso ou entregues não podem ser alteradas. A edição da partilha de um Reel no feed preserva o vídeo e a capa quando esses campos são omitidos. Para o Pinterest, edite channelOptions.destinationUrl para alterar a ligação de destino; null explícito limpa a ligação guardada. As leituras devolvem esse valor em destinationUrl e nas opções do canal. Estas edições não publicam imediatamente.

Cartões de ligação

Para publicações normais do Facebook, LinkedIn, Bluesky ou Threads sem outros anexos, forneça linkUrl nas opções do canal. LinkedIn e Bluesky também aceitam linkTitle e linkDescription. O Facebook e o Threads usam a pré-visualização do site de destino. O LinkedIn e o Bluesky também aceitam linkThumbnailUrl com o URL da ligação: um JPEG, PNG ou WebP público direto até 1,000,000 bytes, com oito pré-visualizações distintas por pedido. É importado de forma protegida e enviado ao fornecedor; uma falha de carregamento interrompe o processo antes da publicação. Guarde uma pré-visualização nova no rascunho antes de o submeter. Null limpa uma pré-visualização guardada. Ligações HTTPS não podem conter credenciais. Não é feita extração de páginas no servidor. Edite cartões futuros com updatePost.channelOptions; um null explícito em linkUrl limpa o cartão e o título/descrição. Limpá-lo e substituir multimédia no mesmo pedido é uma operação atómica. As opções de rascunho combinam os campos explicitamente alterados; uma lista vazia repõe todas as escolhas.

Localizações e tópicos do Threads

Publicações de feed/Reel do Instagram e do Threads aceitam um valor numérico do fornecedor em locationId e, opcionalmente, locationName. Os elementos de carrossel do Instagram não recebem a etiqueta. As Stories automáticas do Instagram rejeitam esta opção. O Threads também aceita um campo topic até 50 unidades UTF-16, sem E comercial nem ponto. Escolhas omitidas preservam-se em edições futuras; null limpa-as.

Avisos de conteúdo e declaração de IA

O Mastodon aceita spoilerText; o aviso é contado literalmente e partilha o limite de caracteres configurado da instância com a legenda preparada. A contagem de URLs e menções remotas da instância aplica-se à legenda, não ao aviso. Use null para limpar um aviso guardado. Os vídeos do Instagram, YouTube e TikTok aceitam isAiGenerated. O Instagram envia-o apenas no contentor multimédia principal. As opções de rede não suportadas são rejeitadas antes de guardar qualquer publicação.

Primeiros comentários

Os primeiros comentários usam limites UTF-16 separados: Facebook 5,000, Instagram 2,200, LinkedIn 1,250 e Threads 500. Leia maxFirstCommentLength e firstCommentLengthUnit da capacidade do canal. Os emojis podem contar como duas unidades. Destinos não suportados e Stories rejeitam comentários; o texto nunca é truncado silenciosamente. Continuam a aplicar-se as permissões do plano existente.

Limites das legendas

A maioria das legendas de programador usa unidades UTF-16, nas quais muitos emojis contam como duas. URLs HTTP(S) no LinkedIn contam como 24 unidades; quebras de linha lógicas no Instagram contam como duas. As legendas Facebook permitem 5,000 e Instagram 2,196; títulos Pinterest e YouTube permitem 100. O Google Business mantém o limite nativo de 1,500. O Mastodon usa metadados limitados da instância, com uma alternativa conservadora configurada; leia os campos de capacidades para saber a base atual e a disponibilidade dos metadados. O Bluesky conta grafemas após compactar etiquetas visíveis de ligações, preservando os URLs completos nas facetas. As legendas originais guardadas não mudam. Leia as capacidades do canal para conhecer o limite e a unidade de contagem atuais.

Publicações do Google Business

Use channelOptions.businessPost para atualizações normais, eventos e ofertas. Eventos e ofertas precisam de título e datas locais de início/fim. Horas opcionais emparelhadas usam HH:mm; omitir ambos abrange o dia local completo. O agendamento de publicações em UTC mantém-se separado. Atualizações normais e eventos suportam botões de ação; ofertas usam cupão, ligação de utilização e condições. Botões de chamada usam o telefone do negócio sem URL de ação. Outros botões exigem URLs HTTPS. Estas opções exigem publicação automática, mantêm os limites existentes de resumo/imagem e nunca implicam entrega confirmada pelo fornecedor.

Áudio do Instagram

Explore ou pesquise música licenciada e sons originais através das consultas do catálogo de áudio. É necessário Facebook Login. Para um Reel de vídeo único, indique um ID de áudio e níveis de volume opcionais nas opções do canal. As pré-visualizações expiram; erros de permissão e resultados parciais são explícitos. As opções do rascunho guardado mantêm-se na submissão posterior.

Fios ordenados

Bluesky, Mastodon e Threads suportam 2–25 entradas. As respostas aguardam a entrega confirmada da entrada principal. Reagendar ou cancelar a raiz mantém juntas as respostas futuras seguras. Entradas Bluesky e Threads também aceitam linkUrl; o Bluesky aceita linkTitle, linkDescription e um linkThumbnailUrl protegido. Cartões não podem combinar-se com outros ficheiros multimédia; o Threads usa a pré-visualização do site de destino. O Mastodon rejeita cartões. Os fios permitem oito anexos por pedido e, no máximo, 100 publicações de destino.

mutation {
  createThread(requestKey: "launch-thread-001", channelIds: ["YOUR_CHANNEL_ID"],
    mode: schedule, dueAt: "2026-11-01T14:00:00+00:00",
    entries: [{text: "First part"}, {text: "The follow-up"}]) {
    contentItemId accepted posts { id status thread { rootPostId parentPostId position total } }
  }
}

Editar anexos ao longo de um fio futuro

Use updateContentItem.threadEntries ou a ferramenta edit_content_item para substituir ou limpar anexos e escolhas de ligação do fio existente completo. Forneça todas as entradas por ordem, a legenda, a versão atual do grupo e uma chave estável. Anexos omitidos ficam inalterados; images: [] ou clearMedia: true remove-os. Ficheiros partilhados são importados uma vez por entrada entre canais. Cada destino tem de estar sem tentativas, não publicado e a mais de dois minutos no futuro. A edição inteira é guardada atomicamente. Mantenha o mesmo número de entradas e edite o agendamento separadamente; alterações de dimensão e edições combinadas de multimédia/agendamento não são suportadas.

Filtros de grupos de conteúdo

Filtre contentItems por draftContent ou postContent, e ordenar por createdAt e updatedAt. Por predefinição, a descoberta limita-se à sua integração. A opção explícita discovery: workspace exige aprovação separada para content:read mais posts:read; as credenciais existentes não a recebem automaticamente. Também lê grupos visíveis segundo as permissões nativas do espaço de trabalho e os canais selecionados. Grupos com um destino inacessível são excluídos, incluindo legenda e multimédia partilhadas. Verifique managedByCurrentIntegration; alterações de grupo entre integrações continuam bloqueadas, enquanto alterações individuais mantêm verificações de autorização separadas. Os cursores estão associados à descoberta, filtros, ordenação e acesso aos canais; reinicie a paginação quando estes mudarem. O SDK0.1.14 fornece contentItems(options) e contentItem(id, options) como auxiliares de leitura.

Revisão da equipa

Use posts:review e requestApproval: true para criar publicações com publicação suspensa. requestPostApproval envia uma publicação existente não publicada para revisão. withdrawPostApproval devolve-o ao estado de rascunho apenas quando as permissões nativas de aprovação o permitem. A permissão de revisão nunca concede publicação automática.

Adapte cada destino.

Use createContentItemVariants quando cada canal precisa de legenda, título, anexo, opção nativa ou agendamento diferente. Forneça IDs distintos de canais selecionados em posts. O grupo suporta até 25 destinos e oito anexos no total, dentro dos limites existentes de multimédia e publicação. Entradas multimédia idênticas partilham uma única importação protegida.

mutation Campaign($key: String!, $posts: [ContentVariantInput!]!) {
  createContentItemVariants(requestKey: $key, title: "Product launch", posts: $posts) {
    contentItemId accepted published
    posts { id channelId text title status isDraft publishingMethod
      manualReminder { state providerDeliveryConfirmed } dueAt version }
  }
}
# Each posts entry supplies its own channelId, text, optional media,
# channelOptions, mode and dueAt. Read real channel IDs first.

A validação e a gravação são atómicas: uma variante com falha não guarda parte da campanha. Cada entrada usa por predefinição a fila ou o agendamento fornecido. Use mode: publishNow apenas para uma submissão imediata intencional. Defina requestApproval: true para revisão suspensa da equipa. A aceitação continua a não ser entrega confirmada.

Leia contentItem.hasChannelVariants e a versão do grupo; depois leia os IDs individuais das publicações para obter todos os detalhes. Edite uma publicação individual para preservar legendas diferentes. Uma edição de texto ou multimédia do grupo aplica intencionalmente a mesma alteração a todos os destinos futuros seguros. As versões do grupo e individuais são diferentes.

Promover um rascunho existente

Leia um rascunho sem canal, pertencente à integração e ainda não submetido, e a versão atual do grupo. Chame promoteContentItemDraft com um valor não vazio em posts como lista para transformar o mesmo item de conteúdo em publicações distintas por canal. Cada entrada fornece o seu ID de canal, texto explícito e multimédia, escolhas nativas e agendamento opcionais. A legenda e os anexos de origem mantêm-se guardados; a multimédia omitida numa entrada não os herda.

mutation Promote($id: ID!, $version: String!, $key: String!,
    $posts: [ContentVariantInput!]!) {
  promoteContentItemDraft(id: $id, version: $version, requestKey: $key,
    posts: $posts) {
    contentItemId accepted published
    posts { id channelId text status isDraft publishingMethod
      manualReminder { state providerDeliveryConfirmed } dueAt version }
  }
}
# Each entry needs its channelId and explicit text, plus any media/options.
# Read the existing draft's ID/version first; do not mix posts and channelIds.

Use, por canal, uma das opções posts ou a opção partilhada existente channelIds como formato. Não as combine nem misture escolhas por entrada com opções de agendamento de nível superior. Um destino com falha não guarda uma promoção parcial. Reutilize a mesma chave para repetir sem alterações; um rascunho submetido não pode ser promovido novamente com uma chave nova. Pedir revisão exige drafts:write e posts:review; a submissão automática exige posts:publish. Continuam a aplicar-se as regras nativas de aprovação da equipa. As entradas usam ContentVariantInput. Cada entrada aceita um valor anulável em aiAssisted: false continua false, null ou omissão deixa a assistência desconhecida, e texto alterado numa entrada nunca herda a declaração do rascunho original. Cada destino pode permanecer rascunho, usar publicação automática ou lembrete manual. Mantenha contentItemId para limpar o grupo completo.

Encurtamento automático de URLs por fluxo de trabalho

O encurtamento ocorre antes de guardar definitivamente, usando os conectores configurados do autor. As definições nunca são desativadas silenciosamente. O suporte depende do fluxo, anexo e escolhas nativas do canal; combinações não suportadas devolvem um erro que indica como agir.

O perfil básico de texto abrange Facebook, Bluesky, LinkedIn, Threads, Tumblr, Google Business Profile, Mastodon e WordPress. Os perfis de imagem sujeitos aos limites nativos também incluem Instagram e Pinterest; os perfis de vídeo incluem YouTube/TikTok suportados nativamente e outros serviços validados. A promoção agendada uniforme e as transições guardadas/nativas existentes têm catálogos separados de escolhas validadas; as regras de grupos mistos acima não permitem opções arbitrárias. Continuam a exigir-se privacidade/consentimento explicitamente guardados e validação nativa atual. Guardar nunca ativa a publicação, e a revisão nunca concede publicação. Leia allowedActions e as versões atuais; retire a revisão pendente antes de eliminar quando essa ação estiver disponível. A aceitação da preparação e o encurtamento não confirmam a entrega na rede.

Guardar um destino antes de agendar

Defina saveToDraft: true numa entrada para guardar um rascunho associado a um canal. Exige drafts:write, sem permissão de publicação nem uma nova autenticação para publicar. Guardar, por si só, não cria um agendamento nem um lembrete no telemóvel. O modo e a data de uma entrada guardada não a agendam nem se tornam instruções reutilizáveis de agendamento; escolha um modo e uma data novos quando a agendar explicitamente mais tarde. Null não é aceite em saveToDraft.

mutation SaveForChannel($key: String!, $channel: ID!, $text: String!) {
  createContentItemVariants(requestKey: $key, posts: [{
    channelId: $channel, text: $text, saveToDraft: true
  }]) {
    contentItemId accepted published
    posts { id channelId isDraft publishingMethod version }
  }
}

Leia o ID do destino e a versão mais recente e depois use armDestinationDraft ou a ferramenta arm_destination_draft para agendar a mesma publicação. A ferramenta específica chama ao ID postId. Escolha publishNow, schedule com dueAt, addToQueue ou prioritize. Se omitir o modo, uma data fornecida seleciona o agendamento; caso contrário, é usada a fila. A publicação automática volta a verificar a permissão atual de publicação, o acesso ao canal, os ficheiros multimédia, os requisitos de aprovação e o estado da autenticação.

mutation ScheduleSavedDraft($id: ID!, $version: String!, $key: String!,
    $when: String!) {
  armDestinationDraft(id: $id, version: $version, requestKey: $key,
    mode: schedule, dueAt: $when) {
    id version deleted
  }
}
# Use the destination post ID and its latest version, not the group ID.
# Then read the post to check publishing state; this is not a delivery receipt.

Devolver um destino futuro ao estado de rascunho

Para um destino automático gerido pelo proprietário cuja publicação ainda não começou, updatePost(saveToDraft: true) pode preservar o mesmo ID de destino, grupo de origem e anexos, desativando o único agendamento futuro. Forneça a versão atual e uma chave estável, com permissões de publicação e rascunho. O agendamento tem de estar a mais de dois minutos. Devolva-o primeiro ao estado de rascunho e depois edite-o separadamente; estados de revisão, lembrete, fio e tentativa de publicação mantêm fluxos próprios. Ative explicitamente a publicação do rascunho quando estiver pronto.

Rever um rascunho guardado

Num canal que exige aprovação, combine saveToDraft: true com requestApproval: true. Exige permissões de rascunho e revisão. O rascunho continua sem publicação ativada após a aprovação: agende explicitamente a versão aprovada sem alterações. Editá-la exige nova aprovação. Em contrapartida, pedir revisão ao agendar explicitamente uma publicação automática suspende esse agendamento até à aprovação.

Mantenha a publicação manual explícita

Defina, numa entrada, o campo publishingMethod: reminder quando alguém vai terminar a publicação no telemóvel. Um rascunho guardado mantém a escolha sem exigir dispositivo. Ao agendá-lo mais tarde, omitir o método preserva a escolha guardada; um método explícito seleciona-o novamente. Null não é aceite. Agendar um lembrete exige permissões de rascunho e publicação, um dispositivo ativo com sessão iniciada e notificações, e qualquer aprovação exigida. publishNow coloca na fila um lembrete para agora; não publica automaticamente na rede.

Leia isDraft, publishingMethod e manualReminder.state em conjunto. Uma entrada guardada com revisão pendente continua a ser rascunho, e uma escolha de lembrete guardada ainda não tem lembrete ativo. providerDeliveryConfirmed: false não é prova de entrega na rede. Grupos mistos podem conter entradas guardadas, agendadas e de lembrete; as ações por publicação continuam separadas. Use edit_post com draft: true para editar um destino guardado seguro e a operação canónica deleteContentItem ou delete_content_item para limpar todo o grupo. Retire primeiro a revisão pendente. Uma publicação assumida pelo processo ou com resultado incerto exige reconciliação, não eliminação sem verificação.

Ferramentas específicas para clientes de IA

get_publishing_configuration e get_channel expõem os requisitos reais de multimédia e consentimento. Use list_content_items, get_content_item, create_content_item_draft, promote_content_item_draft e create_content_item_variants sem escrever GraphQL. Ferramentas de edição, eliminação e associação mantêm as mesmas verificações de âmbito, versão e repetição.

Reutilize o conteúdo guardado.

Explore, crie e edite os modelos da sua biblioteca real de conteúdo SocialBlaze. Reutilize modelos de texto, imagem, vídeo e PDF em rascunhos. A edição exige a versão atual. Remover um modelo preserva os ficheiros carregados partilhados.

query {
  libraryItems(first: 20) {
    nodes { id title text description emoji visibility version assets { type url title altText } }
    pageInfo { endCursor hasNextPage }
  }
}

Use createDraftFromLibraryItem com ID, versão, chave de pedido e canais selecionados. O acesso à biblioteca segue o plano e as permissões atuais da equipa.

Os modelos aceitam uma descrição opcional (até 1,000 caracteres), emoji (até 32 caracteres) e visibilidade: internal para o espaço de trabalho ou private para o criador. Modelos existentes e visibilidade omitida permanecem internos. Só o criador pode tornar privado um modelo partilhado; modelos privados ficam ocultos aos outros membros na API, biblioteca nativa e leituras móveis. Filtre libraryItems(visibility: private) ou internal. Não existe um catálogo público de modelos selecionados. Null limpa a descrição ou o emoji; os campos omitidos são preservados nas edições. As edições nativas mantêm estas escolhas.

Crie o relatório de que precisa.

As recolhas explícitas junto do TikTok enumeram apenas vídeos públicos. enumerationComplete descreve essa consulta à origem; complete permanece false porque fotografias e vídeos privados são excluídos. Leia basis e note em relatórios, referências agregadas e cobertura de classificação antes de interpretar totais ou resultados vazios.

Relatórios normais de canais, métricas individuais de publicações, classificações e leituras agregadas usam apenas dados existentes do site SocialBlaze e instantâneos guardados. Uma leitura não contacta um fornecedor, coloca recolhas em fila nem atualiza dados em falta. As métricas disponíveis variam por rede; valores indisponíveis continuam desconhecidos, nunca zero.

query Report($channel: ID!, $start: String!, $end: String!, $report: ID,
    $first: Int = 20, $after: String) {
  channelReport(channelId: $channel, startDate: $start,
    endDate: $end, reportId: $report) {
    id state complete basis note enumerationComplete metricsUpdatedAt expiresAt errorCode
    metrics { key value status basis }
    posts(first: $first, after: $after) { nodes { externalId text publishedAt publicationDate publicationTimeBasis
      metrics { key value status } }
      pageInfo { endCursor hasNextPage } }
  }
}

Leia readMode, storedAnalytics e intervalos de datas guardados disponíveis quando não existe relatório normalizado. As secções nativas mantêm as etiquetas e bases de medição originais. A data de atualização de uma linha não prova que todas as métricas foram recolhidas nessa altura. Dados em falta permanecem indisponíveis; a expiração do token de publicação, por si só, não impede uma leitura histórica autorizada. Os intervalos continuam limitados ao histórico disponível da conta. Inspecione complete, o valor de cada métrica em status e o respetivo basis antes de interpretar totais. Cada relatório de canal e referência agregada identifica o serviço de rede. A leitura agregada metricsUpdatedAt é a data/hora contribuinte conhecida mais recente; oldestMetricsUpdatedAt indica o instante contribuinte mais antigo e permanece null quando uma origem pronta tem atualidade desconhecida.

As estatísticas opcionais de vídeo LinkedIn incluem valores únicos por publicação em viewers e totalTimeWatched em minutos. Os espectadores únicos nunca são somados entre publicações. No Instagram, follows é uma contagem atribuída a publicações elegíveis do feed e Stories, não a Reels nem ao crescimento líquido de seguidores. Estes valores dependem do acesso e disponibilidade do fornecedor; valores indisponíveis permanecem null. Não é inferida nenhuma unidade de tempo de visualização do Instagram.

A consulta de relatórios LinkedIn é limitada. Se atingir o limite de páginas ou não puder avançar em segurança, podem ser devolvidas linhas observadas utilizáveis com cobertura parcial. Os totais descrevem apenas esse subconjunto observado, nunca todas as publicações da conta. Leia a nota do relatório e o estado da enumeração antes de comparar canais.

As linhas de desempenho podem expor publicationDate e publicationTimeBasis separadamente de publishedAt. Um dia histórico do calendário nativo com fuso horário desconhecido mantém publishedAt: null; não invente uma hora de publicação à meia-noite UTC. Mantenha publicações de redes diferentes separadas, em vez de juntar as que ligam ao mesmo artigo.

Ler as secções de estatísticas guardadas do site

Use storedChannelAnalytics ou a ferramenta MCP get_stored_channel_analytics com analytics:read, um canal autorizado e datas de início/fim exatas. Cada secção identifica a origem, a disponibilidade e a base das datas. availableRanges lista intervalos guardados; não substitui por eles as datas pedidas. Uma secção bruta indisponível ou demasiado grande não prova que não existem publicações; verifique o código de erro e a leitura paginada channelReport como projeção.

Para TikTok, Pinterest, Tumblr e WordPress, o campo report como secção pode expor uma recolha explícita já guardada, identificada como saved_developer_report. São dados de relatório guardados, não prova de que um coletor nativo do site os produziu. Sem relatório guardado correspondente, o resultado é indisponível; a leitura não recolhe um. Um relatório pode estar pronto enquanto complete ou enumerationComplete é false. Preserve cobertura parcial e métricas indisponíveis ao comunicar resultados.

query StoredAnalytics($channel: ID!, $start: String!, $end: String!) {
  storedChannelAnalytics(channelId: $channel, startDate: $start, endDate: $end) {
    channelId service state complete basis note errorCode
    metricsUpdatedAt recordUpdatedAt freshness
    availableRanges { startDate endDate recordUpdatedAt }
    sections { name available source data rangeBasis startDate endDate
      metricsUpdatedAt recordUpdatedAt freshness errorCode note }
  }
}
# This reads saved data only. Use actual channel IDs and the requested dates.
# availableRanges does not silently replace a missing requested date range.

Na paginação de relatórios normalizados, mantenha juntos o ID do relatório devolvido, o canal e as datas e passe posts.pageInfo.endCursor como o próximo after. Comece sem cursor ao mudar de instantâneo. Uma métrica guardada de uma publicação e um relatório incompleto de canal podem ter coberturas diferentes; indique o estado e a base de cada resultado.

Recolha novos dados do fornecedor apenas quando solicitado

Use a opção explícita refreshChannelReport como mutação ou a ferramenta MCP refresh_channel_report apenas depois de o utilizador pedir novos dados do fornecedor. A recolha pode exigir permissão atual de estatísticas do fornecedor e consome o limite separado de atualizações. Pode devolver um estado em fila; consulte o mesmo ID de relatório e datas devolvidos com channelReport. As leituras normais nunca iniciam sessão, voltam a ligar contas nem iniciam automaticamente esta operação.

mutation CollectNewReport($channel: ID!, $start: String!, $end: String!) {
  refreshChannelReport(channelId: $channel, startDate: $start, endDate: $end) {
    id channelId state complete errorCode
  }
}
# Only run after an explicit request to collect new provider data.
# If queued, poll channelReport using the returned report ID and dates.

Incluir métricas guardadas nas leituras de publicações

Defina includeMetrics: true em post ou posts, ou as ferramentas MCP get_post e list_posts. Forneça metricSnapshots com ID de canal, ID de relatório e datas de início/fim correspondentes para cada canal. Ambos os valores posts:read e analytics:read são obrigatórios. Isto apenas lê instantâneos existentes; nunca contacta uma rede nem inicia a recolha de relatórios. Leia metricsState, metricsErrorCode, o estado/base de cada métrica e metricsUpdatedAt. As métricas em falta ou indisponíveis permanecem null. O histórico guardado pode estar desatualizado; mantenha os indicadores de desatualização e atualidade do relatório em vez de o tratar como recém-recolhido. Omita a opção nas leituras normais de publicações; aplicam-se os limites habituais de seleção e complexidade.

Na ferramenta MCP list_posts com includeMetrics: true, com a seleção predefinida completa e um instantâneo fixado, a omissão de first devolve atualmente no máximo 18 linhas com o limite padrão de complexidade de 1,000 pontos. Mais instantâneos podem reduzir esse valor predefinido. Um valor explícito de first nunca é reduzido silenciosamente: 19 linhas completas com um instantâneo excedem esse limite. Listas normais continuam a ter 20 por predefinição; selecionar menos campos pode permitir páginas maiores. Siga pageInfo.endCursor em vez de assumir que uma resposta contém todas as publicações. Este ajuste automático de página pertence à ferramenta específica; uma consulta GraphQL explícita tem de escolher um tamanho de página compatível com a seleção.

query SavedPostMetrics($id: ID!, $pins: [PostMetricSnapshotInput!]!) {
  post(id: $id, includeMetrics: true, metricSnapshots: $pins) {
    id metricsState metricsErrorCode metricsUpdatedAt
    metrics { name value unit status basis comparisonBasis }
  }
}
# pins: [{channelId: YOUR_CHANNEL_ID, reportId: EXISTING_REPORT_ID,
#         startDate: MATCHING_START_DATE, endDate: MATCHING_END_DATE}]
# Supply these as JSON variables, using the snapshot's actual IDs and dates.

Contar registos locais de publicação

publishingActivity conta registos automáticos de publicações conservados pela data de criação original no fuso horário escolhido. Cada destino e entrada de fio conta separadamente. As contagens agregadas incluem registos eliminados logicamente, excluem rascunhos e lembretes manuais e não recuperam registos purgados nem histórico exclusivo do fornecedor. Rascunhos nativos podem conservar datas de criação mais antigas após a submissão. Não são datas históricas exatas de submissão ou publicação; currentlyDelivered descreve o estado atual entre estes registos. Mantenha visíveis a base e a nota devolvidas.

recordedCommitEvents conta separadamente as tentativas nativas conservadas pela data registada de confirmação do fornecedor, independentemente das datas de criação originais. Uma republicação intencional conta novamente. A aceitação pode anteceder processamento ou entrega, pelo que não são totais de entregas. Mantenha commitEventBasis, commitEventCountUnit, commitEventNote e o indicador false commitEventHistoryComplete visível.

query {
  publishingActivity(startDate: "2026-09-01", endDate: "2026-09-30",
    timezone: "America/New_York") {
    count currentlyDelivered complete basis countUnit note
    recordedCommitEvents commitEventBasis commitEventCountUnit
    commitEventHistoryComplete commitEventNote
    channels { channelId service coverage count }
  }
}

Contar horas de publicação conhecidas e registadas

publishedActivity conta registos de destino conservados atualmente entregues cuja hora nativa elegível de entrega registada cai no intervalo de calendário e fuso horário pedidos. Usa as mesmas regras de data/hora do campo anulável post.publishedAt; datas de criação, edição, agendamento e confirmação nunca as substituem. Cada registo de destino de rede/fio conta separadamente, incluindo registos eliminados logicamente nas contagens agregadas. Mantenha rangeStartUtc, rangeEndUtcExclusive, basis, countUnit e complete: false. unknownTimeExcluded conta todos os registos entregues selecionados e conservados com hora desconhecida, não publicações desconhecidas atribuídas a este mês. Histórico purgado, substituído e exclusivo do fornecedor fica fora deste subconjunto de horas conhecidas.

query {
  publishedActivity(startDate: "2026-09-01", endDate: "2026-09-30",
    timezone: "America/New_York") {
    count unknownTimeExcluded complete includesSoftDeleted
    rangeStartUtc rangeEndUtcExclusive basis countUnit unknownTimeExcludedBasis note
    channels { channelId service count unknownTimeExcluded coverage }
  }
}

Use a ferramenta MCP get_published_activity, Node publishedActivity ou CLI tools call get_published_activity. Lê registos locais sem recolha junto do fornecedor. A contagem por coorte de criação original publishingActivity e a contagem baseada em confirmação recordedCommitEvents mantêm significados distintos.

Ordenar o desempenho observado

rankedPosts exige uma métrica explícita e uma das opções lifetime ou period_total como base. Valores desconhecidos e bases incompatíveis são excluídos; zero continua a ser uma pontuação real. A cobertura por rede distingue fontes completas, parciais, em fila e indisponíveis. Reutilize IDs de relatório para comparações estáveis. Cada resultado identifica a unidade da métrica; taxas de interação usam unidades percentuais e preservam a base de comparação. Fórmulas conhecidas diferentes de taxas não são classificadas em conjunto, e taxas nunca são somadas. O alcance único LinkedIn não é somado entre publicações. As reações Gosto do Facebook são separadas das reações totais quando o fornecedor as devolve; valores em falta permanecem null. O desempenho não prova que o texto causou o resultado.

query {
  rankedPosts(startDate: "2026-09-01", endDate: "2026-09-30",
    metric: "reactions", metricBasis: "lifetime", first: 10) {
    state complete metric metricBasis note
    posts { channelId externalId text publishedAt publicationDate publicationTimeBasis value }
    channels { channelId service reportId coverage basis note enumerationComplete missingMetricPosts }
  }
}

As ferramentas MCP específicas são get_publishing_activity e rank_posts. Os métodos do SDK são publishingActivity e rankPosts.

Ligue com OAuth.

Registe na consola um cliente PKCE público ou uma aplicação confidencial de servidor. Registe URLs de retorno exatos, escolha âmbitos e forneça o URL de privacidade da aplicação. Cada cliente escolhe os seus canais e pode desligar a aplicação.

1. Gere um verificador aleatório e o respetivo desafio S256. Guarde um valor state aleatório para verificar o retorno.
2. Abra /api/developer/oauth/authorize com ID de cliente, URI de redirecionamento registado, âmbitos, state, challenge, code_challenge_method=S256 e o recurso pedido.
3. Troque o código devolvido em /api/developer/oauth/token, incluindo o verificador e o recurso originais. Os clientes confidenciais também se autenticam com o seu segredo.
4. Guarde as credenciais em segurança. Os tokens de acesso duram uma hora; os tokens de atualização são renovados e expiram após 30 dias. Nunca reutilize um token de atualização substituído.

Os recursos são https://backend.socialblaze.ai/api/developer ou o respetivo /graphql ou /mcp como endpoint. Os tokens existentes de conectores de IA usam um destinatário diferente.

Tenha a sua conta ao alcance.

Use uma ligação MCP remota personalizada num assistente ou cliente de programador compatível. O endpoint é https://backend.socialblaze.ai/api/developer/mcp. Use autenticação OAuth quando o cliente a suporta; esse fluxo não exige chave de programador. Use uma chave de programador com âmbitos limitados apenas em clientes que suportem autenticação Bearer segura.

{
  "mcpServers": {
    "socialblaze": {
      "url": "https://backend.socialblaze.ai/api/developer/mcp",
      "headers": {"Authorization": "Bearer YOUR_DEVELOPER_KEY"}
    }
  }
}

A sintaxe de configuração varia conforme o cliente. As ferramentas são filtradas pelos âmbitos concedidos. As disponíveis abrangem leitura de conta/canais, rascunhos, publicação, fios, revisão, modelos e relatórios. Os recursos de esquema e as ferramentas GraphQL genéricas usam as mesmas permissões e quotas. A presença nesta lista não implica um conector publicado num marketplace.

Estes exemplos usam o endpoint MCP de programador e o catálogo atual de ferramentas com âmbitos limitados. Uma ligação interativa de publicação SocialBlaze pode expor outro conjunto de ferramentas e contas. Se faltar uma ferramenta, verifique a ligação e as permissões usadas; uma ligação de publicação não implica acesso a relatórios.

Estruturas genéricas de pedidos e resultados MCP

Num cliente MCP inicializado, passe o objeto apresentado {name, arguments} como objeto, sob tools/call como parâmetros. execute_query exige um resumo fiel em summary (no máximo 500 caracteres) e query; execute_mutation exige summary e mutation. As variáveis e o nome da operação são opcionais. A consulta de conta exige accounts:read; criar um rascunho exige drafts:write.

{
  "name": "execute_query",
  "arguments": {
    "summary": "Read the connected account identifier.",
    "query": "query ConnectedAccount { account { id } }",
    "operationName": "ConnectedAccount"
  }
}

{
  "name": "execute_mutation",
  "arguments": {
    "summary": "Save an unpublished text draft.",
    "mutation": "mutation SaveDraft($key: String!) { createDraft(requestKey: $key, text: \"Draft for review\") { postId version published } }",
    "variables": {
      "key": "my-draft-001"
    },
    "operationName": "SaveDraft"
  }
}

Os resultados de chamadas MCP podem definir isError e expõem structuredContent.error ou detalhes de validação; uma resposta GraphQL também pode conter errors ou um valor tipado de MutationError. O JSON-RPC em bruto contém o resultado da ferramenta em result e pode ter, no nível superior, error. Inspecione também o conteúdo devolvido: HTTP 200, por si só, não significa sucesso.

Editar um rascunho existente e depois lê-lo

Leia primeiro o ID e a versão atuais do rascunho. Substitua os marcadores do exemplo por valores reais devolvidos por get_post ; não submeta os marcadores sem os substituir. A edição de um rascunho próprio usa edit_post com draft: true, texto explícito, uma chave de pedido estável e drafts:write. Omita saveToDraft, mode e dueAt para esta edição de rascunho. Devolve postId e version. Em contrapartida, o editor de publicações com agendamento futuro devolve id, version e deleted. Selecione apenas campos dessa operação; obtenha texto e recursos separadamente através de get_post com posts:read.

{
  "name": "edit_post",
  "arguments": {
    "postId": "YOUR_DRAFT_ID",
    "version": "CURRENT_64_CHARACTER_VERSION",
    "requestKey": "my-draft-edit-001",
    "draft": true,
    "text": "Updated draft caption",
    "fields": "postId,version"
  }
}

{
  "name": "get_post",
  "arguments": {
    "postId": "YOUR_DRAFT_ID",
    "fields": "id,version,text,isDraft,assets.{type,url,altText}"
  }
}

Substituir multimédia num rascunho guardado

Para um rascunho pertencente à integração, ainda não submetido nem agendado, omita draft e defina saveToDraft: true. Forneça o ID/versão atual, uma chave de pedido estável, drafts:write e a multimédia de substituição; omita mode e dueAt. Não combine draft: true com saveToDraft: true. Esta operação do editor de publicações devolve id, version e deleted, não postId. O exemplo de PDF do LinkedIn substitui a lista de anexos por um documento. Substitua todos os marcadores, incluindo URL/título, e preserve a legenda pretendida. Leia novamente a publicação para confirmar os recursos e o estado de rascunho. Esta edição não submete, agenda nem publica o rascunho.

{
  "name": "edit_post",
  "arguments": {
    "postId": "YOUR_OWNED_DRAFT_ID",
    "version": "CURRENT_64_CHARACTER_VERSION",
    "requestKey": "my-draft-media-edit-001",
    "saveToDraft": true,
    "text": "Current draft caption",
    "document": {
      "url": "https://YOUR_MEDIA_HOST/your-document.pdf",
      "title": "Your document title"
    },
    "fields": "id,version,deleted"
  }
}

n8n

Adicione um passo MCP Client, escolha HTTP Streamable e use https://backend.socialblaze.ai/api/developer/mcp. Selecione Bearer Auth e guarde a chave com âmbitos limitados numa credencial do n8n. Escolha uma ferramenta e use dados JSON para parâmetros aninhados. Comece por get_account ou uma mutação de rascunho; mantenha a mesma chave de pedido ao repetir um evento.

Zapier

Nas ligações da aplicação, adicione MCP Client by Zapier. Introduza o endpoint acima, escolha Streamable HTTP e OAuth. Inicie sessão na SocialBlaze, reveja as permissões pedidas e selecione os canais. Use uma ferramenta só de leitura para relatórios ou Run Tool para uma ação autorizada de rascunho. Ative o tratamento de erros e inspecione os dados estruturados devolvidos antes de iniciar outro passo.

Alguns editores MCP Client do Zapier enviam texto de arrays como cadeias de caracteres. channelIds exige um array real. Se o editor o converter em texto, use execute_mutation com uma cadeia de mutação GraphQL que contenha o literal channelIds: ["YOUR_CHANNEL_ID"]. Comece com um agendamento futuro, mantenha a chave de pedido e inspecione os erros antes de continuar.

Usam os clientes MCP genéricos das plataformas. A disponibilidade de contas dos clientes e as taxas dos fornecedores são separadas dos limites da API SocialBlaze.

Limites com que pode planear.

As janelas UTC são partilhadas por todas as chaves e aplicações autorizadas. Mais chaves não multiplicam os limites. Apenas a operação selecionada e os fragmentos alcançáveis são contabilizados: uma unidade por 25 pontos de complexidade, arredondada por excesso, com mínimo de uma, mais duas para mutações. Cabeçalhos de resposta e metadados MCP indicam as unidades de trabalho cobradas e a base do custo. É uma política inicial conservadora; atualizações de fornecedores e multimédia mantêm limites separados. Leituras em cache continuam a consumir trabalho local de consulta. Publicações no site e limites das redes/fornecedores são separados.

• 401: credencial expirada, revogada ou inválida.
• 403: âmbito em falta, acesso ao canal ou permissão da equipa.
• 409: versão desatualizada, dados alterados numa repetição ou estado de publicação inseguro.
• 422: inspecione os detalhes de validação, incluindo channels.ID.
• 429: siga Retry-After; reutilize a mesma chave de mutação.

O GraphQL pode devolver erros com HTTP 200. Inspecione sempre errors. Cada mutação também tem uma variante try , como tryCreateDraft, com um resultado de sucesso tipado em result ou MutationError. Selecione __typename e o campo do erro code, httpStatus, message, fields e retryAfterSeconds. Um erro tipado pode aparecer em data com HTTP 200, por isso verifique também esse resultado.

Os chamadores MCP também têm de inspecionar isError e structuredContent: os erros podem aparecer como erros GraphQL em errors, um erro tipado MutationError, error ou validation mesmo quando o pedido de transporte é bem-sucedido. Quando disponível, _meta inclui httpStatus, chargedWorkUnits, os limites restantes e retryAfterSeconds. Um cliente que oculta metadados não prova que uma chamada foi gratuita. Resolva erros de permissão ou validação antes de repetir. Se uma escrita tiver resultado incerto, mantenha a chave original e os mesmos dados; leia o estado guardado em vez de criar outra publicação.

São limites de pré-visualização, não uma promessa de que um fornecedor permite o mesmo volume.

Comece com um fluxo pequeno.

Importar um fluxo de trabalho n8n

Transfira um fluxo de trabalho, escolha Import from File no n8n, edite os dados de entrada e associe a sua credencial Bearer Auth ao passo MCP Client. Cada fluxo começa com um acionador manual e permanece inativo após a importação. As chaves pertencem às credenciais do n8n, nunca ao JSON.

• De evento a rascunho / ID de evento estável para repetições; nunca publica.
• Atividade local de publicação / datas originais de criação dos registos, com limites de contagem explícitos.
• Classificação de publicações observadas / métrica e base escolhidas, com cobertura e referências fixadas de relatórios.

Importado com n8n 2.43.5; chamadas do nó MCP verificadas numa API de teste isolada. A execução alojada com as suas credenciais exige uma verificação separada. Estes fluxos usam clientes MCP genéricos e não implicam uma aplicação publicada num marketplace nem um modelo Zapier publicado. Mantenha a autorização para mensagens externas no seu próprio fluxo.

Leia o esquema atual.

A referência é gerada a partir dos tipos GraphQL implementados. A introspeção autenticada e o explorador fornecem o contrato implementado. A SocialBlaze usa identificadores e esquema próprios.

Forneça ao seu assistente de programação o Guia da API legível por IA para que possa usar os endpoints, permissões, versões e regras de repetição corretos.

Cliente Node no servidor

O pacote versionado inclui declarações TypeScript e um cliente de linha de comandos. Instale o ficheiro transferido com npm install ./socialblaze-developer-client-0.1.14.tgz. Guarde a chave numa variável de ambiente do servidor.

Use os comandos específicos de publicações e rascunhos, tools list, tools describe NAME, tools call NAME, schema describe TYPE e doctor. Forneça JSON diretamente, a partir de um ficheiro ou de stdin. --dry-run verifica regras básicas de entrada anunciadas sem chamar a ferramenta; a descoberta continua a usar quota e não confirma validação do fornecedor nem entrega. A CLI nunca repete escritas automaticamente.

As leituras de publicações suportam postTypes e dueAtPresence para filtrar formatos nativos guardados e a presença de data agendada. Reinicie o cursor ao alterar filtros. Estes filtros não ativam formatos adicionais de publicação.

A ferramenta list_channels suporta páginas de 1–100, com 20 por predefinição, com afterId. Selecione menos campos para páginas maiores; aplicam-se os limites normais de complexidade e trabalho. Os filtros de formato também incluem o formato Google Business event, offer e whats_new, com base nos metadados nativos guardados. Estes sobrepõem-se intencionalmente ao grupo de publicações normal e não ativam novos formatos de publicação.

Node getPost e contentItem devolvem URLs de recursos, incluindo pré-visualizações estáticas e animadas. Node listPosts mantém a projeção compacta sem recursos; use uma leitura individual ou seleção GraphQL explícita. Node getPost inclui isDraft mas mantém uma projeção compacta sem estado do método de publicação ou lembrete manual. Use a ferramenta get_post ou uma consulta GraphQL explícita desses campos; o cliente genérico e a CLI podem executar as novas operações de rascunho sem alterar o pacote imutável do SDK.

Selecionar campos da resposta

As chamadas específicas da CLI aceitam --fields 'id,text' e grupos relacionados, como --fields 'nodes.{id,text},pageInfo.endCursor'. Os caminhos são relativos ao resultado indicado. O servidor constrói uma seleção GraphQL mais pequena e valida-a antes de executar. O custo reflete essa seleção. Mantenha IDs e versões ao acompanhar escritas e preserve a base, as notas e a cobertura dos relatórios. all repõe a seleção padrão da ferramenta, não todos os campos do esquema. As ferramentas MCP específicas aceitam a mesma opção fields como cadeia de caracteres. Os metadados de paginação de canais continuam disponíveis quando os campos apresentados omitem IDs. Comandos genéricos de consulta usam o documento explícito.

Configuração da CLI e orientações para agentes

socialblaze init grava predefinições locais; config path e config get --all permitem inspecioná-las. Recomendam-se credenciais de ambiente. Apenas a opção explícita init --save-token guarda um token num ficheiro global não encriptado fora do projeto atual. A configuração do repositório suporta apenas fuso horário e tempo limite; não pode fornecer credenciais nem redirecionar a origem. A saída de configuração oculta as chaves guardadas; a remoção local não revoga a chave no servidor.

context --list lista os tópicos de agente incluídos; context imprime offline a competência e as orientações de relatórios. completion bash, zsh, fish ou powershell imprime um script de conclusão automática da shell. Use socialblaze install claude ou install codex para uma instalação explícita offline da competência gerida; uninstall claude ou uninstall codex reverte uma instalação sem alterações. Pastas personalizadas ou ligadas são preservadas. A instalação do pacote e init não instalam competências nem alteram perfis da shell. As sugestões abrangem grupos estáticos de comandos. A versão 0.1.5 corrige a conclusão automática aninhada do zsh. As sugestões estáticas são verificadas em ambientes reais offline bash, zsh ZLE e fish; a saída PowerShell é verificada pelo analisador. Estas verificações não exercitam ferramentas remotas nem autorizam publicação.

Ler a competência de agente incluída. Preserva a autorização e distingue contagens de registos locais, classificações observadas e histórico incompleto do fornecedor. Leia a referência de relatórios associada para esses fluxos.

Precisa de ajuda com um pedido específico? Envie email para [email protected] com o nome da operação, estado e código de erro seguro. Nunca inclua a chave, token de atualização ou credenciais de redes sociais.