Cookbook

Três receitas por tarefa que você pode copiar e executar hoje, sem precisar abrir o SociaHive. Cada uma é uma automação real, montada pelo mesmo conjunto de ferramentas MCP que um assistente de IA ou um script chama: responder comentários do Instagram com um direct, agendar uma semana de posts em lote a partir de um CSV pela API REST ou pela CLI, e trazer um resumo diário de desempenho para a conversa com o seu assistente de IA. Escolha abaixo a que combina com o seu trabalho.

Responder comentários do Instagram que mencionam “preço”

Perfil: usuário de IA (Claude.ai, Claude Desktop, Cursor) Tempo: 2 minutos Código: nenhum, só um prompt via MCP

O que você vai montar: um fluxo de automação do SociaHive que envia um direct para quem comentar “preço”, “valor” ou “quanto custa” nos seus posts do Instagram. Você faz isso conversando com o seu assistente de IA, sem clicar no SociaHive.

Pré-requisitos: um cliente MCP conectado ao SociaHive. Veja o guia de configuração do MCP.

O prompt:

Usando o SociaHive, crie um fluxo de resposta automática a comentários do Instagram:

1. Gatilho em comentários que contenham “preço”, “valor” ou “quanto custa”
2. Responda em público com “Estou enviando no seu direct agora! 📩”
3. Envie ao autor do comentário um direct com o nosso link de preços: https://example.com/pricing
4. Ative o fluxo quando terminar

Use a minha primeira conta do Instagram. Mostre o fluxo final antes de ativar.

O que a IA faz por baixo dos panos:

1. list_accounts                  → encontra a sua conta do Instagram
2. generate_flow (0 crédito de IA)   → a IA monta o grafo inteiro do fluxo
3. get_flow                       → mostra o resultado para você
4. activate_flow                  → depois que você confirma

Variações:

Custo: 0 crédito de IA para criar: o generate_flow é IA de criação e é grátis em todos os planos. As mensagens prontas que a automação envia não custam nada. Só a IA que responde ao seu público gasta créditos: as respostas por IA custam 5 créditos cada.

Agendar uma semana de posts a partir de um CSV

Perfil: desenvolvedor Tempo: 5 minutos Código: Python + Node

Pré-requisitos: uma chave de API do SociaHive (veja o guia rápido para desenvolvedores) e o SDK de Python ou de Node instalado.

Formato do CSV:

text,platform,scheduled_at,image_url
"Monday motivation 💪",instagram,2026-06-01T09:00:00Z,https://cdn.example.com/mon.jpg
"Tuesday tip: keep it short",twitter,2026-06-02T09:00:00Z,
"Wednesday wisdom",linkedin,2026-06-03T09:00:00Z,

import csv
import os
import sys
from sociahive import SociaHive
 
sh = SociaHive(api_key=os.environ["SOCIAHIVE_API_KEY"])
 
with open(sys.argv[1]) as f:
    rows = list(csv.DictReader(f))
 
account_cache = {}
for platform in {r["platform"] for r in rows}:
    accounts = sh.accounts.list(platform=platform).get("data", [])
    if not accounts:
        sys.exit(f"No connected account for {platform}")
    account_cache[platform] = accounts[0]["id"]
 
payloads = [{
    "text": r["text"],
    "platforms": [{"platform": r["platform"], "account_id": account_cache[r["platform"]]}],
    "schedule_type": "scheduled",
    "scheduled_at": r["scheduled_at"],
    "timezone": "UTC",
    **({"media": [{"type": "image", "url": r["image_url"]}]} if r["image_url"] else {}),
} for r in rows]
 
# Use bulk endpoint when >10 posts; otherwise loop
if len(payloads) > 10:
    result = sh.posts.bulk(payloads)
    for post in result["data"]:
        print(f'scheduled {post["id"]} on {post["platforms"][0]["platform"]}')
else:
    for p in payloads:
        post = sh.posts.create(**p)
        print(f'scheduled {post["id"]} on {p["platforms"][0]["platform"]}')

