Postproxy

Publique em várias redes sociais com apenas um MCP

Documentação

Servidor MCP Postproxy

Servidor MCP (Model Context Protocol) para integrar a API do Postproxy com o Claude Code. Este servidor fornece ferramentas para publicar posts, verificar status e gerenciar perfis de redes sociais através do Claude Code.

Instalação

Instalação Global

npm install -g postproxy-mcp

Instalação Local

npm install postproxy-mcp

O Claude Code armazena a configuração do servidor MCP em ~/.claude/plugins/. Após instalar o postproxy-mcp, o Claude detectará automaticamente o servidor na reinicialização.

Configuração

Registrar Servidor MCP

Após instalar o postproxy-mcp, registre-o no Claude Code usando o comando claude mcp add:

claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api -- postproxy-mcp

Substitua your-api-key pela sua chave real da API Postproxy.

A configuração será salva automaticamente em ~/.claude/plugins/. Após executar este comando:

Reinicie sua sessão do Claude Code
Teste a conexão perguntando ao Claude: "Verifique meu status de autenticação do Postproxy"
Se as ferramentas estiverem disponíveis, o Claude poderá usá-las automaticamente

Alternativa: Configuração Interativa

Para usuários não técnicos, você pode usar o comando de configuração interativa:

postproxy-mcp setup

postproxy-mcp-setup

Isso guiará você pelo processo de configuração passo a passo e registrará o servidor usando claude mcp add automaticamente.

Ferramentas Disponíveis

Ferramentas de Autenticação

`auth_status`

Verifica o status de autenticação, configuração da API e informações do workspace.

Parâmetros: Nenhum

Retorna:

{
  "authenticated": true,
  "base_url": "https://api.postproxy.dev/api",
  "profile_groups_count": 2
}

Visão Geral da Conta

`summary_get`

Responda "qual é o status?" em uma única chamada — um instantâneo de atividade para um intervalo de tempo em vez de idas e voltas separadas de history_list / comments_list / dm_chats_list.

Parâmetros:

window (string, opcional): 24h (padrão), 7d ou 30d
from (string, opcional): Timestamp ISO 8601 ou data simples iniciando um intervalo explícito. Substitui window, e as contagens de *_previous retornam null
to (string, opcional): Fim do intervalo explícito. Padrão é agora quando apenas from é fornecido
profile_group_id (string, opcional): Relatório sobre um único grupo. Omita para cobrir todos os grupos que a chave pode acessar

Retorna:

{
  "window": {
    "label": "24h",
    "from": "2026-08-17T09:00:00Z",
    "to": "2026-08-18T09:00:00Z",
    "previous_from": "2026-08-16T09:00:00Z",
    "backlog_from": "2026-07-19T09:00:00Z"
  },
  "posts": {
    "published": 4,
    "published_previous": 3,
    "failed": 1,
    "scheduled_ahead": 6,
    "next_scheduled_at": "2026-08-18T14:00:00Z",
    "by_platform": { "instagram": { "published": 4, "failed": 0 } }
  },
  "engagement": {
    "total": { "impressions": 48210, "likes": 1204 },
    "by_platform": { "instagram": { "impressions": 31002, "likes": 900 } },
    "posts_with_insights": 14
  },
  "comments": { "received": 96, "received_previous": 71, "awaiting_reply": 12, "by_platform": { "instagram": 61 } },
  "reviews": { "received": 7, "received_previous": 4, "awaiting_reply": 3 },
  "dms": { "inbound": 41, "outbound": 33, "chats_awaiting_reply": 5, "reply_window_closing": 2 },
  "api": { "calls": 812, "calls_previous": 640 }
}

Notas:

Contagens de posts são posts, então um post enviado para três redes conta uma vez e um tópico conta uma vez. by_platform conta entregas por rede, então um tópico X com 3 itens é 3 em twitter.
engagement é vitalício até a data para posts publicados no intervalo, não engajamento obtido durante ele — soma o instantâneo de estatísticas mais recente de cada post. Um post publicado há minutos pode não ter instantâneo ainda e não estará em posts_with_insights. As chaves são as métricas normalizadas listadas em Campos de Estatísticas por Plataforma.
As contagens de awaiting_reply descrevem o estado atual, não o intervalo — elas não mudam quando você altera window. Elas olham 30 dias para trás, retornadas como window.backlog_from. Um comentário conta como respondido apenas quando a resposta veio de você (via Postproxy ou do próprio perfil); chats_awaiting_reply é derivado dos timestamps das mensagens, já que o Postproxy não tem estado de lida/não lida.
reply_window_closing conta conversas com menos de 6 horas restantes da janela de mensagens de 24h. Redes sem janela (Telegram, Bluesky) são excluídas.
engagement é null quando os insights estão desativados para a conta; dms é null quando DMs estão desativados.
Escopo como todas as outras ferramentas: uma chave com escopo de grupo relata apenas seu grupo.

Gerenciamento de Perfis

`profile_groups_list`

Lista todos os grupos de perfis acessíveis com sua chave de API. Grupos de perfis são contêineres organizacionais (ex.: por marca ou cliente) que contêm perfis relacionados. Use o id de um grupo para filtrar profiles_list por profile_group_id.

Parâmetros: Nenhum

Retorna:

{
  "profile_groups": [
    {
      "id": "grp123abc",
      "name": "Main Brand",
      "profiles_count": 4
    }
  ]
}

`profiles_list`

Lista todos os perfis de redes sociais disponíveis para publicação.

Parâmetros:

profile_group_id (string, opcional): Se fornecido, apenas perfis neste grupo são retornados (use profile_groups_list para encontrar IDs de grupos)

Retorna:

{
  "profiles": [
    {
      "id": "profile-123",
      "name": "My Twitter Account",
      "platform": "twitter",
      "profile_group_id": "group-abc"
    }
  ]
}

`profiles_placements`

Lista posicionamentos disponíveis para um perfil. Para perfis do Facebook, posicionamentos são páginas de negócios. Para perfis do LinkedIn, posicionamentos incluem o perfil pessoal e organizações. Para perfis do Pinterest, posicionamentos são quadros. Para perfis do Telegram, posicionamentos são canais onde o bot pode publicar. Para perfis do Google Business, posicionamentos são locais, retornados como caminhos de recursos completos (accounts/X/locations/Y) para passar como location_id. Para perfis do WhatsApp, posicionamentos são os números de telefone na Conta Comercial — o id do posicionamento é o phone_number_id que toda ferramenta whatsapp_* e dm_chat_create aceita. Disponível para perfis facebook, linkedin, pinterest, telegram, google_business e whatsapp.

Parâmetros:

profile_id (string, obrigatório): Hashid do perfil

Retorna (exemplo LinkedIn):

{
  "placements": [
    {
      "id": null,
      "name": "Personal Profile"
    },
    {
      "id": "108520199",
      "name": "Acme Marketing"
    }
  ]
}

Notas:

Se nenhum posicionamento for especificado ao criar um post:
- LinkedIn: padrão é o perfil pessoal
- Facebook: padrão é uma página conectada aleatória (se apenas uma página estiver conectada, não é necessário definir um ID de posicionamento)
- Pinterest: falha
- Telegram: falha — chat_id é obrigatório em todo post
- Google Business: falha — location_id é obrigatório em todo post e em toda ferramenta google_business_*

`profiles_stats`

Obtém a série temporal de seguidores/engajamento para um perfil. Instantâneos são capturados aproximadamente a cada 23 horas, então você pode plotar crescimento de seguidores e outras tendências ao longo do tempo. Os campos stats são nativos da plataforma (não normalizados) — veja Campos de Estatísticas por Plataforma na seção post_stats para formato e chaves adicionais de nível de perfil (followers_count, followersCount, etc.) por rede.

Parâmetros:

profile_id (string, obrigatório): Hashid do perfil
placement_id (string, condicional): Obrigatório para perfis facebook, linkedin, telegram e google_business. Obtenha de profiles_placements. Omita para instagram, threads, youtube, twitter, tiktok, pinterest e bluesky.
from (string, opcional): Timestamp ISO 8601 — incluir apenas instantâneos registrados neste horário ou depois
to (string, opcional): Timestamp ISO 8601 — incluir apenas instantâneos registrados neste horário ou antes

Retorna (exemplo LinkedIn):

