How Behold works

Behold is organized around two primary concepts: sources and feeds. In simple terms, a source is a where Instagram posts come from and a feed is how they are output.

Sources

There are two types of sources: basic and advanced. A basic source represents an authorized connection to a single Instagram account. An advanced source is connected to a Facebook user or Business Portfolio, and provides access to one or more Instagram accounts. Learn more here.

Feeds

A feed is an auto-updated collection of posts from a single Instagram account or a set of hashtags, output in a specific format.

Every feed is associated with a source, which grants access to the posts of a single Instagram account. You can have any number of sources connected to your account, and any number of feeds may access posts through a given source.

For the visual learners out there, here’s a simplified diagram showing the basic concept:

Integrating Behold with your app

Using Behold with your application involves four related processes:

1. Connecting user Instagram accounts
2. The Admin REST API
3. Receiving notifications via webhook
4. Consuming / displaying feeds

Connecting to Instagram

Every Behold account has a unique auth URL (e.g. https://behold.link/YOUR_AUTH_ID). Whenever anyone visits this URL they will be directed through an Instagram OAuth flow. They will be asked to grant access to their Instagram, and a new source will be added to your account. They do not need a Behold account to complete this process. You can find your auth URL by clicking “Add source” in your Behold dashboard.

By default your auth link will create a basic source. To authorize an advanced source instead, add either type=bp or type=fb as query params to the auth URL to connect via business portfolio or Facebook account respectively.

Custom Source IDs

You may add a custom identifier to sources by appending a customId param to your auth URL. The custom ID will be associated with any source connected using this URL, and will be returned in subsequent webhooks and API responses via the customId attribute. This is useful for associating sources with users in your system. Custom IDs may be up to 64 characters long and must contain only numbers, letters, underscores and hyphens.

customId is an immutable attribute. It is set the first time a source is connected, and then cannot be changed except by deleting the source and reconnecting it.

Auth URL Example

https://behold.link/YOUR_AUTH_ID?type=bp&customId=INTERNAL_ID

In this example, users will be directed to authorize access to one or more Instagram accounts via Facebook Business Portfolio (because of the type=bp). When this is done, a source will be created in your account with the customId attribute set to INTERNAL_ID.

Token Invalidation

The access token associated with a source can be invalidated for a number of reasons (e.g. Instagram password change). We refer to this as a source being “disconnected.” If that happens, the source needs to be reconnected by having the account owner visit your auth link and follow the same procedure as when the source was originally connected.

Feeds associated with a disconnected source will continue to function, but won’t update as new posts are published.

Branding

On the developer settings page of the Behold dashboard you can upload an app icon and input a name for your company/app. This will be displayed alongside the Behold logo during the auth process. The uploaded logo should be an icon that fits well into a circle.

If you activate the Show auth interstitial switch, users will be shown a screen like this before authorizing:

The Admin API

The Behold Admin API follows REST principles. It has predictable URLs, accepts JSON-encoded request bodies, uses standard HTTP response codes, bearer authentication, and verbs.

The API can be used to read and delete the sources in your account and perform CRUD operations on your feeds. For more information see the API reference.

Webhooks

You can subscribe to receive events via webhook. There are number of events available, but the most common use is to handle sources being disconnected from Instagram (the source.updated event will trigger in that case). Learn more in the webhooks reference.

Displaying feeds

Feeds are available to the API in two varieties: JSON feeds and widget feeds.

JSON feeds output an array of posts available at feeds.behold.so/FEED_ID, like so:

https://feeds.behold.so/zFgp2Jbbk23Ovf1ZUOhq

Just GET that url and you’re ready to go. Build whatever you’d like.

Widget feeds are used by setting the feed-id on our embedded JS widget. We also have official components available for most popular libraries and frameworks.

Have questions?

Get in touch! We’re happy to answer any questions you have, or provide a demo: sales@behold.so.