Como mandar posts para o PostaChat pela API

Este guia explica, do zero, como um sistema ou um agente de IA (um assistente que produz conteúdo, uma ferramenta de agendamento ou qualquer outro programa) pode preparar posts do Instagram e deixá-los esperando a aprovação de alguém da equipe no PostaChat.

Você não precisa saber programar para entender o guia. Quem for montar a integração encontra, no fim de cada parte, o exemplo pronto para copiar.

Resumo em 30 segundos

1. Alguém da equipe gera uma chave em Configurações > API e passa para quem vai integrar.
2. O sistema envia as fotos ou vídeos do post para o PostaChat.
3. O sistema cria o post como rascunho, com legenda, horário sugerido e opções.
4. O post aparece na tela Publicações > para aprovar. Só vai para o Instagram depois que alguém aprova.

Nada é publicado sozinho pela API. A palavra final é sempre de uma pessoa da equipe (dono ou admin da conta).

Palavras que aparecem neste guia

Antes de começar (uma vez só)

1. A conta precisa estar liberada para publicar. Na tela Publicações, se aparecer o aviso amarelo "libere a publicação desta conta", clique em liberar publicação e confirme no Instagram. Sem isso dá para receber rascunhos, mas ninguém consegue aprovar.

2. Gere a chave.

1. Entre no PostaChat e escolha a conta no menu lateral.
2. Vá em Configurações > API.
3. Clique em gerar chave API.
4. Copie na hora. Por segurança, a chave aparece uma vez só. Depois a tela mostra só o final dela (exemplo: ic_…x7Kq), para você saber qual está ativa.

Perdeu a chave? Clique em gerar nova chave. A antiga para de funcionar no mesmo instante, então atualize em todo lugar que usava.

Quer cortar o acesso de vez? Clique em revogar.

Cuidados com a chave:

• Trate como uma senha. Não cole em grupo, post, print ou e-mail aberto.
• Cada conta do Instagram tem a sua chave. A chave de uma conta não serve para outra.
• Só dono e admin da conta veem e geram a chave. Atendente não tem acesso.

Passo 1: enviar a foto ou o vídeo

Para cada foto ou vídeo do post, mande um pedido de envio. O PostaChat guarda o arquivo, ajusta a foto para o formato que o Instagram aceita e devolve o item (o recibo).

O que mandar:

• o arquivo (foto JPG, PNG ou WebP, ou vídeo MP4 ou MOV);
• para que ele serve:
  • feed: foto de post, vídeo de Reels ou item de carrossel. É o padrão;
  • story: foto ou vídeo de story;
  • cover: imagem de capa de um Reels.

O que o PostaChat faz sozinho com a foto:

• converte para JPG (o Instagram só aceita JPG);
• PNG com fundo transparente ganha fundo branco;
• foto muito grande é reduzida para 1440 pixels de largura.

O que volta (o item):

{
  "key": "publishing/9f1c.../a83b2e.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "size": 18234112,
  "url": "https://... (link para conferir o arquivo, vale 1 hora)"
}

Guarde esse item inteiro: ele vai no Passo 2. Foto volta também com a largura (width) e a altura (height).

Quando o envio é recusado (a mensagem vem em português, ver a tabela "Deu erro"):

• foto de feed que não está entre 4:5 (retrato, tipo 1080 x 1350) e 1,91:1 (paisagem). Foto 9:16 (vertical de celular) só serve como story;
• foto com menos de 320 pixels de largura ou com mais de 30 MB;
• vídeo de feed com mais de 300 MB, ou vídeo de story com mais de 100 MB;
• arquivo que não é foto nem vídeo aceito;
• capa que não é foto.

Exemplo para quem programa:

POST https://api.postachat.com.br/api/v1/content/uploadMedia
Cabeçalho: Authorization: Bearer SUA_CHAVE
Formulário (multipart): file = o arquivo, purpose = feed | story | cover

curl -X POST https://api.postachat.com.br/api/v1/content/uploadMedia \
  -H "Authorization: Bearer $POSTACHAT_KEY" \
  -F "file=@R011.mp4" \
  -F "purpose=feed"

Passo 2: criar o post para aprovar

Com os itens em mãos, crie o post. Ele entra como rascunho e aparece em Publicações > para aprovar.

Os 4 tipos de post

O que dá para mandar

Opções extras (options)

