Usage Guide

Overview

The Usage section of this guide provides instructions on receiving and handling Facebook Messenger conversations in Amazon Connect. Once deployment is complete, Amazon Connect flows automatically capture incoming Messenger messages and route them as chat interactions to available agents.

Pre-requisites

  • Deployment completed and CloudFormation stack successfully created
  • Facebook app configured and in development or production mode (see Setup Guide)


How Messenger Flows Are Structured

When you deploy the Facebook Messenger integration, Amazon Connect example contact flows are automatically provisioned to handle incoming messages. These flows handle the routing, logging, and delivery of Messenger conversations to agents. to add your own modifications to these flows, please export and import the flow into another flow rather than editing these example flows directly.

Finding your flows:

  1. Sign in to the AWS Console and navigate to Amazon Connect.

  2. Select your Connect instance and go to Contact Flows.

  3. Look for the following provisioned Flows/Modules:

  4. ccx-facebook-entry-example-v1 (Entry flow): The main entry point that receives incoming Messenger messages via webhook. This is the core flow that initiates the conversation routing process.

  5. ccx-agent-whisper-example-v1 (Agent whisper flow): Sets the agent as the prefered agent for persistent conversations.

  6. ccx-disconnect-example-v1 (Disconnect flow): Handles the end of the chat.

  7. ccx-fb-persistent-chat-module (Persistent chat module): Manages chat session persistence to re-hydrate conversations and attributes from previous chats.


Configuring the Entry Flow

The entry flow (ccx-facebook-entry-example-v1) is configured during CloudFormation deployment and is referenced by the inbound Lambda function that processes webhook messages from Facebook.

If you need to use a different entry flow:

  1. Go to AWS Lambda in the AWS Console.

  2. Find the ccx-inboundMessageHandlerFunction Lambda function.

  3. Go to the Configuration tab and select Environment variables.

  4. Update the CONTACT_FLOW_ID environment variable with the ID of your custom flow.

  5. Save the changes. New messages will now route through your specified flow.

Note: Ensure your custom flow is properly configured to handle incoming Messenger chat interactions before updating the Lambda environment variable.


Receiving Messenger Conversations

1. A customer sends a message to your Facebook Messenger page.

2. The message is received at your webhook URL (configured in the Facebook app settings).

3. Amazon Connect validates the message signature using your verify token.

4. The message is routed through your contact flow to an available agent's queue.

5. The agent is notified and sees: - Customer's Messenger name - Full message history from the conversation

6. The agent replies directly from Amazon Connect (via Amazon Connect Chat).

7. The reply is sent back to the customer's Messenger inbox.


Handling Conversations as an Agent

From the agent's perspective, Messenger conversations appear and behave like standard chat interactions in Amazon Connect:

1. Accept an incoming chat from the Contact Control Panel (CCP).

2. The chat interface opens with full conversation history and customer context.

3. Type replies in the chat window and send—they are automatically delivered to Messenger.

4. End the chat when the interaction is complete; the contact record is logged in Amazon Connect.


Testing Messenger Integration

Development Mode Testing (Before App Review):

1. Add test users to your Facebook app (in the app settings under Roles → Test Users).

2. Log in as a test user to your test Page.

3. Send test messages to the Page using Messenger.

4. Verify that messages appear in Amazon Connect and are routed to your queue.

5. Reply as an agent and confirm the message appears in the test user's Messenger inbox.

6. Repeat for various scenarios (e.g., multiple users, rapid messages, long conversations).

Production Testing (After App Review Approved):

1. Your app is now approved for production and live customers can message your Page.

2. Monitor initial live traffic and agent performance.

3. Track message delivery, handling times, and customer satisfaction metrics in Amazon Connect.

4. Make refinements to flows or queue assignments as needed based on real-world volume and patterns.


Monitoring & Troubleshooting

Monitor message flow:

  • Check Amazon Connect Contact Search for recent Messenger interactions.
  • Review Contact Logs to trace the path of messages through your flows.
  • Monitor CloudWatch Logs for webhook errors or Lambda function issues.

If messages are not arriving:

  • Verify webhook URL and verify token are correctly configured in your Facebook app (see Setup Guide).
  • Check that your contact flow is active and correctly routed to a queue.
  • Ensure agents are available and marked "Available" in the CCP.
  • Review AWS Secrets Manager to confirm credentials are up to date (ccx-FacebookCredentials2-<alias>).
  • Verify your Facebook app is not in sandbox or development mode without test users configured.

If messages are not being delivered to Messenger:

  • Check that agent replies are being processed by the flow.
  • Verify the Facebook Page Token is valid and has pages_messaging permission.
  • Confirm there are no AWS service limits or throttling issues.


Need Help?

For assistance with Messenger setup, flow configuration, or troubleshooting, contact Support.