Instagram

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
• Requirements
• Capabilities

• Configuring Instagram Direct

  • Using the Dashboard

  • Using the Integration API

    • Quick Start
    • Facebook App Permissions
    • Integration Flow Overview
    • User Access Token: Facebook JavaScript SDK
    • User Access Token: Build a custom OAuth flow
    • Page Access Token

• Troubleshooting

  • Missing OAuth Permissions
• Delivery Events
• How to enable the channel
• Story mentions
• Conversation window

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.

Requirements

Brands that integrate their Instagram profile with Sunshine Conversations are also committing to sending a reply to all user messages within 24 hours of first being contacted. The aim is to ensure that end-users have a positive experience using this channel. Using a bot or an automated message to meet this commitment is permitted.

Capabilities

Instagram currently supports a limited number of capabilities as seen in the channel capabilities grid however, they are working hard to introduce many of the features we have come to expect from a social channel. Below is a detailed view of each capability.

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 the pages_manage_metadata reference 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:

1. Obtain a user access token
2. Use this token to query a list of the user’s Facebook pages that have an Instagram business account linked to it
3. Present this list to the user and prompt them to choose one
4. Obtain a page access token for the selected Instagram business account
5. 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 flow your web service will need to implement in order to achieve this flow are detailed in the Facebook article Manually Build a Login Flow; be sure to use the appropriate Instagram OAuth endpoints.

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=500

The 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 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

Navigate to the Sunshine Conversations Instagram messaging marketplace page and perform the Facebook login to connect the channel. At this time, not all brands will be able to connect via Instagram’s APIs, but as the channel opens up, more and more brands will be granted access. ISVs that have gone through app review with Facebook for the necessary permissions should be able to start enabling their brands as well.

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 conversation referral 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 said account.

Conversation window

Just like with Facebook Messenger, Instagram Direct follows a 7 days conversation window. This means that from a user’s last message, the business will have 7 days to reply to the message after-which the conversation will be closed until the user sends a new message to the brand.