{
  "data": {
    "profile_id": "prof_li_001",
    "platform": "linkedin",
    "placement_id": "108520199",
    "records": [
      { "stats": { "followerCount": 4500, "shareCount": 8, "likeCount": 80 }, "recorded_at": "2026-05-09T08:00:00Z" },
      { "stats": { "followerCount": 4520, "shareCount": 9, "likeCount": 90 }, "recorded_at": "2026-05-10T08:00:00Z" }
    ]
  }
}

Para redes sem posicionamento (ex.: Bluesky), omita placement_id:

{
  "data": {
    "profile_id": "prof_bsky_001",
    "platform": "bluesky",
    "placement_id": null,
    "records": [
      { "stats": { "followersCount": 8800, "postsCount": 40 }, "recorded_at": "2026-05-09T08:00:00Z" }
    ]
  }
}

Gerenciamento de Posts

`post_publish`

Publica um post em perfis de redes sociais especificados.

Parâmetros:

content (string, obrigatório): Texto do conteúdo do post
profiles (string[], obrigatório): Matriz de IDs de perfis (hashids) ou nomes de plataformas (ex.: "linkedin", "instagram", "twitter"). Ao usar nomes de plataformas, publica no primeiro perfil conectado para essa plataforma.
schedule (string, opcional): Horário agendado ISO 8601
media (string[], opcional): Matriz de URLs de mídia ou caminhos de arquivos locais
idempotency_key (string, opcional): Chave de idempotência para deduplicação
require_confirmation (boolean, opcional): Se verdadeiro, retorna resumo sem publicar
draft (boolean, opcional): Se verdadeiro, cria um post rascunho que não será publicado automaticamente
queue_id (string, opcional): ID da fila para adicionar o post. A fila atribuirá automaticamente um horário. Não use junto com schedule.
queue_priority (string, opcional): Prioridade ao adicionar a uma fila: high, medium (padrão) ou low

platforms (objeto, opcional): Parâmetros específicos da plataforma. A chave é o nome da plataforma (ex.: "instagram", "youtube", "tiktok"), o valor é um objeto com opções específicas da plataforma. Veja Referência de Parâmetros da Plataforma para documentação completa.

Exemplo:

{
  "instagram": {
    "format": "reel",
    "collaborators": ["username1", "username2"],
    "first_comment": "Link in bio!"
  },
  "youtube": {
    "title": "My Video Title",
    "privacy_status": "public"
  },
  "tiktok": {
    "privacy_status": "PUBLIC_TO_EVERYONE",
    "auto_add_music": true
  }
}

Retorna:

{
  "post_id": "job-123",
  "accepted_at": "2024-01-01T12:00:00Z",
  "status": "pending",
  "draft": true
}

Nota sobre posts rascunho: Se você solicitar um post rascunho (draft: true) mas a API retornar draft: false, um campo warning será incluído na resposta indicando que a API pode ter ignorado o parâmetro de rascunho. Isso pode acontecer se a API não suportar rascunhos com certos parâmetros (ex.: anexos de mídia) ou sob condições específicas. Verifique o campo warning na resposta para detalhes.

`post_status`

Obtém o status de um post publicado pelo ID do trabalho.

Parâmetros:

post_id (string, obrigatório): ID do post da resposta de post.publish

Retorna:

{
  "post_id": "job-123",
  "overall_status": "complete",
  "draft": false,
  "status": "processed",
  "content": "Full post body as submitted...",
  "scheduled_at": "2024-01-02T09:00:00Z",
  "created_at": "2024-01-01T12:00:00Z",
  "source": "postproxy",
  "queue_id": null,
  "platforms": [
    {
      "platform": "twitter",
      "status": "published",
      "url": "https://twitter.com/status/123",
      "post_id": "123",
      "error": null,
      "attempted_at": "2024-01-01T12:00:00Z"
    }
  ]
}

scheduled_at é null para posts publicados imediatamente. O url da plataforma é o permalink publicado (nulo até a publicação).

Valores de status:

overall_status: "draft", "pending", "processing", "complete", "failed"
status da plataforma: "pending", "processing", "published", "failed", "deleted"
error da plataforma: Mensagem de erro se a publicação falhou (nulo se bem-sucedido)

`post_publish_draft`

Publica um post rascunho. Apenas posts com status draft: true podem ser publicados usando este endpoint.

Parâmetros:

post_id (string, obrigatório): ID do post rascunho a ser publicado

Retorna:

{
  "post_id": "job-123",
  "status": "processed",
  "draft": false,
  "scheduled_at": null,
  "created_at": "2024-01-01T12:00:00Z",
  "message": "Draft post published successfully"
}

`post_delete`

Exclui um post pelo ID do trabalho.

Parâmetros:

post_id (string, obrigatório): ID do post a ser excluído

Retorna:

{
  "post_id": "job-123",
  "deleted": true
}

`post_stats`

Obtém instantâneos de estatísticas para um ou mais posts. Retorna todos os instantâneos correspondentes para que você possa ver tendências ao longo do tempo. Suporta filtragem por perfis/redes e período.

Parâmetros:

post_ids (string[], obrigatório): Matriz de hashids de posts (máx. 50)
profiles (string, opcional): Lista separada por vírgulas de hashids de perfis ou nomes de redes (ex.: instagram,twitter ou abc123,def456 ou misto)
from (string, opcional): Timestamp ISO 8601 — incluir apenas instantâneos registrados neste horário ou depois
to (string, opcional): Timestamp ISO 8601 — incluir apenas instantâneos registrados neste horário ou antes

Retorna:

{
  "data": {
    "abc123": {
      "platforms": [
        {
          "profile_id": "prof_abc",
          "platform": "instagram",
          "records": [
            {
              "stats": {
                "impressions": 1200,
                "likes": 85,
                "comments": 12,
                "saved": 8
              },
              "recorded_at": "2026-02-20T12:00:00Z"
            }
          ]
        }
      ]
    }
  }
}

Campos de estatísticas por plataforma:

Plataforma	Campos
Instagram	`impressions`, `likes`, `comments`, `saved`, `profile_visits`, `follows`
Facebook	`impressions`, `clicks`, `likes`
Threads	`impressions`, `likes`, `replies`, `reposts`, `quotes`, `shares`
Twitter	`impressions`, `likes`, `retweets`, `comments`, `quotes`, `saved`
YouTube	`impressions`, `likes`, `comments`, `saved`
LinkedIn	`impressions`
TikTok	`impressions`, `likes`, `comments`, `shares`
Pinterest	`impressions`, `likes`, `comments`, `saved`, `outbound_clicks`

Notas: Stories do Instagram não retornam estatísticas. Estatísticas do TikTok exigem que o post tenha um ID público.

Gerenciamento de Filas

`queues_list`

Lista todas as filas de publicação. Filas agendam automaticamente posts em horários semanais recorrentes com ordenação baseada em prioridade.

Parâmetros:

profile_group_id (string, opcional): Filtra filas por grupo de perfis

Retorna:

{
  "queues": [
    {
      "id": "q1abc",
      "name": "Morning Posts",
      "description": "Daily morning content",
      "timezone": "America/New_York",
      "enabled": true,
      "jitter": 10,
      "profile_group_id": "pg123",
      "timeslots": ["Monday at 09:00 (id: 1)", "Wednesday at 09:00 (id: 2)"],
      "posts_count": 5
    }
  ]
}

`queues_get`

Obtém detalhes de uma única fila de publicação incluindo seus horários e contagem de posts.

Parâmetros:

queue_id (string, obrigatório): ID da fila

`queues_create`

Cria uma nova fila de publicação com horários semanais. Parâmetros:

profile_group_id (string, obrigatório): ID do grupo de perfis para conectar a fila (use profiles_list para encontrar isso)
name (string, obrigatório): Nome da fila
description (string, opcional): Descrição opcional
timezone (string, opcional): Nome do fuso horário IANA (ex.: America/New_York). Padrão: UTC
jitter (number, opcional): Deslocamento aleatório em minutos (0–60) aplicado aos horários agendados para padrões naturais de postagem. Padrão: 0
timeslots (array, opcional): Intervalos de tempo semanais iniciais. Cada objeto possui day (0=domingo até 6=sábado) e time (formato HH:MM de 24 horas)

Exemplo:

