If you have issues connecting Facebook, please see the troubleshooting guide.

​
Posting to Facebook

Posting using the Facebook API requires connecting a Facebook Page. Facebook does not allow personal accounts to be connected. JSON for a basic post with a link and image to a Facebook page:
Facebook Post with Image
{
  "post": "The best FB post ever #best https://www.facebook.com", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook"]
}
  • Facebook will automatically show a preview of the link in the post unless there is an image or video included. In the above example the image will show. Removing the image will cause the link preview to show.
  • If your video doesn’t end in a known video extension such as mp4, please use the isVideo parameter. See the /post endpoint for details.
  • Facebook also supports sending media without post text. If you do not want post text included send an empty String post: "".
  • See Facebook Media Guidelines and Facebook Authorization for more information.
Facebook’s API does not support mixing images and videos in a single post. You can include multiple images OR a single video, but not both.
Available on Premium, Business, Enterprise plans.
Post Facebook Carousel images through Ayrshare’s API with the carousel body parameter.
Facebook Carousel Post
{
  "faceBookOptions": {
    "carousel": {
      // The URL of the "See More At" button - required
      "link": "URL of See More At...",
      "items": [
        // 2 min, 10 max elements in the array
        {
          "name": "Image name", // optional
          "link": "URL when image clicked", // required
          "picture": "URL of image" // required
        },
        {
          "name": "Image name",
          "link": "URL when image clicked",
          "picture": "URL of image"
        }
      ]
    }
  }
}
  • The top-level link parameter is the URL at the end of the carousel.
  • The items is an array of object containing the following values. Minimum 2 elements and max 10 elements in the items array.
  • picture - URL of the carousel image.
  • link - URL when the image is clicked.
  • name - (optional) Image displayed in each image card.
Note: Do not use the media_urls with carousel. If media_urls is used, carousels will be ignored. Please see our Facebook Carousel Guide for more information.

​
Facebook Reels

You can post a video to Facebook Reels with the following facebookOptions.
Meta enforces a limit of 30 Reels per connected Facebook Page within any 24-hour period to prevent spam and ensure platform quality. This is a rolling limit, meaning it counts the most recent 24 hours, not calendar days.
Facebook Reels Post
{
  "post": "The description of the video",
  "platforms": ["facebook"],
  "mediaUrls": ["https://img.ayrshare.com/012/reel.mp4"],
  "faceBookOptions": {
    "reels": true,
    "title": "Super title for the Reel", // optional
    "thumbNail": "https://img.ayrshare.com/012/reel-thumbnail.jpg" // optional
  }
}
  • reels: Set to true to post the video to Reels. Required if you want to post to Facebook Reels.
  • title: The title of the video with a maximum of 255 characters. Over 255 characters will be truncated. Optional.
  • thumbNail: The thumbnail (cover image) of the video. The thumbnail should a URL to a JPEG or PNG file. The thumbnail should be less than 10MB in size. Optional.
Please see the Reels API video requirements or an example of using the Facebook Reels API.
Meta occasionally has issues processing Facebook Reels for some accounts. Even though an error response may be returned, the Reel might still have been published.If you encounter errors for Facebook Reels, we recommend checking the Reel status. If the post has not been published you may try posting once more. This is often successful.You may use the URL contained in the verifyReelsUrl field to check the status. Be sure to use the same Profile Key as your original post. Wait until the time in verifyReelsIn to check the Reel status (10 minutes). If a HTTP error code of 400 is returned, the post failed and you may try the post one more time.
Facebook Reels Post Error
{
  "action": "post",
  "status": "error",
  "code": 108,
  "message": "Facebook Error: Facebook cannot process your post at this time. Please try again. ",
  "detailsData": {
    "id": "104619420979033_36930641143",
    "verifyReelsUrl": "https://api.ayrshare.com/history/36930641143?searchPlatformId=true&platform=facebook",
    "verifyReelsIn": "2024-01-26T00:07:05.170Z",
    "postUrl": "https://www.facebook.com/1046194209_36930641143",
    "reels": true
  },
  "retryAvailable": true,
  "platform": "facebook"
}

​
Facebook Stories

Publish Facebook Stories to Facebook Pages either as a photo or as a video.
  • Facebook Stories do not support post text - any text provided in the post field, including mentions, will be ignored.
  • A photo or video uploaded for a story cannot have been used in a previously published post.
  • A video story cannot exceed 60 seconds.
  • Turn on Stories Archive to be able to GET stories.
Facebook Stories Post
{
  "post": "", // Ignored by stories
  "platforms": ["facebook"],
  "mediaUrls": ["https://img.ayrshare.com/012/stories.mp4"],
  "faceBookOptions": {
    "stories": true
  }
}
Please see the Stories API image and video requirements.

​
Media Captions

Set a Facebook caption for each media image posted. Accepts an array of string caption text. Each array must correspond to a media url. E.g. [“This is my best pic”, ”😃 here is the next one”] refers to the 1st and 2nd urls in mediaUrls.
Facebook Media Captions
{
  "faceBookOptions": {
    "mediaCaptions": ["This is my best pic", "😃 here is the next one"]
  }
}