CLI de uma só vez (sem escrever script):

sociahive posts create \
  --text "Monday motivation 💪" \
  --platforms '[{"platform":"instagram","account_id":"…"}]' \
  --schedule-type scheduled \
  --scheduled-at "2026-06-01T09:00:00Z" \
  --media '[{"type":"image","url":"https://cdn.example.com/mon.jpg"}]'

cURL, uma chamada só:

curl -X POST https://www.sociahive.com/api/v1/posts \
  -H "X-API-Key: $SOCIAHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Monday motivation 💪",
    "platforms": [{"platform":"instagram","account_id":"…"}],
    "schedule_type": "scheduled",
    "scheduled_at": "2026-06-01T09:00:00Z"
  }'

Dicas para erros:

• 413 em /posts/bulk: o limite do lote é de 100 linhas; divida o seu CSV em partes.
• 400 platform_user_id required: a busca do ID da conta achou a conta errada; envie platform_user_id explicitamente.
• 429: o padrão é 1.000 requisições por hora por chave; guarde os IDs das contas e use o endpoint em lote.

Conferir: sociahive posts list --status scheduled --limit 20.

Custo: 0 crédito de IA.

Enviar mídia e postar um slideshow no TikTok

A mídia precisa estar no nosso armazenamento antes de um post poder usá-la. Sua chave precisa de uploads:write e posts:write.

Pela CLI (arquivos locais):

sociahive upload slide-1.jpg slide-2.jpg slide-3.jpg
# [{ "file": "slide-1.jpg", "url": "https://.../uploads/...jpg", "key": "uploads/...", "size_bytes": 182311 }, ...]
 
# Or upload and create in one go (repeat --media-file per file):
sociahive posts create --text "3 mistakes new founders make" \
  --platforms '[{"platform":"tiktok"}]' --scheduled-at "tomorrow 9am" \
  --media-file slide-1.jpg --media-file slide-2.jpg --media-file slide-3.jpg

O sociahive upload sai com código diferente de zero quando algum arquivo falha e mostra o motivo de cada arquivo. Formatos aceitos: JPEG, PNG, WebP, MP4 e MOV, até o tamanho de upload do seu plano.

Pela API REST, cada arquivo exige três chamadas:

1. POST /api/v1/uploads/presign com { filename, mime_type, size_bytes }.
2. Envie os bytes com PUT para upload_url, com todos os cabeçalhos de required_headers, exatamente como foram devolvidos (hoje Content-Type, Content-Length e Content-Disposition). Cada um faz parte da assinatura da URL: se você omitir um ou mudar algum, o armazenamento responde 403.
3. POST /api/v1/uploads/verify com { key }. O public_url da resposta é a URL para usar como mídia do post.

Pelo Claude.ai ou pelo ChatGPT (sem bytes de arquivo): a ferramenta upload_media_from_url, ou POST /api/v1/uploads/from-url com { url }, copia uma imagem ou um vídeo públicos para os seus uploads e devolve { url, key, size_bytes, mime_type }. O tipo é lido do próprio arquivo, e os arquivos têm limite de 100 MB (para arquivos maiores, use o upload com presign acima). Quando o site não entrega o arquivo, a resposta é 422: upstream_refused (o site respondeu com um erro; o status HTTP dele está em details.reason), upstream_timeout ou upstream_unreachable. Escolha outra URL ou baixe o arquivo e use o upload com presign.

No ChatGPT, uma imagem que o ChatGPT gera, ou uma foto que você adiciona à conversa, entra sem URL: o ChatGPT passa o arquivo para upload_media_from_url como file (a ferramenta declara _meta["openai/fileParams"]), e o SociaHive o copia na hora. Peça “faça uma imagem da nossa vela nova e agende para o Instagram amanhã às 9” e o ChatGPT cria a imagem, importa e agenda o post.

POST /api/v1/posts com schedule_type: "scheduled" e um scheduled_at no futuro agenda o post na mesma chamada.

Resumo diário de desempenho com o Claude

