Instagram Direct is a channel that allows businesses with Professional Instagram accounts to surface their story replies, direct messages, and mentions in their preferred platform. With Instagram, businesses have the opportunity to drive sales and improve customer satisfaction by having meaningful interactions in a scalable manner.
Channel overview
Instagram is a channel where customers not only engage with brands they already love but it’s also a channel that helps users discover new brands and products based on their interests. As such, businesses on Instagram focus heavily on creating the right voice for themselves through a curated collection of posts, stories, reels, and public comments. So, it’s only natural that a brand would want to be able to carry this through to the way they engage with their customers one-on-one.
This is why the Facebook API has introduced support for Instagram. They’ve taken the APIs and concepts from Facebook messenger, that are already familiar to most, and used them to unlock Instagram. It is used specifically for direct mentions originating from story replies and directly from the brand’s profile as well as being able to engage with customers who mention the brand in their story. While there’s currently a requirement that businesses engage with their customers using live agents, having API access means scaling and automating these interactions with bots is just around the corner.
Requirements
Since Instagram is currently an Early Access channel, any brand wanting to use the channel must be nominated by their Account Executive or Account Manager and be approved by Instagram. While in Early Access, Instagram is focusing specifically on accounts that already have a decent amount of volume on the channel and that the brand is also active in posting content to their account. Brands that sign up for Instagram are also committing to having a live agent available to answer all user messages within 24 hours of first being contacted.
Capabilities
Instagram supports a limited number of capabilities in its Early Access release as seen in the channel capabilities grid. Below is a detailed view of each capability.
Content Types
Action Types
Structured Messages
Delivery Events
Delivery events allow you to track deliveries of Sunshine Conversations messages to Instagram by subscribing to the conversation:message:delivery:channel webhook. Sunshine Conversations also tracks user deliveries on Instagram which let you confirm whether a message has reached the user by listening to the conversation:message:delivery:user webhook. Failures to deliver a message to Instagram or to a Instagram user can be detected by subscribing to the conversation:message:delivery:failure webhook.
The Instagram message IDs associated with each Sunshine Conversations message are available in delivery event payloads in the externalMessages property.
Configuring Instagram Direct
An Instagram business account is linked to a Facebook page which is owned by a Facebook account. A page owner can grant access to a 3rd party Facebook app, allowing it to interact with that page and instagram account on the owner’s behalf. This is how the Sunshine Conversations Instagram Direct integration works.
There are two ways to configure a new integration. If you’re integrating Sunshine Conversations with your own Facebook Page that has an Instagram business account linked, you can do so via the web dashboard. With this option you’re granting Sunshine Conversations’ own Facebook app access to your Facebook Page and Instagram business account. However, if you’re integrating Sunshine Conversations on behalf of your customer then you will need to use the Integration API.
Using the Dashboard
In this option you’re granting Sunshine Conversations access to your own Instagram business account and the Facebook Page linked. Note that your Facebook account must have Admin access to the page in question. You can check this from your Facebook page by browsing to Settings > Page Roles.
You can find the Sunshine Conversations Instagram Direct integration in the Integrations menu bar tab of the Sunshine Conversations dashboard. When you click Authenticate, you will be redirected to Facebook where you will be prompted to grant Sunshine Conversations access to interact with your Instagram business accounts and pages on your behalf.
Once your Instagram business account is connected to Sunshine Conversations, select your Instagram account and hit save. You should now be able to receive messages from your Instagram business account and reply via any of your configured business systems or with the Sunshine Conversations API.
Using the Integration API
If you’re building your own user experience for users integrating their Instagram business account with your software, this option is for you. In this scenario after you’ve obtained authorization from the Facebook account owner, you will create the Sunshine Conversations integration via the Integration API. To begin you must first have your own Facebook app with your own company name and logo. This Facebook app represents your business identity in the Facebook platform whenever you request permission to act on behalf of another Facebook user.
Quick Start
Before you submit your App Review you can get a Sunshine Conversations integration up and running quickly on one of your own Facebook Page linked to an Instagram account by issuing yourself a page access token via the Facebook dashboard. From your App settings choose Messenger > Settings > Token Generation.
Facebook App Permissions
Before you go live your app will need to request some additional Facebook permissions. These permissions grant Sunshine Conversations the ability to configure the integration with your app and successfully exchange messages with end users on Instagram. Adding these permissions will require your Facebook app to pass an App Review. The permissions subject to review are:
-
instagram_basic: Add this permission to your review request from the Permissions and Features sub-section under App Review on the Facebook dashboard. This permission is required in order to get basic information about your Instagram business account, including (but not limited to):- Instagram business account username
- Instagram business account name
- Instagram business account ID
-
instagram_manage_messages: Add this permission to your review request from the Permissions and Features sub-section under App Review on the Facebook dashboard. This permission is required to enable core functions for the Instagram Direct integration such as sending messages. -
pages_manage_metadata: Add this permission to your review request from the Permissions and Features sub-section under App Review on the Facebook dashboard. This permission allows your app to subscribe and receive webhooks about activity on your Page. See thepages_manage_metadatareference page for more information about this permission and its usage. -
pages_show_list: This permission does not require a review request, since it is included by default. It is however, required to be part of the access token to query the list of Pages that a person manages. -
human_agent: Add this permission to your review request from the Permissions and Features sub-section under App Review on the Facebook dashboard. The human agent tag is required for business replies to be delivered by Facebook between 24 hours and 7 days after the user’s last message. This permission is applied systematically by the platform to all business replies. -
public_profile: Add this permission to allow apps to view a user’s profile fields in order to authenticate them. For more information, see public_profile.
Integration Flow Overview
When a user integrates their Instagram business account with your software, the sequence will typically follow these steps:
- Obtain a user access token
- Use this token to query a list of the user’s Facebook pages that have an Instagram business account linked to it
- Present this list to the user and prompt them to choose one
- Obtain a page access token for the selected Instagram business account
- Create a new Sunshine Conversations integration using this page access token
The first step is to request a user access token. This step represents the user granting you permission to act on their behalf. This can be done in a number of ways, each with their own strengths and weaknesses that are detailed below.
User Access Token: Facebook JavaScript SDK
The easiest way to implement a user access token flow is by using the Facebook JavaScript SDK. We’ve created a GitHub sample project here that demonstrates this process end-to-end.
The first step is to embed the Facebook SDK script tag into your website. Then you’ll call FB.login(), requesting the scopes instagram_basic, instagram_manage_messages, pages_manage_metadata and pages_show_list as seen below:
FB.login((data) => {
const userAccessToken = data.authResponse.accessToken;
}, {
scope: 'manage_pages,pages_messaging'
});This will prompt the user to grant your app these requested permissions. If the user agrees, an access token will be returned to you in the FB.login() callback.
User Access Token: Build a custom OAuth flow
In this option you’ll be building an OAuth flow based on browsers redirects. The advantage with this option is that it doesn’t rely on the Facebook JavaScript SDK’s popup window. Instead, this flow redirects the user to Facebook in order grant access. A browser redirect based flow might be preferable for native apps and mobile devices.
The flow begins with redirecting the user’s browser to Facebook, where they will be shown an access grant dialog. Upon granting permission, Facebook will redirect the user back to your site using a predefined callback URL. This callback will include a code that your server side application can then exchange for an access token, using your Facebook app ID and secret. The endpoints your web service will need to implement in order to achieve this flow are detailed in the Facebook article Manually Build a Login Flow.
Page Access Token
You’ll now use the user access token obtained in the previous step to obtain a page access token. You can query the user’s pages with the /me/accounts API.
First, obtain your Facebook App ID and secret from Facebook dashboard. You’ll use these in addition to the user access token to make a server-to-server API call. You must not make this call from the user’s browser because doing so would force you to expose your App secret.
GET https://graph.facebook.com/me/accounts?
client_id=facebook_app_id
&client_secret=facebook_app_secret
&access_token=user_access_token
&limit=500The response will include a list of users’ pages and their associated page access tokens. All that’s left to do is to prompt the user to choose which one they wish to integrate and that has an Instagram business account linked to. Once the user has selected the page, you can call the [Sunshine Conversations integration API](https://docs.smooch.io
/#facebook-messenger-integration) to connect their Instagram business account with Sunshine Conversations, passing along your app id, app secret, and the page access token.
Congratulations! You’re Done!
Troubleshooting
This section describes a number of problems that commonly affect Facebook integrations and how to solve them.
Missing OAuth Permissions
During the OAuth flow described above, when presented with the authorization dialog, a Facebook page owner may select the “Choose what you allow” option to reduce the scope of access that is granted to Sunshine Conversations. If this is the case, the integration may be in a broken state. Deleting and re-creating the Instagram Direct integration may not resolve the issue because Facebook will remember the user’s chosen scope of access during subsequent OAuth flows. To resolve this issue, access must first be fully revoked from the Facebook dashboard Business Integration page.
How to enable the channel
Once approved by Instagram, you will need to navigate to the Sunshine Conversations Instagram messaging marketplace page and perform the Facebook login to connect the channel. At this time, brands will be the only customers able to integrate with Instagram via Sunshine Conversations. The one exception being ISVs that were accepted as a partner by Instagram on their own merits.
Story mentions
When a user mentions your Professional Instagram account in their story, we will pass along the webhook notifying you of this event. The webhook contains a referral link pointing to the Instagram story as well as the information required to start a conversation with the user. A Story mention webhook will only flow in if the user mentioning the business has their account set to public. Story mentions from a private account will only flow in if the business follows the said account.