​
Location Tagging

A Facebook location tag is specified by a locationId, which is a Facebook Page ID or Facebook Page name. For example, Facebook page Id of the Guggenheim Museum is 7640348500 or Facebook page name "@guggenheimmuseum". Pages must be associated with a physical location.
Facebook Location Tagging
// Using the Facebook Page Id - must be associated with a location
{
  "faceBookOptions": {
    "locationId": 7640348500 // Guggenheim Museum Page Id
  }
}
You can look up the locationId (Page Id) with the brand endpoint. Please note that the Page must have a location listed or the locationId will return an error. Not supported on text posts, images, reels, and stories. Videos are not supported by Meta for location tagging.

​
Audience Targeting

When creating a Page post on Facebook, you have the option to limit its visibility to a specific audience using two types of targeting:
  1. Facebook Targeting: This allows you to define the audience for your post based on factors such as age, gender, location, and relationship. By setting these parameters, you can ensure that your post is shown only to people who meet the specified criteria.
  2. Facebook Feed Targeting: This option enables you to further refine the visibility of your post within the News Feeds of your targeted audience.
You can use either targeting option individually or combine them.

​
Targeting

Facebook targeting limits the audience for publishing content to specific demographics. Anyone not in these demographics will not be able to view this content. This will not override any Page-level demographic restrictions that may be in place. Available demographic fields targeting:
  • ageMin: Limit the minimum age that can view the posts. Accepted values of 13, 15, 18, 21, or 25. Other ages will be rejected.
  • countries: Also known as geofencing, you can limit the countries that can view the post. Array of country codes. The maximum number of countries that can be targeted is 25. If you need to target more than 25 countries, or restrict certain countries, please see Facebook Page Country Restrictions.
