Social media integration

Widget Specification

The YAML specification format used to describe provider capabilities, post types and media constraints for backend-driven widget rendering.

Overview

This document explains how to describe and define the capabilities of social media widgets (providers). The specification file defines what features are supported, which post types are available, and what constraints apply to content such as media files, text, and special features.

File format

Specifications are defined in YAML and follow a standardized structure that allows each social media provider to declare its capabilities and limitations.

Root level structure

version: 1
features:
  # Feature definitions
postTypes:
  # Post type definitions

Features section

The features section defines optional or required capabilities that can be applied to posts. Not all providers or post types may support every feature.

features:
  <featureName>:
    enabled: <boolean>
    required: <boolean>
    postTypes: [<list of post types>]
    constraint:
      min: <number>
      max: <number>

Feature properties

`enabled`

Type: boolean
Mandatory: yes
Description: indicates whether this feature is available/supported by the provider.

`required`

Type: boolean
Mandatory: yes
Description: indicates whether this feature (when enabled) is mandatory when publishing content.

`postTypes`

Type: array of strings
Mandatory: yes
Description: list of post types to which this feature applies. An empty array [] means the feature applies to no post type (effectively disabled).
Note: this array should contain post type identifiers defined in the postTypes section.

`constraint`

Type: object
Mandatory: no
Description:defines numerical or value constraints for the feature.
- min — minimum allowed value (e.g. minimum character count, minimum collaborators)
- max — maximum allowed value (e.g. maximum character count, maximum collaborators)

Feature examples

Enabled, required feature

firstComment:
  enabled: true
  required: true
  postTypes:
    - feed_post
    - reel
  constraint:
    min: 1
    max: 100

The first comment feature is supported and required for feed_post and reel post types. The comment must be between 1 and 100 characters.

Enabled, optional feature

collaboration:
  enabled: true
  required: false
  postTypes:
    - reel
  constraint:
    min: 1
    max: 10

Collaboration is supported but optional for reel post types. When provided, between 1 and 10 collaborators can be specified.

Disabled feature

title:
  enabled: false
  required: false
  postTypes: []
  constraint:
    min: 1
    max: 100

The title feature is not supported by this provider: the postTypes array is empty and enabled is false.

Post types section

The postTypes section lists all post types supported by the provider. Each post type has its own configuration for text requirements, media support and constraints.

postTypes:
  - type: <identifier>
    label: <display name>
    description: <description>
    allowTextOnly: <boolean>  # Required field
    caption:                  # Required section
      required: <boolean>
      minLength: <number>
      maxLength: <number>
    media:
      carousel: <carousel config>
      image: <image config>
      video: <video config>

Post type properties

`type`

Type: string
Mandatory: yes
Description: unique identifier for the post type (used in feature definitions), e.g. feed_post, reel, story.

`label`

Type: string
Mandatory: yes
Description: human-readable name for the post type, e.g. "Post", "Reel", "Story".

`description`

Type: string
Mandatory: yes
Description: detailed description of what this post type represents, e.g. "Single photo, video, or carousel".

`allowTextOnly`

Type: boolean
Mandatory: yes
Description: whether a post can be published with only text and no media. When false, at least one media item must be included.

Caption configuration

caption:
  required: <boolean>
  minLength: <number>
  maxLength: <number>

caption.required — whether caption/text content is mandatory for this post type.
caption.minLength — minimum number of characters required in the caption.
caption.maxLength — maximum number of characters allowed in the caption.

# Caption is required, between 1 and 1000 characters
caption:
  required: true
  minLength: 1
  maxLength: 1000

# Caption is optional, but if provided must be under 2000 characters
caption:
  required: false
  minLength: 0
  maxLength: 2000

Media configuration

The media (or mediaSpecification) section defines constraints for the different media types (carousel, image, video) that can be included in a post.

media is used for all post types to define available media types and their constraints.
A media type can be turned off by setting supported: false.
All media constraints follow the same nested structure regardless of post type.

Carousel configuration

carousel:
  supported: true
  minItems: 1
  maxItems: 10