{
  "profile_group_id": "pg123",
  "name": "Weekday Mornings",
  "timezone": "America/New_York",
  "jitter": 10,
  "timeslots": [
    { "day": 1, "time": "09:00" },
    { "day": 2, "time": "09:00" },
    { "day": 3, "time": "09:00" },
    { "day": 4, "time": "09:00" },
    { "day": 5, "time": "09:00" }
  ]
}

`queues_update`

Atualize as configurações, intervalos de tempo ou pause/despause uma fila. Alterações no fuso horário ou nos intervalos de tempo acionam o rearranjo de todas as postagens na fila.

Parâmetros:

queue_id (string, obrigatório): ID da fila a ser atualizada
name (string, opcional): Novo nome da fila
description (string, opcional): Nova descrição
timezone (string, opcional): Nome do fuso horário IANA
enabled (boolean, opcional): Defina como false para pausar a fila, true para despausar
jitter (number, opcional): Deslocamento aleatório em minutos (0–60)
timeslots (array, opcional): Intervalos de tempo para adicionar ou remover. Para adicionar: { "day": 1, "time": "09:00" }. Para remover: { "id": 42, "_destroy": true }.

`queues_delete`

Exclua uma fila de postagem. As postagens na fila terão sua referência de fila removida, mas não serão excluídas.

Parâmetros:

queue_id (string, obrigatório): ID da fila a ser excluída

`queues_next_slot`

Obtenha o próximo intervalo de tempo disponível para uma fila.

Parâmetros:

queue_id (string, obrigatório): ID da fila

Retornos:

{
  "next_slot": "2026-03-11T14:00:00Z"
}

Adicionando Postagens a uma Fila

Ao publicar uma postagem com post_publish, você pode adicioná-la a uma fila em vez de agendá-la manualmente:

queue_id (string, opcional): ID da fila para adicionar a postagem. A fila atribuirá automaticamente um intervalo de tempo. Não use junto com schedule.
queue_priority (string, opcional): Nível de prioridade: high, medium (padrão) ou low. Postagens com prioridade mais alta recebem intervalos de tempo mais cedo.

Exemplo:

{
  "content": "Queued post content",
  "profiles": ["twitter", "linkedin"],
  "queue_id": "q1abc",
  "queue_priority": "high"
}

Gerenciamento de Comentários

`comments_list`

Liste comentários em uma postagem publicada. Retorna comentários de nível superior paginados com respostas aninhadas.

Parâmetros:

post_id (string, obrigatório): ID da postagem
profile_id (string, obrigatório): ID do perfil para identificar de qual plataforma os comentários devem ser recuperados
page (number, opcional): Número da página, com índice zero (padrão: 0)
per_page (number, opcional): Número de comentários de nível superior por página (padrão: 20)
from (string, opcional): Data/hora ISO 8601 — apenas comentários recebidos neste ponto ou depois
to (string, opcional): Data/hora ISO 8601 — apenas comentários recebidos neste ponto ou antes

from/to filtram quando o Postproxy recebeu o comentário, não o posted_at da plataforma (que nem sempre é preenchido). Uma data simples como 2026-03-25 significa o início do dia dessa data. O filtro se aplica apenas a comentários de nível superior — um comentário dentro do intervalo ainda retorna seu array completo de replies.

Retornos:

{
  "total": 42,
  "page": 0,
  "per_page": 20,
  "data": [
    {
      "id": "cmt_abc123",
      "external_id": "17858893269123456",
      "body": "Great post!",
      "status": "synced",
      "author_username": "someuser",
      "like_count": 3,
      "is_hidden": false,
      "posted_at": "2026-03-25T10:00:00.000Z",
      "replies": [
        {
          "id": "cmt_def456",
          "body": "Thanks!",
          "author_username": "author",
          "parent_external_id": "17858893269123456"
        }
      ]
    }
  ]
}

Os objetos de comentário também podem incluir um array attachments (mídia no comentário — image, video, audio, gif, external, file), cada um com id, type, url, status e external_id. Preenchido para Facebook, Threads e Bluesky; comentários do Instagram, YouTube e LinkedIn são apenas texto. O array fica vazio quando não há mídia.

`comments_get`

Obtenha um único comentário com suas respostas.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário (ID do Postproxy ou ID externo da plataforma)
profile_id (string, obrigatório): ID do perfil

`comments_create`

Crie um comentário ou resposta em uma postagem publicada. O comentário é publicado na plataforma de forma assíncrona.

Parâmetros:

post_id (string, obrigatório): ID da postagem
profile_id (string, obrigatório): ID do perfil
text (string, obrigatório): Conteúdo de texto do comentário
parent_id (string, opcional): ID do comentário para responder (ID do Postproxy ou ID externo). Omita para comentar na própria postagem.

Retornos:

{
  "id": "cmt_ghi789",
  "body": "Thanks for the feedback everyone!",
  "status": "pending",
  "external_id": null
}

O comentário é criado com status: "pending". Uma vez publicado na plataforma, torna-se "published". Se a publicação falhar, torna-se "failed".

`comments_delete`

Exclua um comentário da plataforma de forma assíncrona. Suportado no Instagram, Facebook, YouTube e LinkedIn. Não suportado no Threads.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário (ID do Postproxy ou ID externo)
profile_id (string, obrigatório): ID do perfil

`comments_edit`

Edite o texto de um comentário que você publicou, de forma assíncrona. Suportado apenas no Facebook e YouTube. Retorna { accepted: true }; o resultado chega via webhooks comment.edited / comment.edit_failed.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário (ID do Postproxy ou ID externo)
profile_id (string, obrigatório): ID do perfil
body (string, obrigatório): Novo texto do comentário

`comments_hide`

Oculte um comentário na plataforma de forma assíncrona. Suportado no Instagram, Facebook e Threads.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário
profile_id (string, obrigatório): ID do perfil

`comments_unhide`

Reexiba um comentário anteriormente oculto. Suportado no Instagram, Facebook e Threads.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário
profile_id (string, obrigatório): ID do perfil

`comments_like`

Curta um comentário na plataforma de forma assíncrona. Atualmente suportado apenas no Facebook.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário
profile_id (string, obrigatório): ID do perfil

`comments_unlike`

Remova uma curtida de um comentário. Atualmente suportado apenas no Facebook.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário
profile_id (string, obrigatório): ID do perfil

Suporte por Plataforma

Ação	Instagram	Facebook	Threads	YouTube	LinkedIn
Listar	Sim	Sim	Sim	Sim	Sim
Responder	Sim	Sim	Sim	Sim	Sim
Excluir	Sim	Sim	Não	Sim	Sim
Ocultar/Reexibir	Sim	Sim	Sim	Não	Não
Curtir/Descurtir	Não	Sim	Não	Não	Não

Mensagens Diretas

Mensagens 1:1 (chats e mensagens) em perfis com capacidade de DM. Suportado no Facebook (Messenger), Instagram (DMs), Telegram (DMs de Bot), Bluesky e WhatsApp. Envios de saída são processados de forma assíncrona (retornados com status: "pending"). A janela de mensagens de 24h da Meta se aplica ao Facebook/Instagram — um humano respondendo à própria consulta do participante pode passar tag: "HUMAN_AGENT" para enviar fora dela (até 7 dias, nunca para conteúdo promocional ou automatizado); Telegram e Bluesky não têm janela. No WhatsApp, a janela é reaberta apenas enviando um modelo aprovado (template) ou um texto category: "utility" — consulte Gerenciamento de Negócios do WhatsApp para o restante da superfície do WhatsApp.

`dm_chats_list`

Liste chats para um perfil, ordenados pela atividade mais recente.

Parâmetros:

profile_id (string, obrigatório): ID do perfil (Facebook, Instagram, Telegram, Bluesky ou WhatsApp)
page (number, opcional): Número da página, com índice zero (padrão: 0)
per_page (number, opcional): Itens por página (padrão: 20)
before / after (string, opcional): Filtros de timestamp ISO 8601 em last_message_at

Os chats do WhatsApp também carregam external_placement_id (o número de telefone ao qual o chat pertence), group (true para chats em grupo) e within_messaging_window.

`dm_chat_create`

Encontre ou crie um chat para um participante (idempotente — retorna o chat existente se houver um). Use antes de enviar mensagem a um participante com quem o perfil ainda não se comunicou.

Parâmetros:

profile_id (string, obrigatório): ID do perfil
participant_external_id (string, obrigatório): ID do participante na plataforma (ID de usuário com escopo IG, PSID do Facebook, ID de usuário do Telegram, DID do Bluesky ou número de telefone do WhatsApp com código do país — não-dígitos são removidos)
placement_id (string, opcional): ID de posicionamento de profiles_placements. Obrigatório no WhatsApp (o número de telefone no qual o chat está); opcional no Facebook (ID da página)
participant_username (string, opcional)
participant_name (string, opcional)

Uma conversa totalmente nova no WhatsApp não tem janela de mensagens aberta, então o primeiro envio nela deve ser um template (veja dm_message_send).

`dm_chat_get`

Obtenha um único chat pelo ID do Postproxy ou external_conversation_id da plataforma.

Parâmetros:

chat_id (string, obrigatório): ID do chat ou ID externo da conversa

`dm_messages_list`

Liste mensagens em um chat, das mais recentes para as mais antigas.

Parâmetros:

chat_id (string, obrigatório): ID do chat ou ID externo da conversa
page (number, opcional): Número da página, com índice zero (padrão: 0)
per_page (number, opcional): Itens por página (padrão: 20)
direction (string, opcional): inbound ou outbound
status (string, opcional): Filtrar por status da mensagem

`dm_message_send`

Envie uma mensagem de saída. Forneça exatamente um de body (texto), media (um único anexo) ou — no WhatsApp — template, interactive, location ou contacts. Parâmetros:

chat_id (string, obrigatório): ID do chat ou ID de conversa externo
body (string, opcional): Texto da mensagem (obrigatório quando nada mais é enviado; no WhatsApp também pode acompanhar media como legenda)
media (string[], opcional): Até um anexo como URL ou caminho de arquivo local. Não suportado no Bluesky. (O MCP remoto/Worker aceita apenas URLs.) Limites do WhatsApp: imagem 5MB jpeg/png, vídeo 16MB mp4/3gpp, áudio 16MB, documento 100MB.
tag (string, opcional): HUMAN_AGENT para enviar fora da janela de 24h — estende para 7 dias a partir da última mensagem recebida do participante (somente Facebook/Instagram). A Meta restringe a um humano respondendo à própria consulta do participante; usar para marketing, ofertas ou reengajamento automatizado pode suspender a capacidade de envio de mensagens dessa Página/conta do Instagram. Após 7 dias, a Meta rejeita o envio e a mensagem cai em status: failed com o erro da plataforma em error_details.
reply_to_external_id (string, opcional): Telegram e WhatsApp — ID da mensagem da plataforma (Telegram message_id, WhatsApp wamid) para citar/responder em tópico
reply_markup (objeto, opcional): Somente Telegram — payload de teclado inline/de resposta
quick_replies (objeto[], opcional): Somente Facebook e Instagram — até 13 chips tocáveis acima do compositor do participante. Cada { title, payload }.
buttons (objeto[], opcional): Somente Facebook e Instagram — até 3 botões anexados à mensagem. Cada { type: "web_url", title, url } ou { type: "postback", title, payload }.
card (objeto, opcional): Somente Facebook e Instagram — campos extras para o cartão que carrega buttons (subtitle, image_url, default_action). Requer buttons.
template (objeto, opcional): Somente WhatsApp — enviar um modelo aprovado: { id | name, language, variables[], button_params[], header_media, header_location }. A única forma de enviar mensagem fora da janela de 24h ou abrir uma nova conversa.
interactive (objeto, opcional): Somente WhatsApp — mensagem interativa no formato da Meta (botões de resposta, lista, cta_url, produto, fluxo, solicitação de localização), passada sem alterações
location (objeto, opcional): Somente WhatsApp — { latitude, longitude, name, address }
contacts (objeto[], opcional): Somente WhatsApp — cartões de contato no formato contacts da Meta
category (string, opcional): Somente WhatsApp — "utility" marca um envio de texto simples como um Direct Send utilitário que pode sair da janela sem modelo
link_preview (booleano, opcional): Somente WhatsApp — false suprime a prévia de URL em uma mensagem de texto
voice_note (booleano, opcional): Somente WhatsApp — entregar um anexo de áudio OGG/Opus como nota de voz
filename (string, opcional): Somente WhatsApp — nome de exibição para um anexo de documento

Respostas rápidas e botões

Somente Facebook Messenger e Instagram Direct — no Telegram use reply_markup (passar estes retorna um 422). Respostas rápidas são chips efêmeros que desaparecem após um toque; botões permanecem anexados à mensagem no tópico.

	`quick_replies`	`buttons`
Máx. por envio	13	3
`title`	obrigatório, ≤20 caracteres	obrigatório, ≤20 caracteres
`payload`	obrigatório, ≤1000 caracteres	obrigatório para `postback`, ≤1000 caracteres
`url`	—	obrigatório para `web_url`, deve ser `https://`
Precisa de `body`	não	sim, e `body` é limitado a 80 caracteres
Com `media`	somente Facebook	não permitido

{
  "chat_id": "chat_xyz789",
  "body": "What can I help with?",
  "quick_replies": [
    { "title": "Track order", "payload": "TRACK" },
    { "title": "Talk to support", "payload": "HELP" }
  ]
}

{
  "chat_id": "chat_xyz789",
  "body": "Nike Air Max",
  "card": { "subtitle": "$129 · Arriving Friday", "image_url": "https://cdn.example.com/shoe.png" },
  "buttons": [
    { "type": "web_url", "title": "Buy now", "url": "https://shop.example.com/p/air-max" },
    { "type": "postback", "title": "Notify me", "payload": "NOTIFY:air-max" }
  ]
}

Os botões são entregues como um modelo genérico da Meta cujo título do elemento é seu body — é daí que vem o limite de 80 caracteres. O Instagram é mais restritivo que o Messenger: ele entrega respostas rápidas apenas em mensagens de texto simples, então quick_replies com media ou com buttons retorna 422 lá.

Recebendo toques: um postback de chip ou botão tocado chega como uma mensagem recebida carregando tapped_action: { "kind": "quick_reply" | "postback" | "callback_query", "payload": "...", "title": "..." }. Leia de dm_messages_list / dm_message_get em vez de procurar em platform_data. Toques de quebra-gelo do Instagram e callbacks de consulta do Telegram são normalizados no mesmo campo.

Modelos do WhatsApp e mensagens interativas

Um número do WhatsApp só pode enviar texto livre, mídia, interactive, location e contacts enquanto a janela de 24h do participante estiver aberta (within_messaging_window no chat). Fora dela — incluindo uma conversa iniciada por você — envie um modelo aprovado. variables preenchem os placeholders em ordem (variáveis de texto do cabeçalho primeiro, depois variáveis do corpo, depois variáveis de botão de URL dinâmica) e devem corresponder ao variable_count do modelo de whatsapp_templates_list; o corpo renderizado é armazenado na mensagem.

{
  "chat_id": "chat_wa1",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": ["Ana", "ORD-12345"]
  }
}

Modelos com cabeçalho de mídia usam header_media: { "link": "https://..." }; um cabeçalho de localização usa header_location; botões de URL / código de cópia / fluxo usam button_params: [{ "index": 0, "sub_type": "url", "parameters": [{ "type": "text", "text": "12345" }] }].

Dentro da janela, interactive é o objeto próprio da Meta — botões de resposta (até 3), uma lista (até 10 linhas), uma URL de CTA, um cartão de produto, um fluxo ou uma solicitação de localização:

{
  "chat_id": "chat_wa1",
  "interactive": {
    "type": "button",
    "body": { "text": "Ready to confirm your booking?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
        { "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } }
      ]
    }
  }
}

Um toque volta como uma mensagem recebida cujo body é o título tocado, com o id de resposta sob platform_data.interactive. quick_replies / buttons do Facebook/Instagram retornam 422 no WhatsApp, e template / interactive / location / contacts / category retornam 422 em todas as outras redes.

`dm_message_get`

Obter uma única mensagem por ID Postproxy ou external_id da plataforma.

Parâmetros:

message_id (string, obrigatório): ID da mensagem ou ID externo

`dm_message_edit`

Editar uma mensagem enviada anteriormente. Somente Telegram. Forneça body e/ou reply_markup (passe {} para limpar o teclado); pelo menos um é obrigatório.

Parâmetros:

message_id (string, obrigatório): ID da mensagem ou ID externo
body (string, opcional): Novo texto/legenda
reply_markup (objeto, opcional): Novo teclado (ou {} para remover)