E por foto: dentro de cada item de foto (post de foto ou carrossel) dá para pôr "alt_text": "descrição", até 1.000 caracteres. É o texto alternativo, lido em voz alta para quem usa leitor de tela. Em vídeo e story não vale.

Story não aceita selo de IA, primeiro comentário, texto alternativo nem automação: é limite do Instagram, não do PostaChat.

Como escrever a data (scheduled_at)

Formato: ano-mês-diaThora:minuto:segundo.

• Sem fuso, o PostaChat entende como horário de Brasília.
• Precisa ser um horário no futuro.
• Na resposta, o horário volta em UTC (9h de Brasília aparece como 12:00:00+00:00). É o mesmo horário, só escrito no padrão mundial.
• Sem scheduled_at, o rascunho fica sem data, esperando quem aprova escolher.
• Se o horário sugerido passar e ninguém tiver aprovado, o rascunho não é publicado: vira "vencido", e a equipe pode remarcar na tela.

Exemplos

Reels para amanhã às 9h, com selo de IA e primeiro comentário:

{
  "post_type": "reel",
  "items": [{"key": "publishing/9f1c.../a83b2e.mp4", "kind": "video"}],
  "caption": "Sorvetinho de melancia que o seu cachorro pode comer 🍉 Comenta PETISCO",
  "options": {"ai_generated": true, "first_comment": "A receita completa está no link da bio"},
  "scheduled_at": "2026-10-24T09:00:00",
  "source_label": "Agente de conteúdo"
}

Reels de teste com nome do áudio:

{
  "post_type": "reel",
  "items": [{"key": "publishing/.../b1.mp4", "kind": "video"}],
  "caption": "Será que ele aprova? 🐶",
  "options": {"trial": "auto", "audio_name": "Som da Loja", "ai_generated": true},
  "source_label": "Agente de conteúdo"
}

Carrossel com texto alternativo:

{
  "post_type": "carousel",
  "items": [
    {"key": "publishing/.../1.jpg", "kind": "image", "alt_text": "Cachorro caramelo segurando um picolé de banana"},
    {"key": "publishing/.../2.jpg", "kind": "image", "alt_text": "Potinho com cubos de melancia congelada"},
    {"key": "publishing/.../3.mp4", "kind": "video"}
  ],
  "caption": "5 petiscos pro calor (salva pra não esquecer)",
  "options": {"ai_generated": true},
  "source_label": "Agente de conteúdo"
}

Foto no feed ligando a automação de comentário:

{
  "post_type": "image",
  "items": [{"key": "publishing/.../foto.jpg", "kind": "image"}],
  "caption": "Comenta MELANCIA que eu te mando a receita",
  "automation_id": "id-da-automacao (pegue em GET /api/v1/page/getFlows)"
}

Story:

{
  "post_type": "story",
  "items": [{"key": "publishing/.../story.mp4", "kind": "video"}],
  "scheduled_at": "2026-10-24T19:00:00"
}

O que volta: a confirmação com o post criado, já com "status": "draft" (para aprovar) e o id dele.

{"status": "success", "data": {"id": "5d1e...", "status": "draft", "post_type": "reel", "scheduled_at": "2026-10-24T12:00:00+00:00"}}

Exemplo para quem programa:

curl -X POST https://api.postachat.com.br/api/v1/content/createDraft \
  -H "Authorization: Bearer $POSTACHAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post_type": "reel", "items": [{"key": "publishing/.../a83b2e.mp4", "kind": "video"}], "caption": "Comenta PETISCO", "source_label": "Agente de conteúdo"}'

Passo 3: acompanhar o que aconteceu

Peça a lista de posts da conta (os 100 mais novos). Dá para filtrar por situação.

curl "https://api.postachat.com.br/api/v1/content/getPosts?status=published" \
  -H "Authorization: Bearer $POSTACHAT_KEY"

O que acontece depois que alguém aprova

• O PostaChat confere a fila a cada minuto e publica na hora marcada.
• Se o Instagram falhar por instabilidade, o PostaChat tenta de novo sozinho até 3 vezes (depois de 1, 3 e 10 minutos). Só então marca como "falhou".
• Nenhum post sai duas vezes, mesmo se o Instagram demorar para responder.
• Se tiver primeiro comentário, ele sai logo depois do post. Se o Instagram recusar o comentário, o post continua no ar e a tela avisa.
• Se tiver automação, ela passa a responder os comentários desse post.
• As fotos e vídeos ficam guardados no PostaChat até 7 dias depois de publicados (o Instagram já tem a cópia dele). Arquivo enviado que nunca virou post é apagado em 2 dias.