carousel.supported — whether carousels (multiple items in one post) are supported.
carousel.minItems — minimum number of items required in a carousel.
carousel.maxItems — maximum number of items allowed in a carousel.

Image configuration

image:
  supported: <boolean>
  size:
    min: <number>
    max: <number>
    relaxed: <boolean>
  width:
    min: <number>
    max: <number>
    relaxed: <boolean>
  aspectRatio:
    min: <number>
    max: <number>
    relaxed: <boolean>
  formats:
    relaxed: <boolean>
    accepted: [<list of formats>]

image.supported — whether images are supported in this post type.
image.size — file size constraints in bytes (min, max, relaxed).
image.width — width constraints in pixels (min, max, relaxed).
image.aspectRatio — aspect ratio constraints, width/height (min, max, relaxed).
image.formats — accepted formats: relaxed (whether other formats may be accepted) and accepted (e.g. "jpeg", "png").

image:
  supported: true
  size:
    min: 1        # 1 byte
    max: 8388608  # 8MB
    relaxed: false
  width:
    min: 320      # 320px
    max: 1440     # 1440px
    relaxed: true
  aspectRatio:
    min: 0.8      # 4:5
    max: 1.91     # 16:9
    relaxed: true
  formats:
    relaxed: true
    accepted: ["jpeg"]

In this example images are supported, the file size must be between 1 byte and 8 MB, the width can be relaxed but ideally 320–1440 px, the aspect ratio can be relaxed but ideally 4:5 to 16:9, and JPEG is the primary format although others may be acceptable.

Video configuration

video:
  supported: <boolean>
  size:
    min: <number>
    max: <number>
    relaxed: <boolean>
  width: <object>
  duration: <object>
  fps: <object>
  aspectRatio: <object>
  videoBitrate: <object>
  formats:
    relaxed: <boolean>
    accepted: [<list of formats>]
  videoCodec:
    relaxed: <boolean>
    accepted: [<list of codecs>]

Video constraints can be organized in two equivalent ways: properties nested undersize, or properties at the video level (flat structure).

video.supported — whether videos are supported in this post type.
video.size — file size constraints in bytes (min, max, relaxed). Strict for most providers.
video.width — width constraints in pixels.
video.duration — duration constraints in seconds. Often a strict constraint to ensure compliance with platform limits.
video.fps — frames per second constraints.
video.aspectRatio — aspect ratio constraints (width/height).
video.videoBitrate — bitrate constraints in bits per second.
video.formats — accepted formats (e.g. "mp4", "mov").
video.videoCodec — accepted codecs (e.g. "h264", "hevc").

video:
  supported: true
  size:
    min: 1           # 1 byte
    max: 314572800   # 300MB
    relaxed: false
  width:
    min: 1
    max: 1920        # 1920px
    relaxed: true
  duration:
    min: 30          # 30s
    max: 900         # 15m
    relaxed: false
  fps:
    min: 23          # 23fps
    max: 60          # 60fps
    relaxed: true
  aspectRatio:
    min: 0.01        # 0.01:1
    max: 10          # 10:1
    relaxed: true
  videoBitrate:
    max: 26214400    # 25Mbps
    relaxed: true
  formats:
    relaxed: true
    accepted: ["mov", "mp4"]
  videoCodec:
    accepted: ["h264", "hevc"]

Understanding constraints

The relaxed property indicates whether a constraint is flexible or strict.

`relaxed: false` (strict)

The constraint must be enforced.
Content violating this constraint should be rejected or converted.
Examples: file size limits, minimum duration.
Use case: legal/technical requirements that cannot be bypassed.

`relaxed: true` (relaxed)

The constraint is preferred but flexible.
Content violating this constraint may still be accepted or converted.
Examples: aspect ratio, width, format preference.
Use case: best practices or optimization guidelines that can be worked around.

Dynamic updates by profile

Providers may allow the specification to be dynamically adjusted based on a social media profile (for example account type, permissions or feature flags). If a runtime profile changes supported features or constraints, the effective specification should reflect those changes while preserving the same schema shape.

Edit this page

Media Analysis

How media files are verified against provider requirements before a post is created.

Post Status Notifications

How users are informed about the outcome of asynchronous social media publications.