Buffer

¿Qué hace Buffer?

Accede a la API GraphQL de Buffer con autenticación gestionada. Programa y gestiona publicaciones en redes sociales a través de Instagram, Facebook, Twitter, LinkedIn, TikTok y más.

Inicio Rápido

# Obtén información de la cuenta con organizaciones
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/

Buffer utiliza un único endpoint GraphQL. Todas las consultas y mutaciones se envían como solicitudes POST a este endpoint.

Autenticación

Todas las solicitudes requieren la clave API de Maton en el encabezado Authorization:

Authorization: Bearer $MATON_API_KEY

Variable de Entorno: Establece tu clave API como MATON_API_KEY:

export MATON_API_KEY="TU_CLAVE_API"

Cómo Obtener tu Clave API

1. Inicia sesión o crea una cuenta en maton.ai
2. Ve a maton.ai/settings
3. Copia tu clave API

Gestión de Conexiones

Gestiona tus conexiones de Buffer en https://ctrl.maton.ai.

Listar Conexiones

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

Crear Conexión

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

Obtener Conexión

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

Respuesta:

{
  "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"
  }
}

Eliminar Conexión

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

Especificar Conexión

Si tienes múltiples conexiones de Buffer, especifica cuál usar con el encabezado 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

Si se omite, la pasarela utiliza la conexión activa predeterminada (la más antigua).

Referencia de la API

Obtener Cuenta

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

Respuesta:

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

Obtener Organizaciones

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

Respuesta:

{
  "data": {
    "account": {
      "organizations": [
        {
          "id": "69846f7479b75e6487fa3484",
          "name": "Mi Organización",
          "channels": [
            {
              "id": "canal123",
              "name": "Mi Twitter",
              "service": "twitter",
              "avatar": "https://...",
              "isDisconnected": false
            }
          ]
        }
      ]
    }
  }
}

Obtener Canales

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

Obtener un Solo Canal

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": "canal123"
    }
}).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 Publicaciones

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": "canal123",
        "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 del Estado de la Publicación:

• draft - Guardado como borrador
• scheduled - Programado para publicación
• sent - Publicado
• failed - Falló al publicar

Obtener una Sola Publicación

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

Crear Publicación

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": "canal123",
            "text": "¡Hola desde la API de 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 (obligatorio): ID del canal de destino
• text: Contenido de la publicación
• schedulingType (obligatorio): "scheduled", "draft" o "now"
• dueAt: Fecha y hora ISO 8601 para publicaciones programadas
• mode (obligatorio): "queue" o "share"
• assets: Archivos multimedia adjuntos
• tagIds: Etiquetas de contenido
• metadata: Opciones específicas de la plataforma (consulta la sección Metadatos de Plataforma)
• ideaId: Vincula la publicación a una idea existente
• draftId: Crea a partir de un borrador existente
• source: Origen de la publicación
• aiAssisted: Indica si la IA ayudó a crear el contenido
• saveToDraft: Guardar como borrador en lugar de programar

Crear Publicación con Metadatos de 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": "id_canal_instagram",
            "text": "¡Mira nuestra última publicación! #fotografía",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "instagram": {
                    "type": "post",
                    "firstComment": "¡Síguenos para más!",
                    "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

Crear Hilo de 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": "id_canal_twitter",
            "text": "Primer tuit del hilo",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "twitter": {
                    "thread": [
                        {"text": "Segundo tuit del hilo"},
                        {"text": "Tercer tuit del hilo"}
                    ]
                }
            }
        }
    }
}).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

Crear Publicación de LinkedIn con Enlace

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": "id_canal_linkedin",
            "text": "¡Descubre nuestro nuevo artículo!",
            "schedulingType": "scheduled",
            "dueAt": "2026-03-15T14:00:00Z",
            "mode": "queue",
            "metadata": {
                "linkedin": {
                    "linkUrl": "https://ejemplo.com/articulo",
                    "linkTitle": "Título del Artículo",
                    "linkDescription": "Descripción del artículo.",
                    "linkImageUrl": "https://ejemplo.com/imagen.png"
                }
            }
        }
    }
}).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

Actualizar Publicación

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation UpdatePost($input: UpdatePostInput!) {
        updatePost(input: $input) {
            ... on Post { id text status }
            ... on InvalidInputError { message }
            ... on NotFoundError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "id": "post123",
            "text": "Texto actualizado",
            "dueAt": "2026-03-16T10:00:00Z",
            "assets": [],
            "tagIds": []
        }
    }
}).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

Eliminar Publicación

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation DeletePost($input: DeletePostInput!) {
        deletePost(input: $input) {
            ... on Deleted { id }
            ... on NotFoundError { message }
            ... on UnauthorizedError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "id": "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

Listar Ideas

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    query GetIdeas($organizationId: OrganizationId!, $first: Int) {
        ideas(organizationId: $organizationId, first: $first) {
            id
            title
            column
            createdAt
            updatedAt
            post {
                id
                text
                status
            }
        }
    }
    """,
    "variables": {
        "organizationId": "69846f7479b75e6487fa3484",
        "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

Crear Idea

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation CreateIdea($input: CreateIdeaInput!) {
        createIdea(input: $input) {
            ... on Idea {
                id
                title
                column
                createdAt
            }
            ... on InvalidInputError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "organizationId": "69846f7479b75e6487fa3484",
            "title": "¡Nueva idea de contenido!"
        }
    }
}).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

Metadatos de Plataforma

Los metadatos de plataforma te permiten configurar opciones específicas de la red social al crear publicaciones.

Instagram

{
  "instagram": {
    "type": "post",
    "firstComment": "Texto del primer comentario",
    "shouldShareToFeed": true
  }
}

Instrucciones Especiales: Para publicaciones en Instagram, la API espera metadatos de plataforma. Siempre incluye el objeto metadata con instagram al crear publicaciones para un canal de Instagram. Usa type: "post" para publicaciones regulares. Si se necesitan funciones como Reels o Historias, la API puede devolver errores de validación.

Twitter

{
  "twitter": {
    "thread": [
      {"text": "Segundo tuit"},
      {"text": "Tercer tuit"}
    ]
  }
}

LinkedIn

{
  "linkedin": {
    "linkUrl": "https://ejemplo.com/enlace",
    "linkTitle": "Título del Enlace",
    "linkDescription": "Descripción del enlace.",
    "linkImageUrl": "https://ejemplo.com/imagen.png"
  }
}

Límites de Velocidad y Restricciones de Buffer

La pasarela Maton se encarga de la limitación de velocidad de manera automática. Cuando la API de Buffer devuelve un error de límite de velocidad, la pasarela reintenta automáticamente la solicitud hasta que tenga éxito.

Actualizar Cola

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "query": """
    mutation UpdateQueue($input: UpdateQueueInput!) {
        updateQueue(input: $input) {
            ... on Queue {
                id
                channel {
                    id
                    name
                }
                isPaused
            }
            ... on NotFoundError { message }
        }
    }
    """,
    "variables": {
        "input": {
            "channelId": "canal123",
            "isPaused": 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

Manejo de Errores

La API de GraphQL devuelve errores de las siguientes maneras:

• Errores del protocolo GraphQL estándar
• Tipos de unión con interfaces de error como InvalidInputError, NotFoundError, UnauthorizedError

Siempre verifica si hay errores en el nivel de GraphQL y maneja los tipos de error específicos en las respuestas de mutación.