Deu erro: o que fazer

Quando algo está errado, a resposta traz o motivo no campo detail.

Erros que aparecem depois, no campo error de um post failed (vindos do Instagram), também chegam em português. Exemplos: "Vídeo não aceito: use MP4 ou MOV (H.264 ou HEVC), de 3 segundos a 15 minutos.", "Limite da Meta: no máximo 100 posts publicados pela API a cada 24 horas.", "Sem permissão de publicar nesta conta...".

Perguntas frequentes

Dá para publicar direto, sem aprovação? Não. É de propósito: tudo que chega pela API passa por uma pessoa da equipe.

Mandei com horário e ninguém aprovou. O que acontece? Na hora marcada o post não sai. Ele vira "vencido" e continua na tela para ser remarcado.

Dá para editar ou apagar um rascunho pela API? Não. Editar, remarcar e excluir é pela tela Publicações. Se precisar mudar algo, mande um rascunho novo e avise para excluir o antigo.

O vídeo precisa estar em algum lugar público na internet? Não. Você envia o arquivo direto no Passo 1. O PostaChat guarda e entrega para o Instagram.

Posso usar o mesmo arquivo em dois posts? Envie o arquivo de novo para cada post (Passo 1). O item é apagado junto quando um dos posts é excluído, e 7 dias depois que ele é publicado; reaproveitar pode fazer o outro post falhar.

Quanto tempo o Instagram leva para processar um Reels? Normalmente de alguns segundos a poucos minutos. Se passar de 30 minutos, o post é marcado como "falhou".

Por que o horário voltou diferente do que mandei? Ele volta em UTC, o horário mundial. 12h UTC é 9h em Brasília: é o mesmo momento.

Funciona para várias contas do Instagram? Sim, mas cada conta tem a própria chave. Use a chave da conta onde o post deve sair.

Quantos posts posso mandar? O PostaChat não limita rascunhos. O Instagram limita a 100 publicações por conta a cada 24 horas (carrossel conta como 1).

Limites do Instagram

O Instagram não deixa fazer pela API: figurinha, enquete, link ou música da biblioteca no story; marcar produto; parceria paga.

Exemplo completo em Python (para agentes)

Envia um vídeo e cria o rascunho de Reels. Basta trocar o nome do arquivo e a legenda.

import os
import httpx

API = "https://api.postachat.com.br/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['POSTACHAT_KEY']}"}


def enviar(caminho: str, para: str = "feed") -> dict:
    """Passo 1: envia foto ou vídeo e devolve o item."""
    with open(caminho, "rb") as arquivo:
        r = httpx.post(
            f"{API}/content/uploadMedia",
            headers=HEADERS,
            files={"file": (os.path.basename(caminho), arquivo)},
            data={"purpose": para},
            timeout=300,  # vídeo grande demora para subir
        )
    if r.status_code != 200:
        raise RuntimeError(f"envio recusado: {r.json().get('detail')}")
    return r.json()


def criar_rascunho(tipo: str, itens: list[dict], legenda: str = "", **extras) -> dict:
    """Passo 2: cria o post para aprovar."""
    r = httpx.post(
        f"{API}/content/createDraft",
        headers=HEADERS,
        json={"post_type": tipo, "items": itens, "caption": legenda, **extras},
        timeout=60,
    )
    if r.status_code != 201:
        raise RuntimeError(f"rascunho recusado: {r.json().get('detail')}")
    return r.json()["data"]


video = enviar("R011.mp4")
post = criar_rascunho(
    "reel",
    [video],
    "Biscoito de aveia em 3 passos 🐶 Comenta PETISCO",
    options={"ai_generated": True, "first_comment": "Receita no link da bio"},
    scheduled_at="2026-10-25T09:00:00",  # 9h de Brasília
    source_label="Agente de conteúdo",
)
print("rascunho criado:", post["id"], post["status"])  # aparece em Publicações > para aprovar

Para testar sem programar

Abra o Swagger, procure o grupo "API pública: posts para aprovar", clique em uma rota, depois em Try it out. Cole a chave no campo Authorization como Bearer SUA_CHAVE, preencha e clique em Execute.

Outras coisas que a API faz

Usam a mesma chave e o mesmo cabeçalho. As respostas vêm no formato {"status": "success", "data": ...}.