Buffer

O que Buffer faz?

Acesse a API GraphQL do Buffer com autenticação gerenciada. Agende e gerencie postagens em redes sociais como Instagram, Facebook, Twitter, LinkedIn, TikTok e outras.

Início Rápido

# Obter informações da conta com organizações
python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": "query { account { id email organizations { id name } } }"
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

URL Base

https://gateway.maton.ai/buffer/

O Buffer usa um único endpoint GraphQL. Todas as consultas e mutações são enviadas como requisições POST para este endpoint.

Autenticação

Todas as requisições exigem a chave de API do Maton no cabeçalho Authorization:

Authorization: Bearer $MATON_API_KEY

Variável de Ambiente: Defina sua chave de API como MATON_API_KEY:

export MATON_API_KEY="SUA_CHAVE_API"

Obtendo sua Chave de API

1. Faça login ou crie uma conta em maton.ai
2. Acesse maton.ai/settings
3. Copie sua chave de API

Gerenciamento de Conexões

Gerencie suas conexões do Buffer em https://ctrl.maton.ai.

Listar Conexões

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=buffer&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Conexão

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'buffer'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obter Conexão

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resposta:

{
  "connection": {
    "connection_id": "a71282a3-52be-473d-9273-22b4546dc146",
    "status": "ACTIVE",
    "creation_time": "2026-03-12T00:18:28.327860Z",
    "last_updated_time": "2026-03-12T00:18:42.818009Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "buffer",
    "metadata": {},
    "method": "API_KEY"
  }
}

Excluir Conexão

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Especificando Conexão