Facebook Targeting
{
    "faceBookOptions": {
        "targeting": {
            "ageMin": 18,
            "countries": ["DE", "BR"]
    }
}

​
Feed Targeting

Anyone in these Facebook feed targeting groups are more likely to see this post, others are less likely, but may still see it anyway. Use targeting, see above, if you want to guarantee the restriction. Available demographic fields for feedTargeting:
  • ageMin: Limit the minimum age that can view the posts.. Integer value 13 or higher. Default is 0.
  • ageMax: Limit the maximum age that can view the posts. Integer value 65 or lower.
  • countries: Also known as geo targeting, you can indicate the countries that should be able to view the post. Array of country codes.
  • collegeYears: Target the college graduation age to view the post. Array of integers for graduation year from college.
  • educationStatuses: Target the education status to view the post. Array of integers for targeting based on education level. Use 1 for high school, 2 for undergraduate, and 3 for alum.
  • genders: Target the gender to view the post. Array of integers for targeting specific genders. 1 targets all male viewers and 2 females. Default is to target both.
  • relationshipStatuses: Target the relationship status to view the post. Array of integers for targeting based on relationship status. Use 1 for single, 2 for ‘in a relationship’, 3 for married, and 4 for engaged. Default is all types.
Facebook Feed Targeting
{
  "feedTargeting": {
    "ageMax": 30,
    "ageMin": 26,
    "countries": ["DE", "BR"],
    "genders": [1, 2],
    "relationshipStatuses": [1, 2]
  }
}

​
Alternative Text

Add Facebook alternative text, also known as alt text, to an image or video. Facebook alt text is an accessibility feature used for additional user info and screen readers. Use the altText in the faceBookOptions object.
Facebook Alt Text
{
  "faceBookOptions": {
    // Array of Alt Texts
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
Each alt text must correspond to an image or video in the mediaUrls array. The alt text will be applied to each image in order.

​
Video Thumbnail

Set a Facebook video thumbnail (cover image). Send a remote URL of a PNG or JPG file that is the same dimensions as the video and less than 10 MB. URL should end in .png or .jpg.
Example Facebook Video Thumbnail
{
  "faceBookOptions": {
    "thumbNail": "https://octodex.github.com/images/Fintechtocat.png"
  }
}

​
Video Title

Add a Facebook video title with the title parameter.
Facebook Video Title
{
  "faceBookOptions": {
    "title": "The best video ever!"
  }
}

​
Animated GIFs

Only one mediaUrls URL is allowed in the array when posting a Facebook animated GIF. If the media URL does not end in “.gif” or ”.GIF”, set the isVideo field to true.
Facebook Animated GIF
{
  "randomPost": true,
  "platforms": ["facebook"],
  // Set to true if the GIF URL does not end in .gif or .GIF
  "isVideo": false,
  // Only one URL is allowed in the array
  "mediaUrls": ["https://img.ayrshare.com/012/cat.gif"]
}

​
Facebook Page Mentions

Available on Premium, Business, Enterprise plans.
You can mention another Facebook Page, also known as Facebook mentions or Facebook tagging, by including the Facebook Page name or Page ID in the post text. Facebook does not allow mentions or tags of personal profiles or groups. Include a mention with the following @mention: @page-name or @[page-id]

​
Mention with Page Name

An example post text with a Page name. You can find the Page name from the Facebook URL, e.g. https://www.facebook.com/Ayrshare
Facebook Page Mention with Page Name
{
  "post": "This is the best social media api by @Ayrshare"
}
Ayrshare will make a best attempt to find the matching Page based on the name, but sometimes a match cannot be found. A more reliable method is using a Page ID.

​
Mention with Page ID

An example post text with a Page ID; note the use of []. Please see below on how to find the Page ID.
Facebook Page Mention with Page ID
{
  "post": "This is the best social media api by @[738681876342836]" // Ayrshare Page ID
}
The Facebook Page ID will resolve to the matching page and notify the Page mentioned.
Use Page mentioning with caution by only mentioning Pages you are associated. You should be careful to never spam.When you mention a Page, the owner of the Page will be notified via an alert and email. If several Pages complain about you mentioning them, Facebook could ban your account. Generally you should only tag Pages that you have an established relationship with.The Facebook Page being mentioned must allow other Pages to mention/tag their Page. Mentions can be enabled in the Page’s general settings under “Others Tag this Page”.Please review the important rules on mentions.

​
Find a Facebook Page ID

​
Brand Endpoint

You can look up either a Facebook user or Facebook Page using the Brand endpoints.

​
At Facebook.com

  1. From the Facebook News Feed, click Pages in the left side menu.
  2. Click your Page name to go to your Page.
  3. Click About at the top of your Page. If you don’t see it, click More▼.
  4. Scroll down to find your Page ID below MORE INFO.
or if you want to find the ID of a page your don’t own:
  • If the Facebook Page has a URL such ashttps://www.facebook.com/ayrshare-1234567890 then the ID is 1234567890.
  • If the Facebook Page has a URL such as:
https://www.facebook.com/pages/ayrshare/123466789203 then the Page ID is the number at the end, such as 123466789203. You can test that the Page ID is correct by going to https://facebook.com/page-id and it will resolve to the Page. You can also try a 3rd party Facebook Page look up tool, which is not supported by Ayrshare, such as: https://lookup-id.com/ If all other methods fail, you can go to the Facebook page in a browser and view the page source. In Chrome, right click to select “View Source”. Then search for either owning_profile_id or profile_id to find the Page ID.
Please review the important rules on mentions.

​
Enable Page Mentions

The Page must allow mentions and tagging in posts and comments. By default this is enabled, but you can verify by logging into facebook.com and switching to your Page.
  1. Viewing as your Page, click your page’s profile image in the top right corner.
  2. Click Settings & Privacy -> Settings.
  3. In the Settings menu, click Privacy.
  4. Click Page and Tagging.
  5. Scroll down to Reviewing.
  6. Toggle settings to allow tag and mentions.

​
Meta Business Suite

​
Draft Posts

Create a Facebook draft post that appears in the Meta Business Suite Draft tab. Facebook draft posts are posts that you have started writing, but have not yet published. You can save draft posts to come back to later, or you can schedule them to be published at a later date. Add the draft parameter to faceBookOptions to send the post as a draft. Available for text, images, video, and reels posts.
Facebook Draft Post
{
  "faceBookOptions": {
    "draft": true
  }
}

​
Schedule Publish Time

Set a schedule publish time for Facebook posts that appear in the Meta Business Suite Scheduled Posts tab. Facebook scheduled posts are posts that you have created and scheduled to be published at a later date and are managed in the Meta Business Suite. This can be useful for planning your social media posts in advance, or for publishing posts at times when you know your audience is most active. Available for text, images, video, and reels posts.
The publish time must be greater than 10 minutes from the current time and within 29 days of the current date.Unless you need to manage Facebook posts in Meta Business Suite, we recommend using the standard post schedule date.
Add the scheduledPublishDate parameter to faceBookOptions to schedule a post time.
Facebook Scheduled Post
{
  "faceBookOptions": {
    "scheduledPublishDate": "2023-09-28T21:44:06Z" // Future date in UTC
  }
}
A Facebook post will automatically create a link preview of a link in the post body. However, if you want to specify either a different link or force the link preview, use the link parameter with URL of the link.
Facebook Link Preview
{
  "faceBookOptions": {
    "link": "https://www.ayrshare.com/instagram-hashtag-guide/"
  }
}
If a mediaUrls field is included in the post request, the media will be displayed instead of the link preview.

​
Facebook Ads

Facebook Ads are a way to promote your posts to a wider audience.

Facebook Ads

​
Character Limits

Please see Facebook Character Limits for more information.

​
Additional Information

​
How do I add line breaks or rich text to a Facebook post?

Facebook line breaks can be added to a post with a special new line character. Rich text, such as bold or italic lettering, can be added to a Facebook post with a few html elements.

​
Why do I see “Published by Ayrshare” on a post?

Don’t worry, it only shows in the admin view. Please see the troubleshooting guide for more information.