Perfil: usuário avançado / operador de agência Tempo: 2 minutos Código: nenhum, só um prompt via MCP

O que você recebe: um resumo matinal de uma tela: quais fluxos ficaram abaixo do esperado, quais posts superaram o esperado, o que está na fila para hoje e onde é preciso prestar atenção. Sem cliques, sem SQL, sem caçar dados no painel.

Pré-requisitos: um cliente MCP conectado ao SociaHive. Veja o guia de configuração do MCP.

O prompt:

Faça um resumo do desempenho de ontem no SociaHive. Etapas:

1. Liste meus fluxos com as métricas das últimas 24 horas.
2. Busque a visão geral das métricas do mesmo período em todas as plataformas.
3. Liste tudo o que está agendado para publicar hoje.
4. Entregue um resumo de 6 linhas:
   • Fluxo de melhor desempenho (por conclusões) e por quê
   • Fluxo de pior desempenho (por taxa de erro) e o que investigar
   • Melhor post (por engajamento) e o que ele tinha em comum com os outros
   • Alcance / impressões totais nas plataformas em comparação com o dia anterior
   • Tudo o que está na fila para hoje e que devo revisar antes de sair
   • Uma ação concreta que você recomendaria

Seja conciso: menos de 200 palavras no total. Não altere nada.

O que a IA faz por baixo dos panos:

1. list_flows_with_stats     → desempenho dos fluxos + contagem de erros
2. get_analytics_overview    → impressões / engajamento entre plataformas
3. list_scheduled_posts      → a fila de hoje

As três são ferramentas só de leitura: sem risco de mudanças acidentais e sem pedidos de confirmação.

Variações:

Custo:

• 0 crédito de IA do SociaHive: as três ferramentas são endpoints de métricas só de leitura e não são medidos.
• O que o seu assistente de IA cobrar pelos próprios tokens (geralmente centavos por execução com o Claude Haiku ou o GPT-4o-mini).

Por que isso vence o painel:

O painel mostra os dados. A IA diz o que fazer com eles, que é o que você queria quando abriu o painel às 9h.

Perguntas frequentes

Preciso escrever código em alguma dessas receitas? As receitas 1 e 3 são só prompts: você escreve uma frase para o seu assistente de IA e ele chama as ferramentas MCP por você. A receita 2 (importação por CSV) tem um exemplo em Python e outro em Node, mas os exemplos da CLI e do cURL nessa seção funcionam sem escrever nenhum código.

Dá para usar essas receitas com o ChatGPT em vez do Claude? Dá. Todas as receitas usam o servidor MCP público do SociaHive, que qualquer agente compatível com MCP pode chamar: Claude Desktop, Claude Code, conectores do ChatGPT ou Cursor. Veja o guia de configuração do MCP para os passos de conexão de cada cliente.

O que acontece se uma etapa falhar no meio do caminho? As leituras (list_accounts, get_flow, list_flows_with_stats) sempre podem ser repetidas com segurança. As escritas irreversíveis, como publicar um post na hora ou excluir um fluxo, devolvem um token de confirmação de curta duração na primeira chamada e só executam em uma segunda confirmação explícita; nada destrutivo dispara em uma chamada só. Para a receita do CSV em especial, veja as dicas de erro acima sobre as falhas comuns 413 e 429 e como se recuperar.

Quanto custam essas receitas? As receitas 1 e 3 custam 0 crédito de IA: a geração de fluxos e as ferramentas de métricas só de leitura são IA de criação gratuita, sem medição. A receita 2 não chama IA; são chamadas diretas à REST/CLI, então não custa nada além do uso de tokens do seu próprio assistente de IA (se você usa a CLI por meio dele).

O que ler depois

• Padrões de fluxo: os sete formatos que a maioria dos fluxos do SociaHive adota, para você descrever o que quer montar.
• Guia rápido para desenvolvedores: referência de REST, SDKs e CLI se você quer integrar o SociaHive a um aplicativo maior.
• Guia de configuração do MCP: a integração com assistentes de IA que libera as receitas 1 e 3.