`dm_message_react` / `dm_message_unreact`

Adicionar ou remover a reação da sua conta comercial em uma mensagem. Facebook Messenger, Instagram Direct e WhatsApp.

Parâmetros (dm_message_react):

message_id (string, obrigatório): ID da mensagem ou ID externo
reaction (string, opcional): Reação nomeada (padrão love). Ignorada no WhatsApp
emoji (string, opcional): Emoji Unicode. Obrigatório no WhatsApp (qualquer emoji)

Parâmetros (dm_message_unreact):

message_id (string, obrigatório)

`dm_chat_archive` / `dm_chat_unarchive`

Arquivar (silenciar) ou desarquivar (reativar som) um chat. Somente Bluesky. Retorna o chat com archived definido.

Parâmetros:

chat_id (string, obrigatório): ID do chat ou ID de conversa externo

`dm_chat_mark_read`

Marcar um chat como lido. No WhatsApp, isso envia o recibo de leitura (ticks azuis) para a mensagem recebida mais recente; em outras redes, apenas carimba metadata.read_at. Retorna o chat.

Parâmetros:

chat_id (string, obrigatório): ID do chat ou ID de conversa externo

`dm_comment_private_reply`

Enviar um DM ao autor de um comentário, em resposta a esse comentário ("Respostas Privadas" da Meta). Ignora a janela de 24h (comentários de até 7 dias) e cria/reutiliza um chat automaticamente. Uma resposta privada por comentário, sempre. Somente Instagram e Facebook.

Parâmetros:

post_id (string, obrigatório): ID da postagem
comment_id (string, obrigatório): ID do comentário ou ID externo
profile_id (string, obrigatório): ID do perfil (Instagram ou Facebook)
text (string, obrigatório): Texto do DM
quick_replies (array, opcional): Até 13 chips — mesmo formato de dm_message_send
buttons (array, opcional): Até 3 botões — mesmo formato de dm_message_send; limita text a 80 caracteres
card (objeto, opcional): Estilo do cartão para buttons (subtitle, image_url, default_action)

Elementos interativos seguem as mesmas regras de dm_message_send — no Instagram, quick_replies e buttons são mutuamente exclusivos. Anexos de mídia não estão disponíveis em respostas privadas.

Suporte de Plataforma

Ação	Facebook	Instagram	Telegram	Bluesky	WhatsApp
Listar/Enviar/Obter	Sim	Sim	Sim	Sim	Sim
Anexo de mídia	Sim	Sim	Sim	Não	Sim (legenda permitida)
Editar mensagem	Não	Não	Sim	Não	Não
Reagir/Desfazer reação	Sim	Sim	Não	Não	Sim (`emoji`)
Arquivar/Desarquivar	Não	Não	Não	Sim	Não
Marcar como lido (recibo enviado)	somente local	somente local	somente local	somente local	Sim
Resposta privada a comentário	Sim	Sim	Não	Não	Não
`tag` (janela de 24h)	Sim	Sim	n/a	n/a	Não — use `template` / `category: utility`
`reply_to_external_id`	Não	Não	Sim	Não	Sim
`reply_markup`	Não	Não	Sim	Não	Não
`quick_replies` / `buttons` / `card`	Sim	Sim (somente texto)	Não	Não	Não — use `interactive`
`template` / `interactive` / `location` / `contacts`	Não	Não	Não	Não	Sim
`tapped_action` em toques recebidos	Sim	Sim	Sim	Não	Não (veja `platform_data.interactive`)

Histórico

`history_list`

Listar trabalhos de postagem recentes.

Parâmetros:

limit (número, opcional): Número máximo de trabalhos a retornar (padrão: 10)

Retorna:

{
  "jobs": [
    {
      "post_id": "job-123",
      "content": "Full post body as submitted...",
      "content_preview": "Post content preview...",
      "created_at": "2024-01-01T12:00:00Z",
      "overall_status": "complete",
      "status": "processed",
      "scheduled_at": "2024-01-02T09:00:00Z",
      "draft": false,
      "source": "postproxy",
      "queue_id": null,
      "platforms_count": 2,
      "platforms": [
        {
          "platform": "twitter",
          "status": "published",
          "url": "https://x.com/user/status/123"
        }
      ]
    }
  ]
}

scheduled_at é null para postagens publicadas imediatamente. status é o status bruto da API (draft, scheduled, processing, processed, …), enquanto overall_status resume os resultados da plataforma em um único veredito.

Nota: A API /posts do Postproxy não retorna identidade de perfil (ID ou nome do perfil) por plataforma — apenas a rede. Use profiles_list para mapear redes para perfis conectados.

Gerenciamento do Perfil do Google Business

Estas ferramentas editam o próprio anúncio do Google Business — horários, atributos, serviços, menus de comida, links de ação e fotos de perfil — em vez de publicar postagens locais nele (isso é post_publish com plataforma google_business).

Três regras se aplicam a toda ferramenta neste grupo:

location_id é sempre obrigatório. É o caminho completo do recurso do Google accounts/X/locations/Y, retornado por profiles_placements.
Atualizações são mascaradas por campo. Cada escrita usa um array fields nomeando exatamente o que está sendo substituído. Qualquer coisa nomeada em fields mas ausente no payload é limpa, e objetos aninhados são substituídos por completo, não mesclados. Sempre leia antes de corrigir.
Disponibilidade varia por categoria e região. Atributos, listas de serviços, menus de comida e tipos de link de ação diferem por anúncio. Liste o que está disponível primeiro; uma localização não elegível retorna 422.

Os payloads usam os formatos próprios do Google e chaves em camelCase em ambas as direções, então uma resposta pode ser enviada diretamente de volta como corpo de solicitação.

Ferramenta	Finalidade
`google_business_location_get`	Ler o anúncio — nome, descrição, site, telefones, categorias, endereço, horários, área de serviço, metadados
`google_business_location_update`	Atualizar campos do anúncio (`title`, `websiteUri`, `phoneNumbers`, `categories`, `storefrontAddress`, `serviceArea`, `labels`, `latlng`, `openInfo`, `profile`, `storeCode`)
`google_business_categories_list`	Resolver nomes de recursos de categoria (`categories/gcid:*`) para uma região — necessário para qualquer patch de `categories`
`google_business_hours_update`	Definir `regularHours`, `specialHours` e `moreHours`
`google_business_attributes_get`	Ler atributos atualmente definidos
`google_business_attributes_available`	Listar quais atributos este anúncio pode definir, com tipos de valor
`google_business_attributes_update`	Definir atributos
`google_business_service_list_get`	Ler a lista de serviços
`google_business_service_list_update`	Substituir a lista de serviços (requer `metadata.canModifyServiceList`)
`google_business_food_menus_get`	Ler cardápios de alimentos (somente categorias do tipo restaurante)
`google_business_food_menus_update`	Substituir cardápios de alimentos (requer `metadata.canHaveFoodMenus`)
`google_business_place_action_links_list`	Listar botões de ação ("Agendar online", "Pedir online")
`google_business_place_action_link_create`	Adicionar um botão de ação
`google_business_place_action_link_update`	Atualizar um botão de ação
`google_business_place_action_link_delete`	Remover um botão de ação
`google_business_media_list`	Listar fotos e vídeos do perfil
`google_business_media_create`	Adicionar uma foto ou vídeo
`google_business_media_delete`	Remover uma foto ou vídeo

Fluxo típico

1. profiles_placements                    → get location_id
2. google_business_location_get           → read current state
3. google_business_attributes_available   → see what this listing accepts
4. google_business_attributes_update      → patch only what changed

Formatos de valores de atributos

google_business_attributes_available retorna um valueType por atributo, que determina o formato a ser enviado de volta:

valueType	Formato
`BOOL`	`{ "name": "attributes/offers_online_appointments", "values": [true] }`
`URL`	`{ "name": "attributes/url_linkedin", "uriValues": [{ "uri": "https://..." }] }`
`ENUM`	`{ "name": "attributes/preferred_messaging_service", "repeatedEnumValue": { "setValues": ["TOKEN"] } }`

attribute_mask usa por padrão exatamente os nomes que você envia, então uma atualização parcial nunca limpa atributos que você deixou de fora.

Horários

Os horários aceitam strings "09:00" / "09:00:00" ou objetos { "hours": 9, "minutes": 0 } do Google — ambos são normalizados antes da chamada. Leia os horários atuais de google_business_location_get; cada bloco nomeado em fields é substituído por completo.

