# Link Posts

Share URLs with rich previews (title, description, image, and call-to-action) across your social networks via the Publer API.

### Overview <a href="#overview" id="overview"></a>

Link posts display a URL preview alongside optional caption text. You control metadata (title, description, images, CTA) to enhance engagement.

### Key Features

* Rich previews with title, description, and image
* Custom call-to-action buttons (e.g., `LEARN_MORE`, `SIGN_UP`)
* Platform-specific metadata overrides
* Schedule or publish immediately

### Platform Support

<table><thead><tr><th width="160.1873779296875">Network</th><th width="255.6014404296875">Preview Elements</th><th>Notes</th></tr></thead><tbody><tr><td>Facebook</td><td>Title, description, images, CTA</td><td>Full link card support</td></tr><tr><td>LinkedIn</td><td>Title, description, images, CTA</td><td>Full link card support</td></tr><tr><td>Twitter/X</td><td>Automatic card preview</td><td>Metadata driven by Twitter Card tags</td></tr><tr><td>Pinterest</td><td>Custom images</td><td>Requires uploaded images in <code>media</code></td></tr><tr><td>Telegram</td><td>Title, description</td><td>Native link preview</td></tr><tr><td>Mastodon</td><td>Title, description</td><td>Native link preview</td></tr><tr><td>Threads</td><td>Title, description</td><td>Native link preview</td></tr><tr><td>Bluesky</td><td>Title, description</td><td>Native link preview</td></tr></tbody></table>

### Step 1: Extract Link Metadata

Before scheduling a link post, you can extract rich metadata from any URL using the `/posts/links` endpoint. This step is optional but highly recommended for accurate previews.

## Extract Link Metadata

> Extracts metadata from a URL including title, description, images, and more. Useful for previewing links before creating a post.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Posts","description":"Endpoints for managing social media posts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/posts/links":{"post":{"summary":"Extract Link Metadata","description":"Extracts metadata from a URL including title, description, images, and more. Useful for previewing links before creating a post.","tags":["Posts"],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"object","properties":{"title":{"type":"string","description":"Title of the webpage"},"description":{"type":"string","description":"Meta description of the webpage"},"url":{"type":"string","description":"The normalized URL"},"original_url":{"type":"string","description":"The URL as provided by the user"},"images":{"type":"array","description":"Array of image URLs found on the page","items":{"type":"string"}},"favicon":{"type":"string","description":"URL to the site's favicon"},"provider_display":{"type":"string","description":"The hostname of the URL"},"type":{"type":"string","description":"Type of the response, typically 'link' or 'error' if extraction fails","enum":["link","error"]}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - Invalid URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}},"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The URL to extract metadata from"}},"required":["url"]}}}}}}}}
```

**Use this extracted metadata to build your link post payload.**

### Step 2: Create or Schedule a Link Post

Use the unified scheduling endpoint (`/posts/schedule`) or the immediate-publish endpoint (`/posts/schedule/publish`):

```json
{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "link",
            "text": "This is the link post type",
            "link": {
              "url": "http://publer.com",
              "provider_display": "publer.com",
              "description": "Boost your social media strategy with Publer’s suite of tools. Manage multiple accounts, schedule posts, collaborate with your team, and analyze performance—all in one place.",
              "title": "Powerful Social Media Management & Scheduling Tools | Publer",
              "images": [
                "https://framerusercontent.com/assets/20xDElBhD9Xg3L7Cx7jVMwL56FU.png",
                "https://framerusercontent.com/images/OVMI4DbyRxf9neKFkqKesfnSlHE.png",
                "https://framerusercontent.com/images/ShxTAH03BsTSB29AeYZzpPZqi8.jpg",
                "https://framerusercontent.com/images/iuLpS9a0syZanung3ZFGrbYXTKM.jpg",
                "https://framerusercontent.com/images/d7Gg6Hvachd0DuRzXGKoB1szAl4.jpg"
              ],
              "default_image": 0,
              "call_to_action": "LEARN_MORE",
              "phone_number": ""
            }
          }
        },
        "accounts": [
          {
            "id": "63c675b54e299e9cf2b667ea",
            "scheduled_at": "2025-05-24T23:18+02:00"
          }
        ]
      }
    ]
  }
}
```

### Parameters

<table><thead><tr><th width="370.24072265625">Field</th><th width="77.604736328125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>bulk.state</code></td><td>string</td><td><code>scheduled</code>, <code>publish</code>, or a draft state</td></tr><tr><td><code>networks.{provider}.type</code></td><td>string</td><td>Must be <code>"link"</code></td></tr><tr><td><code>networks.{provider}.text</code></td><td>string</td><td>Caption or message to accompany the link (optional)</td></tr><tr><td><code>networks.{provider}.link.url</code></td><td>string</td><td>The target URL</td></tr><tr><td><code>networks.{provider}.link.title</code></td><td>string</td><td>Preview title (overrides fetched metadata)</td></tr><tr><td><code>networks.{provider}.link.description</code></td><td>string</td><td>Preview description (overrides fetched metadata)</td></tr><tr><td><code>networks.{provider}.link.images</code></td><td>array</td><td>Array of image URLs for the preview (overrides fetched metadata)</td></tr><tr><td><code>networks.{provider}.link.default_image</code></td><td>integer</td><td>Index (0-based) of the default image in the <code>images</code> array</td></tr><tr><td><code>networks.{provider}.link.call_to_action</code></td><td>string</td><td>CTA button type (e.g., <code>LEARN_MORE</code>, <code>SIGN_UP</code>)</td></tr><tr><td><code>accounts[].id</code></td><td>string</td><td>Target account identifier</td></tr><tr><td><code>accounts[].scheduled_at</code></td><td>string</td><td>ISO 8601 timestamp for scheduling (omit to publish immediately)</td></tr></tbody></table>

> **Note:** You can also include `original_title`, `original_description`, and `original_images` if you pre‐fetch metadata yourself, but only the `link.*` fields above are required.

### Workflow

1. **Extract Metadata**\
   Use `/posts/links` to fetch title, description, and images from your target URL.
2. **Compose Metadata**\
   Define `url`, `title`, `description`, and `images` in the `link` object.
3. **Set Caption**\
   Add optional `text` to introduce or contextualize the link.
4. **Choose Default Image**\
   Use `default_image` to highlight your preferred preview image.
5. **Schedule or Publish**
   * For future posts: include `scheduled_at` under `accounts`.
   * For immediate posting: call `/posts/schedule/publish` or omit `scheduled_at`.

### Best Practices

* **Provide Complete Metadata**: Supply title, description, and images for compelling previews.
* **Optimize Image Dimensions**: Match each network’s recommended preview size for best display.
* **Use Clear CTAs**: Select a relevant `call_to_action` to guide user action.

### Related Topics

* [Media Handling](https://publer.com/docs/posting/create-posts/media-handling)
* [Content Types](https://publer.com/docs/posting/create-posts/content-types)
* [Publishing Methods](https://publer.com/docs/posting/create-posts/publishing-methods)