# 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](/docs/posting/create-posts/media-handling.md)
* [Content Types](/docs/posting/create-posts/content-types.md)
* [Publishing Methods](/docs/posting/create-posts/publishing-methods.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://publer.com/docs/posting/create-posts/content-types/link-posts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.