{
  "fields": ["regularHours"],
  "regularHours": {
    "periods": [
      { "openDay": "MONDAY", "openTime": "09:00", "closeDay": "MONDAY", "closeTime": "18:00" }
    ]
  }
}

Mídia

O Google baixa o arquivo de media_url diretamente — não há etapa de upload, então a URL deve ser publicamente acessível https (não uma URL assinada de curta duração, nem localhost). Imagens precisam ter no mínimo 250×250 e no máximo 5MB. category usa como padrão ADDITIONAL; use COVER ou LOGO somente quando você pretende alterar o cabeçalho ou o logotipo do perfil.

Leitura de resultados vazios

O Google omite chaves em vez de retornar valores vazios: um anúncio sem atributos retorna { "name": "..." } sem nenhuma chave attributes, e o mesmo se aplica a serviceItems, placeActionLinks e sinalizadores booleanos como isPreferred. Trate ausência como vazio.

Analytics

Os dados analíticos de localização do Google Business passam pela ferramenta padrão profiles_stats — passe o location_id como placement_id. As métricas são impressões no Search e no Maps (desktop e mobile), cliques no site, cliques de chamada, solicitações de rota, conversas, reservas, pedidos de comida e cliques no cardápio de alimentos. O Google Business não tem contagem de seguidores, e o Google não expõe dados analíticos por postagem para posts locais.

Gerenciamento do WhatsApp Business

Gerencie uma conta do WhatsApp Business conectada além da caixa de entrada: modelos de mensagem, status e registro do número de telefone, perfil público da empresa, nome de exibição e nome de usuário, usuários bloqueados, grupos e relatórios de conversão do Click-to-WhatsApp. As conversas em si passam pelas ferramentas dm_* acima.

Quatro regras se aplicam a todas as ferramentas deste grupo:

A conta do WhatsApp Business (WABA) é o perfil; cada número de telefone nela é uma veiculação. Ferramentas com escopo de telefone recebem phone_number_id — a veiculação id de profiles_placements (seus metadados carregam display_phone_number, quality_rating, messaging_limit_tier, name_status, platform_type).
Modelos e o conjunto de dados de Conversões são de nível WABA — essas ferramentas recebem apenas profile_id.
Mensagens de formato livre somente dentro da janela de 24h. Quando a última mensagem recebida de um participante tem mais de 24h (ou a conversa é nova), dm_message_send aceita apenas um template APROVADO (ou um texto category: "utility"). Um modelo entregue reabre a janela.
Números de coexistência são limitados. Um número conectado com onboarding: "business_app" (ainda no aplicativo WhatsApp Business em um telefone) tem menor throughput e não pode usar a API de Grupos; whatsapp_number_info relata platform_type diferente de CLOUD_API para esses casos.

As respostas usam os nomes de campos da própria Meta onde os formatos da Meta são retornados (components, interactive, campos do perfil da empresa).

Ferramenta	Finalidade
`whatsapp_templates_list`	Listar modelos sincronizados (filtro `name`, `language`, `status`; `refresh: true` ressincroniza da Meta primeiro)
`whatsapp_template_get`	Um modelo com componentes, status e `variable_count`
`whatsapp_template_create`	Enviar um modelo personalizado (`components`) ou instanciar um da biblioteca (`library_template_name`)
`whatsapp_template_update`	Alterar `components` (de volta para PENDENTE de revisão) e/ou `message_send_ttl_seconds`
`whatsapp_template_delete`	Excluir um idioma (`language`) ou o nome inteiro
`whatsapp_template_library_get`	Inspecionar um modelo da biblioteca da Meta antes de instanciá-lo
`whatsapp_number_info`	Status ao vivo do número + WABA: classificação de qualidade, nível de mensagens, status do nome, tipo de plataforma
`whatsapp_number_register`	Registrar o número com a Cloud API usando seu PIN de 6 dígitos
`whatsapp_number_request_verification_code`	Código de verificação por SMS / voz para um número não verificado
`whatsapp_number_verify`	Enviar o código de verificação
`whatsapp_business_profile_get`	Perfil público: sobre, endereço, descrição, e-mail, sites, segmento, foto
`whatsapp_business_profile_update`	Atualizar esses campos (`about` ≤139, `description` ≤512, ≤2 sites)
`whatsapp_business_profile_photo_update`	Substituir a foto do perfil (`url` ou base64 `data`; JPEG/PNG ≤5MB)
`whatsapp_display_name_get`	Nome de exibição verificado e status da revisão
`whatsapp_display_name_request_change`	Enviar um novo nome de exibição para revisão da Meta
`whatsapp_username_get` / `_set` / `_delete` / `_suggestions`	Gerenciar o nome de usuário `wa.me` do número
`whatsapp_blocked_users_list` / `whatsapp_blocked_user_status`	Quem está bloqueado
`whatsapp_users_block` / `whatsapp_users_unblock`	Bloquear / desbloquear até 1000 números por chamada
`whatsapp_groups_list` / `_create` / `_get` / `_update` / `_delete`	Grupos que o número administra (somente números da Cloud API)
`whatsapp_group_participants_add` / `_remove`	Gerenciar membros (um grupo comporta 8)
`whatsapp_group_invite_link_create`	Novo link de convite (revoga o anterior)
`whatsapp_group_join_requests_list` / `_approve` / `_reject`	Lidar com solicitações de entrada em grupos que exigem aprovação
`whatsapp_dataset_get` / `whatsapp_dataset_create`	Conjunto de dados da API de Conversões na WABA
`whatsapp_conversion_event_send`	Relatar um LeadSubmitted / Purchase / AddToCart / InitiateCheckout / ViewContent para uma conversa de Click-to-WhatsApp

Fluxo típico

1. profile_groups_initialize_connection   → platform: whatsapp (onboarding: api | business_app)
2. profiles_placements                    → get phone_number_id
3. whatsapp_templates_list                → find an APPROVED template and its variable_count
4. dm_chat_create                         → participant_external_id: phone, placement_id: phone_number_id
5. dm_message_send                        → template: { name, language, variables }
6. dm_messages_list                       → the reply opens a 24h window; free-form sends now work

Conectando um número

profile_groups_initialize_connection com platform: "whatsapp" retorna uma URL de conexão. Passe onboarding: "business_app" quando o número estiver no aplicativo WhatsApp Business em um telefone (o usuário escaneia um código QR; o aplicativo continua funcionando junto com o Postproxy e até 6 meses de conversas são importados) ou onboarding: "api" quando o número estiver com outro provedor ou for totalmente novo (movido para a Cloud API; não pode mais ser usado no aplicativo). Omita e a página de conexão perguntará. Cada conta do WhatsApp Business se torna um perfil e cada um de seus números, uma veiculação.

Modelos

A Meta revisa todos os modelos personalizados; um novo fica PENDING até ser aprovado, e somente modelos APPROVED podem ser enviados. Os espaços reservados são {{1}}, {{2}}… (parameter_format: POSITIONAL, o padrão) ou {{name}} (NAMED). variable_count em um modelo é o número de variables que um envio deve carregar: espaços reservados de texto do cabeçalho, depois espaços reservados do corpo e, em seguida, um por botão de URL dinâmico. Modelos da biblioteca (whatsapp_template_library_get → whatsapp_template_create com library_template_name) pulam a revisão. Um nome é único por idioma; excluir por nome sem language remove todos os idiomas.

Conversões

Conversas que começam a partir de um anúncio de Click-to-WhatsApp carregam um ctwa_clid no metadata da conversa. Crie um conjunto de dados uma vez (whatsapp_dataset_create) e depois relate os resultados com whatsapp_conversion_event_send por chat_id ou phone; uma conversa sem ctwa_clid capturado retorna 422.

Exemplos de Prompts

Aqui estão alguns exemplos de prompts que você pode usar com o Claude Code:

Verificar Autenticação

Check my PostProxy authentication status

Listar Perfis

Show me all my available social media profiles

Publicar um Post

Usando IDs de perfil:

Publish this post: "Check out our new product!" to profiles ["profile-123"]

Usando nomes de plataforma:

Publish "Exciting news!" to linkedin and twitter

Publicar com Parâmetros de Plataforma

Você pode usar parâmetros específicos de plataforma para personalizar posts para cada plataforma. O parâmetro platforms aceita um objeto onde as chaves são nomes de plataforma e os valores contêm opções específicas da plataforma.