Se você tiver várias conexões do Buffer, especifique qual usar com o cabeçalho Maton-Connection:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({"query": "query { account { id } }"}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', 'a71282a3-52be-473d-9273-22b4546dc146')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Se omitido, o gateway usará a conexão ativa padrão (a mais antiga).

Referência da API

Obter Conta

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query {
        account {
            id
            email
            name
            avatar
            timezone
            createdAt
            preferences {
                timeFormat
                startOfWeek
            }
        }
    }
    """
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resposta:

{
  "data": {
    "account": {
      "id": "69846f7479b75e6487fa3482",
      "email": "[email protected]",
      "name": "João Silva",
      "avatar": "https://...",
      "timezone": "America/New_York",
      "createdAt": "2024-01-15T10:30:00Z",
      "preferences": {
        "timeFormat": "12h",
        "startOfWeek": "sunday"
      }
    }
  }
}

Obter Organizações

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query {
        account {
            organizations {
                id
                name
                channels {
                    id
                    name
                    service
                    avatar
                    isDisconnected
                }
            }
        }
    }
    """
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resposta:

{
  "data": {
    "account": {
      "organizations": [
        {
          "id": "69846f7479b75e6487fa3484",
          "name": "Minha Organização",
          "channels": [
            {
              "id": "channel123",
              "name": "Meu Twitter",
              "service": "twitter",
              "avatar": "https://...",
              "isDisconnected": false
            }
          ]
        }
      ]
    }
  }
}

Obter Canais

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetChannels($organizationId: OrganizationId!) {
        channels(organizationId: $organizationId) {
            id
            name
            service
            displayName
            avatar
            timezone
            isDisconnected
            isQueuePaused
            postingSchedule {
                days
                times
            }
        }
    }
    """,
    "variables": {
        "organizationId": "69846f7479b75e6487fa3484"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Obter Canal Único

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetChannel($channelId: ChannelId!) {
        channel(channelId: $channelId) {
            id
            name
            service
            displayName
            avatar
            timezone
            postingSchedule {
                days
                times
            }
            postingGoal {
                postsPerWeek
                progress
            }
        }
    }
    """,
    "variables": {
        "channelId": "channel123"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Listar Postagens

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetPosts($channelId: ChannelId!, $status: PostStatus, $first: Int) {
        posts(channelId: $channelId, status: $status, first: $first) {
            edges {
                node {
                    id
                    text
                    status
                    createdAt
                    dueAt
                    sentAt
                    channelService
                }
            }
            pageInfo {
                hasNextPage
                endCursor
            }
        }
    }
    """,
    "variables": {
        "channelId": "channel123",
        "status": "scheduled",
        "first": 10
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Valores de Status de Postagem:

• draft - Salvo como rascunho
• scheduled - Agendado para publicação
• sent - Publicado
• failed - Falha ao publicar

Obter Postagem Única

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetPost($postId: PostId!) {
        post(id: $postId) {
            id
            text
            status
            createdAt
            dueAt
            sentAt
            author {
                name
                email
            }
            channel {
                id
                name
                service
            }
            assets {
                id
                url
                type
            }
        }
    }
    """,
    "variables": {
        "postId": "post123"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Postagem

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post {
                id
                text
                status
                dueAt
            }
            ... on InvalidInputError {
                message
            }
            ... on UnauthorizedError {
                message
            }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "channel123",
            "text": "Olá da API do Buffer!",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue"
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Campos de CreatePostInput:

• channelId (obrigatório): ID do canal de destino
• text: Conteúdo da postagem
• schedulingType (obrigatório): "scheduled", "draft" ou "now"
• dueAt: Data e hora ISO 8601 para postagens agendadas
• mode (obrigatório): "queue" ou "share"
• assets: Anexos de mídia
• tagIds: Tags de conteúdo
• metadata: Opções específicas da plataforma (consulte a seção Metadados da Plataforma)
• ideaId: Vincular postagem a uma ideia existente
• draftId: Criar a partir de um rascunho existente
• source: Origem da postagem
• aiAssisted: Se a IA ajudou na criação do conteúdo
• saveToDraft: Salvar como rascunho em vez de agendar

Criar Postagem com Metadados do Instagram

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "instagram_channel_id",
            "text": "Confira nossa postagem mais recente! #fotografia",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "instagram": {
                    "type": "post",
                    "firstComment": "Siga-nos para mais!",
                    "shouldShareToFeed": True
                }
            }
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Thread no Twitter

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "twitter_channel_id",
            "text": "Primeiro tweet da thread",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "twitter": {
                    "thread": [
                        {"text": "Segundo tweet da thread"},
                        {"text": "Terceiro tweet da thread"}
                    ]
                }
            }
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Postagem no LinkedIn com Link

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "linkedin_channel_id",
            "text": "Nosso novo artigo de blog!\n\nConfira nossas últimas ideias sobre tecnologia.",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T16:00:00Z",
            "mode": "queue",
            "metadata": {
                "linkedin": {
                    "link": {
                        "url": "https://exemplo.com/blog-post",
                        "title": "Título do Artigo",
                        "description": "Breve descrição do artigo"
                    }
                }
            }
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Postagem de Vídeo no TikTok

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "tiktok_channel_id",
            "text": "Confira este vídeo incrível!",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T18:00:00Z",
            "mode": "queue",
            "assets": [
                {
                    "url": "https://exemplo.com/video.mp4",
                    "type": "video"
                }
            ],
            "metadata": {
                "tiktok": {
                    "privacyLevel": "public",
                    "allowDuet": True,
                    "allowStitch": True,
                    "allowComment": True
                }
            }
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Atualizar Postagem

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation UpdatePost($input: UpdatePostInput!) {
        updatePost(input: $input) {
            ... on Post {
                id
                text
                status
                dueAt
            }
            ... on InvalidInputError {
                message
            }
            ... on UnauthorizedError {
                message
            }
        }
    }
    """,
    "variables": {
        "input": {
            "postId": "post123",
            "text": "Texto atualizado da postagem",
            "dueAt": "2026-03-16T14:00:00Z"
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Excluir Postagem

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request(
    'https://gateway.maton.ai/buffer/',
    data=json.dumps({
        "query": """
        mutation ($input: DeletePostInput!) {
            deletePost(input: $input) {
                ... on DeletePostResult { success }
                ... on InvalidInputError { message }
                ... on UnauthorizedError { message }
            }
        }
        """,
        "variables": {
            "input": {
                "postId": "post123"
            }
        }
    }).encode(),
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Listar Ideias

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetIdeas($organizationId: OrganizationId!) {
        ideas(organizationId: $organizationId) {
            id
            text
            channel {
                id
                name
                service
            }
            createdAt
            updatedAt
        }
    }
    """,
    "variables": {
        "organizationId": "69846f7479b75e6487fa3484"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Criar Ideia

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreateIdea($input: CreateIdeaInput!) {
        createIdea(input: $input) {
            ... on Idea {
                id
                text
                channel {
                    id
                    name
                }
            }
            ... on InvalidInputError {
                message
            }
        }
    }
    """,
    "variables": {
        "input": {
            "organizationId": "69846f7479b75e6487fa3484",
            "text": "Ideia para uma postagem sobre nosso novo produto",
            "channelId": "channel123"
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Tratamento de Erros

Tipos de Erros

A API retorna tipos de erros específicos na resposta GraphQL:

• InvalidInputError: Dados de entrada inválidos
• UnauthorizedError: Permissões insuficientes
• RateLimitError: Limite de taxa excedido
• ChannelError: Problema específico do canal
• InternalError: Erro interno do servidor

Exemplo de Tratamento de Erros

import urllib.request, os, json, sys

data = json.dumps({
    "query": """
    mutation ($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
            ... on UnauthorizedError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "invalido",
            "text": "Teste",
            "schedulingType": "now",
            "mode": "queue"
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
try:
    resp = json.load(urllib.request.urlopen(req))
    if 'errors' in resp:
        sys.stderr.write(f"Erro GraphQL: {resp['errors']}\n")
    else:
        result = resp.get('data', {}).get('createPost', {})
        if 'message' in result:
            sys.stderr.write(f"Erro: {result['message']}\n")
        else:
            print(json.dumps(result, indent=2))
except urllib.error.HTTPError as e:
    sys.stderr.write(f"Erro HTTP: {e.code} - {e.reason}\n")
EOF

Exemplos de Postagens com Mídia

Postagem com Imagem

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation ($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "channel123",
            "text": "Postagem com imagem!",
            "schedulingType": "draft",
            "mode": "queue",
            "assets": [
                {
                    "url": "https://exemplo.com/imagem.jpg",
                    "type": "image"
                }
            ]
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Postagem no LinkedIn Carrossel

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation ($input: CreatePostInput!) {
        createPost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "linkedin_channel_id",
            "text": "Confira nosso carrossel!",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "linkedin": {
                    "carousel": [
                        {
                            "url": "https://exemplo.com/slide1.jpg",
                            "type": "image",
                            "altText": "Primeiro slide mostrando dados"
                        },
                        {
                            "url": "https://exemplo.com/slide2.jpg",
                            "type": "image",
                            "altText": "Segundo slide com gráfico"
                        }
                    ]
                }
            }
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/buffer/', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Limites de Taxa

• 100 requisições por minuto por chave de API
• As respostas incluem cabeçalhos de limite de taxa:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Boas Práticas

• Use consultas GraphQL específicas: Solicite apenas os campos necessários
• Agrupe atualizações: Evite múltiplas requisições para a mesma postagem
• Cotação automática: Deixe mode como "queue" para que o Buffer otimize o timing de postagem
• Validação: Sempre verifique erros nas respostas, especialmente InvalidInputError

Notas Adicionais

• Zonas Horárias: Todos os campos dueAt devem estar no formato ISO 8601 (ex: 2026-03-15T14:00:00Z)
• Estado da Fila: Verifique isQueuePaused nos canais para ver se a fila de postagem está ativa
• Metadados da Plataforma: Certos campos de metadados são específicos de cada plataforma e podem ser ignorados se não forem suportados
• Conteúdo Gerado por IA: Defina aiAssisted: true ao usar texto gerado por IA para postagens