Exemplos do Instagram

Post Regular com Colaboradores:

Publish to Instagram: "Amazing content!" to my Instagram account with collaborators username1 and username2

Ou com parâmetros explícitos:

{
  "content": "Amazing content!",
  "profiles": ["instagram"],
  "media": ["https://example.com/image.jpg"],
  "platforms": {
    "instagram": {
      "format": "post",
      "collaborators": ["username1", "username2"],
      "first_comment": "What do you think? 🔥"
    }
  }
}

Reel do Instagram:

{
  "content": "Check out this reel! #viral",
  "profiles": ["instagram"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "instagram": {
      "format": "reel",
      "collaborators": ["collaborator_username"],
      "cover_url": "https://example.com/thumbnail.jpg",
      "audio_name": "Trending Audio",
      "first_comment": "Link in bio!"
    }
  }
}

Story do Instagram:

{
  "profiles": ["instagram"],
  "media": ["https://example.com/story-image.jpg"],
  "platforms": {
    "instagram": {
      "format": "story"
    }
  }
}

Exemplos do YouTube

Vídeo do YouTube com Título e Privacidade:

Upload this video to YouTube with title "My Tutorial" and make it public

Ou com parâmetros explícitos:

{
  "content": "This is the video description with links and details",
  "profiles": ["youtube"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "youtube": {
      "title": "My Tutorial: How to Build an API",
      "privacy_status": "public",
      "cover_url": "https://example.com/custom-thumbnail.jpg"
    }
  }
}

Vídeo do YouTube Não Listado:

{
  "content": "Video description",
  "profiles": ["youtube"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "youtube": {
      "title": "Private Tutorial",
      "privacy_status": "unlisted"
    }
  }
}

Exemplos do TikTok

TikTok Público com Música Automática:

{
  "content": "Check this out! #fyp",
  "profiles": ["tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true,
      "disable_comment": false,
      "disable_duet": false,
      "disable_stitch": false
    }
  }
}

TikTok Somente para Seguidores com Rótulo de IA:

{
  "content": "Special content for followers",
  "profiles": ["tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "tiktok": {
      "privacy_status": "FOLLOWER_OF_CREATOR",
      "made_with_ai": true,
      "brand_content_toggle": false
    }
  }
}

Exemplos do Facebook

Post do Facebook com Primeiro Comentário:

{
  "content": "Check out our new product!",
  "profiles": ["facebook"],
  "media": ["https://example.com/product.jpg"],
  "platforms": {
    "facebook": {
      "format": "post",
      "first_comment": "Link to purchase: https://example.com/shop"
    }
  }
}

Story do Facebook:

{
  "profiles": ["facebook"],
  "media": ["https://example.com/story-video.mp4"],
  "platforms": {
    "facebook": {
      "format": "story"
    }
  }
}

Post de Página do Facebook:

{
  "content": "Company announcement",
  "profiles": ["facebook"],
  "platforms": {
    "facebook": {
      "page_id": "123456789",
      "first_comment": "Visit our website for more details"
    }
  }
}

Exemplos do LinkedIn

Post Pessoal no LinkedIn:

{
  "content": "Excited to share my latest article on AI",
  "profiles": ["linkedin"],
  "media": ["https://example.com/article-cover.jpg"]
}

Post de Empresa no LinkedIn:

{
  "content": "We're hiring! Join our team",
  "profiles": ["linkedin"],
  "media": ["https://example.com/careers.jpg"],
  "platforms": {
    "linkedin": {
      "organization_id": "company-id-12345"
    }
  }
}

Exemplos do Bluesky

Post simples no Bluesky (menções/tags/links com facetas automáticas):

{
  "content": "Hey @jay.bsky.team — check out our latest #ruby post: https://example.com/blog/post",
  "profiles": ["bluesky"]
}

Você não precisa de nenhuma marcação — o Postproxy converte automaticamente @handles, #tags e URLs em facetas do AT Protocol, e gera uma prévia de card de link a partir dos metadados Open Graph da URL (quando nenhuma mídia está anexada). Limite de 300 grafemas.

Exemplos do Telegram

Post em canal do Telegram (formatação HTML):

{
  "content": "<b>New release</b> — read more on our blog https://example.com/post",
  "profiles": ["telegram"],
  "platforms": {
    "telegram": {
      "chat_id": "-1001234567890",
      "parse_mode": "HTML",
      "disable_link_preview": true,
      "disable_notification": false
    }
  }
}

Use profiles_placements com seu perfil do Telegram para listar os chat_ids de canais nos quais o bot pode postar. O bot deve ser adicionado ao canal como administrador com permissão para postar.

Exemplos Entre Plataformas

Mesmo Conteúdo, Plataformas Diferentes:

{
  "content": "New product launch! 🚀",
  "profiles": ["instagram", "twitter", "linkedin"],
  "media": ["https://example.com/product.jpg"]
}

Vídeo Entre Plataformas com Parâmetros Específicos:

{
  "content": "Product launch video",
  "profiles": ["instagram", "youtube", "tiktok"],
  "media": ["https://example.com/video.mp4"],
  "platforms": {
    "instagram": {
      "format": "reel",
      "first_comment": "Link in bio!"
    },
    "youtube": {
      "title": "Product Launch 2024",
      "privacy_status": "public",
      "cover_url": "https://example.com/yt-thumbnail.jpg"
    },
    "tiktok": {
      "privacy_status": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true
    }
  }
}

Referência de Parâmetros de Plataforma

Instagram:

format: "post" | "reel" | "story"
collaborators: Matriz de nomes de usuário (máx. 10 para posts, 3 para reels)
first_comment: String - comentário para adicionar após a postagem
cover_url: String - URL da miniatura para reels
audio_name: String - nome da faixa de áudio para reels
trial_strategy: "MANUAL" | "SS_PERFORMANCE" - estratégia de teste para reels
thumb_offset: String - deslocamento da miniatura em milissegundos para reels
user_tags: Matriz de { username, x, y, media_index } - marcar contas públicas do Instagram em qualquer formato (post, reel, story). Imagens exigem x e y (floats 0.0–1.0 a partir do canto superior esquerdo); reels e slides de vídeo são marcados apenas por nome de usuário (as coordenadas são descartadas); stories aceitam coordenadas, mas não precisam delas. media_index seleciona o slide do carrossel (baseado em 0, padrão 0). Um @ inicial é removido. Coordenadas fora do intervalo, um media_index além do último item de mídia ou uma marcação de imagem sem x/y são rejeitados com um 422 nomeando a entrada. Contas privadas e contas com marcação desativada são silenciosamente ignoradas pelo Instagram. YouTube:
title: String - título do vídeo
privacy_status: "public" | "unlisted" | "private"
cover_url: String - URL da miniatura personalizada

TikTok:

privacy_status: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY"
photo_cover_index: Integer - índice da foto a ser usada como capa (baseado em 0)
auto_add_music: Boolean - ativar música automática
made_with_ai: Boolean - marcar conteúdo como gerado por IA
disable_comment: Boolean - desativar comentários
disable_duet: Boolean - desativar duetos
disable_stitch: Boolean - desativar remixagens
brand_content_toggle: Boolean - marcar como parceria paga (terceiros)
brand_organic_toggle: Boolean - marcar como parceria paga (marca própria)

Facebook:

format: "post" | "story"
first_comment: String - comentário a ser adicionado após a publicação
page_id: String - ID da página para publicar em páginas de empresas

LinkedIn:

organization_id: String - ID da organização para publicações em páginas de empresas

Telegram:

chat_id: String, obrigatório — ID do canal/chat de destino (use profiles_placements para listar)
parse_mode: "HTML" | "MarkdownV2" — omita para texto simples
disable_link_preview: Boolean — suprimir cartão de pré-visualização de URL
disable_notification: Boolean — enviar silenciosamente (sem som de notificação)
Limite de caracteres: 4.096 para texto apenas; 1.024 para a legenda quando há mídia anexada (o corpo além disso é truncado)
Mídia: imagens ≤10 MB (×10), vídeo ≤50 MB (×10), documentos ≤50 MB (×1)
O bot deve ser membro (de preferência administrador com permissão de publicação) do canal de destino

Bluesky:

Nenhum parâmetro específico da plataforma disponível
Limite de caracteres: 300 grafemas (emoji e sequências de combinação contam como um)
Detecta automaticamente menções @handle.bsky.social, #hashtags e URLs e as converte em facetas clicáveis
Gera uma pré-visualização de cartão de link a partir do meta Open Graph quando há uma URL presente e nenhuma mídia anexada
Mídia: imagens ≤1 MB (×4), vídeo ≤100 MB (×1, 1–60s)
Suporta threads via o array padrão thread

Twitter/X & Threads:

Nenhum parâmetro específico da plataforma disponível

Para documentação completa, consulte a Referência de Parâmetros da Plataforma.

Criar um Rascunho de Publicação

Create a draft post: "Review this before publishing" to linkedin

Publicar um Rascunho de Publicação

Publish draft post job-123

Verificar Status da Publicação

What's the status of job job-123?

Isso mostrará o status detalhado, incluindo status do rascunho, erros específicos da plataforma e resultados da publicação.

Excluir uma Publicação

Delete post job-123

Obter Estatísticas da Publicação

Show me the stats for post abc123

Get stats for posts abc123 and def456 filtered to Instagram only, from February 1st to today

Listar Posicionamentos

Show me the placements for my LinkedIn profile prof123

Gerenciamento de Fila

Show me all my posting queues

Create a queue called "Weekday Mornings" for profile group pg123, timezone America/New_York, with timeslots Monday through Friday at 9am

Add a post to queue q1abc with high priority: "Check out our latest feature!"

Pause queue q1abc

What's the next available slot for queue q1abc?

Gerenciamento de Comentários

Show me the comments on post abc123 for my Instagram profile prof456

Reply to comment cmt_abc123 on post abc123 with "Thanks for the feedback!" using profile prof456

Hide comment cmt_abc123 on post abc123 for profile prof456

Mensagens Diretas

List the DM chats for my Instagram profile prof456

Reply "Yes, we ship worldwide!" in chat chat_xyz789

Send a DM to the author of comment cmt_abc123 on post abc123 from profile prof456 saying "DM-ing you the details"

Open a WhatsApp chat with +1 310 555 0007 on number 1055512345 of profile prof_wa and send the order_update template in en_US with Ana and ORD-12345

Mark chat chat_wa1 as read and react to the last inbound message with 🔥

Gerenciamento do WhatsApp Business

List the approved WhatsApp templates on profile prof_wa

Create a UTILITY template called appointment_reminder in en_US on profile prof_wa: "Hi {{1}}, your appointment is on {{2}} at {{3}}."

Show the quality rating and messaging tier for number 1055512345 on profile prof_wa

Update the WhatsApp business profile of number 1055512345 on prof_wa: about "Open Mon–Sat 9–18", website https://acme.example

Block +1 310 555 0099 on number 1055512345 of profile prof_wa

Report a Purchase of 49.90 USD for chat chat_wa1 on profile prof_wa with event id ord-9921

Ver Histórico

Show me the last 5 posts I published

Solução de Problemas

O Servidor Não Inicia

Verifique a Chave de API: Certifique-se de que POSTPROXY_API_KEY está definida ao registrar com claude mcp add
Verifique a Versão do Node: Requer Node.js >= 18.0.0
Verifique a Instalação: Confirme que postproxy-mcp está instalado e no PATH
Verifique o Registro: Certifique-se de que o servidor está registrado via claude mcp add e que a configuração está salva em ~/.claude/plugins/

Erros de Autenticação

AUTH_MISSING: A chave de API não está configurada. Certifique-se de incluir --env POSTPROXY_API_KEY=... ao executar claude mcp add
AUTH_INVALID: A chave de API é inválida. Verifique se a chave de API está correta.

Erros de Validação

TARGET_NOT_FOUND: Um ou mais IDs de perfil não existem. Use profiles_list para ver os perfis disponíveis.
VALIDATION_ERROR: O conteúdo ou os parâmetros da publicação são inválidos. A API agora retorna mensagens de erro detalhadas:
- Erros 400: {"status":400,"error":"Bad Request","message":"..."}
- Erros 422: {"errors": ["Error 1", "Error 2"]} - Array de mensagens de erro de validação
- Verifique a mensagem de erro para problemas específicos de validação

Erros de API

API_ERROR: A API do Postproxy retornou um erro. Verifique a mensagem de erro para detalhes.
Timeout: A solicitação levou mais de 30 segundos. Verifique sua conexão de rede e o status da API.

Erros da Plataforma

Ao verificar o status da publicação com post_status, erros específicos da plataforma agora estão disponíveis no campo error de cada objeto da plataforma:

error: null - Publicação publicada com sucesso
error: "Error message" - Mensagem de erro detalhada da API da plataforma
Erros comuns incluem problemas de autenticação, limites de taxa, violações de conteúdo, etc.

Problemas com Rascunhos de Publicação

Se você criar um rascunho de publicação (draft: true) mas receber draft: false na resposta:

A resposta incluirá um campo warning explicando que a API pode ter ignorado o parâmetro de rascunho
Isso pode acontecer se:
- A API não suportar rascunhos com anexos de mídia
- A API tiver limitações específicas para rascunhos de publicação sob certas condições
Verifique o campo warning na resposta para detalhes
Ative o modo de depuração (POSTPROXY_MCP_DEBUG=1) para ver o registro detalhado sobre o tratamento do parâmetro de rascunho

Modo de Depuração

Ative o registro de depuração definindo POSTPROXY_MCP_DEBUG=1 ao registrar o servidor:

claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api --env POSTPROXY_MCP_DEBUG=1 -- postproxy-mcp

Desenvolvimento

Compilando a partir do Código-Fonte

git clone https://github.com/postproxy/postproxy-mcp
cd postproxy-mcp
npm install
npm run build

Executando em Modo de Desenvolvimento

npm run dev

Licença

MIT

Postproxy

Documentação

Servidor MCP Postproxy

Instalação

Instalação Global

Instalação Local

Configuração

Registrar Servidor MCP

Alternativa: Configuração Interativa

Ferramentas Disponíveis

Ferramentas de Autenticação

auth_status

Visão Geral da Conta

summary_get

Gerenciamento de Perfis

profile_groups_list

profiles_list

profiles_placements

profiles_stats

Gerenciamento de Posts

post_publish

post_status

post_publish_draft

post_delete

post_stats

Gerenciamento de Filas

queues_list

queues_get

queues_create

queues_update

queues_delete

queues_next_slot

Adicionando Postagens a uma Fila

Gerenciamento de Comentários

comments_list

comments_get

comments_create

comments_delete

comments_edit

comments_hide

comments_unhide

comments_like

comments_unlike

Suporte por Plataforma

Mensagens Diretas

dm_chats_list

dm_chat_create

dm_chat_get

dm_messages_list

dm_message_send

Respostas rápidas e botões

Modelos do WhatsApp e mensagens interativas

dm_message_get

dm_message_edit

dm_message_react / dm_message_unreact

dm_chat_archive / dm_chat_unarchive

dm_chat_mark_read

dm_comment_private_reply

Suporte de Plataforma

Histórico

history_list

Gerenciamento do Perfil do Google Business

Fluxo típico

Formatos de valores de atributos

Horários

Mídia

Leitura de resultados vazios

Analytics

Gerenciamento do WhatsApp Business

Fluxo típico

Conectando um número

Modelos

Conversões

Exemplos de Prompts

Verificar Autenticação

Listar Perfis

Publicar um Post

Publicar com Parâmetros de Plataforma

Exemplos do Instagram

Exemplos do YouTube

`auth_status`

`summary_get`

`profile_groups_list`

`profiles_list`

`profiles_placements`

`profiles_stats`

`post_publish`

`post_status`

`post_publish_draft`

`post_delete`

`post_stats`

`queues_list`

`queues_get`

`queues_create`

`queues_update`

`queues_delete`

`queues_next_slot`

`comments_list`

`comments_get`

`comments_create`

`comments_delete`

`comments_edit`

`comments_hide`

`comments_unhide`

`comments_like`

`comments_unlike`

`dm_chats_list`

`dm_chat_create`

`dm_chat_get`

`dm_messages_list`

`dm_message_send`

`dm_message_get`

`dm_message_edit`

`dm_message_react` / `dm_message_unreact`

`dm_chat_archive` / `dm_chat_unarchive`

`dm_chat_mark_read`

`dm_comment_private_reply`

`history_list`