How the message streaming APIs work Step 1: Create a standard SNS topic Step 2: Initiate the chat contact Step 3: Enable message streaming on the contact Step 4: Create the participant connection Next steps

Enable real-time chat message streaming in Connect Customer

Connect Customer Chat provides APIs that you can use to subscribe to a real-time stream of chat messages. Using these APIs, you can:

Stream chat messages in real time when a new chat contact is created.
Extend the current Connect Customer Chat functionality to support use cases like building integrations with SMS solutions and third-party messaging applications, enabling mobile push notifications, and creating analytics dashboards to monitor and track chat message activity.

Note

This page describes how to subscribe to an SNS endpoint for real-time streaming of chat messages in Connect Customer. If you're trying to enable message streaming for conversational AI interactions in Connect Customer, see Enable message streaming for AI-powered chat.

How the message streaming APIs work

The Connect Customer message streaming APIs are triggered when certain events occur within an Connect Customer Chat contact. For example, when a customer sends a new chat message, the event sends a payload to a specified endpoint containing data about the message that was just sent. Messages are published using Amazon Simple Notification Service (Amazon SNS) to a specific endpoint.

This topic describes how to set up real-time message streaming using Connect Customer and Amazon SNS. The steps are:

Use the Amazon SNS console to create a new standard SNS topic and set up the messages.
Call the StartChatContact API to initiate the chat contact.
Call the StartContactStreaming API to initiate message streaming.
Call the CreateParticipantConnection API to create the participant's connection.

Move message streaming and participant connection into StartChatContact

When you create the chat, you can move some of this work into Step 2: Initiate the chat contact. Two optional members on StartChatContact do this: ChatStreamingConfiguration and ConnectionTypes. They are independent. Set one, both, or neither.

Set ChatStreamingConfiguration and you can skip Step 3: Enable message streaming on the contact. Connect Customer starts message streaming when it creates the chat. The response returns StreamingId.

Set ConnectionTypes to WEBSOCKET and you can skip Step 4: Create the participant connection. The response returns a websocket URL, and your client connects to it. A response that returns only a connection token does not connect the participant, so that step still applies.

Step 1: Create a standard SNS topic

Go to the Amazon SNS console.
Create a SNS topic in your AWS account. In the Details section, for Type, choose Standard, enter a name for the topic, and then choose Create topic.

Note
Currently, the message streaming APIs only support standard SNS for real-time streaming of messages. They don't support Amazon SNS FIFO (first in, first out) topics.
After you create the topic, its Amazon Resource Name (ARN) is displayed in the Details section. Copy the topic ARN to the clipboard. Use the topic ARN in the next step and in Step 3: Enable message streaming on the contact. If you set ChatStreamingConfiguration when you create the chat, use the topic ARN there instead.

The topic ARN looks similar to the following example:
```
arn:aws:sns:us-east-1:111122223333:MyTopic                                
                           
```

Choose the Access policy tab, choose Edit, and then add a resource-based policy on the SNS topic so that Connect Customer has permission to publish to it. Following is a sample SNS policy that you can copy and paste into the JSON editor, and then customize with your values:

Note

The default Access policy comes with conditions applied to sourceOwner such as:


"Condition": {
        "StringEquals": {
          "AWS:SourceOwner": "921772911154"
        }
      }

Make sure you remove it and replace with SourceAccount, for example:


"Condition":{
            "StringEquals":{
               "aws:SourceAccount":"YOUR_AWS_ACCOUNT_ID"
            },
            "ArnEquals":{
               "aws:SourceArn":"YOUR_CONNECT_INSTANCE_ARN"
            }
         }

This prevents a cross-service confused deputy issue.

If you're using server-side encryption on SNS, verify you have connect.amazonaws.com permission enabled on the KMS key. Following is a sample policy:

Step 2: Initiate the chat contact

Call the Connect Customer StartChatContact API to initiate the chat contact.

For information about how to create the SDK client for calling Connect Customer APIs, see the following topics:
- Class AmazonConnectClientBuilder
- Creating Service Clients
Keep track of ContactId and ParticipantToken from the StartChatContact response since these response attributes are used for calling other chat APIs required to enable streaming. This is described in the next steps.

Step 3: Enable message streaming on the contact

Call StartContactStreaming to enable real-time message streaming to your SNS topic.
- Limits: You can subscribe to up to two SNS topics per contact.
- When you call StartContactStreaming, you'll need to provide the Amazon Resource Name (ARN) of the SNS topic (see Step 1: Create a standard SNS topic).
  
  A single SNS topic ARN might be used across multiple AWS accounts, but it must be in the same Region as your Connect Customer instance. For example, if your topic ARN is in us-east-1, your Connect Customer instance must be in us-east-1.
- For initial chat messages that aren't received on the streaming endpoint, you can call the GetTranscript API to receive the initial messages.
- You can skip this step (enabling message streaming) if you set ChatStreamingConfiguration on StartChatContact. When you create the chat, Connect Customer starts message streaming and the response returns StreamingId.

Step 4: Create the participant connection

Call CreateParticipantConnection with the ConnectParticipant attribute passed as true.
- You must call CreateParticipantConnection within five minutes of creating the chat.
- Calling CreateParticipantConnection with ConnectParticipant set to true only works if you enabled streaming in Step 2: Initiate the chat contact and caller participant is Customer.
- You can skip this step (creating the participant connection) if you have already connected to the chat contact using WEBSOCKET, including a websocket URL returned by StartChatContact.
  
  Requesting only CONNECTION_CREDENTIALS does not connect the participant. Setting ChatStreamingConfiguration does not make this step optional. In both cases, this step still applies.

Next steps

You are all set for working with the message streaming APIs.

To verify it is working, check that messages are published to the SNS topic you created. You can do this using Amazon CloudWatch metrics. For instructions, see Monitoring Amazon SNS topics using CloudWatch.
Because SNS has limited retention, we recommend that you set up Amazon Simple Queue Service (Amazon SQS) Amazon Kinesis, or another service to retain messages.
Using StopContactStreaming is optional and not required if the chats are being disconnected through a contact flow, or if the customer disconnects the chat. However, StopContactStreaming provides the option to stop the message streaming on the SNS topic, even if the chat is active and ongoing.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Enable persistent chat

SNS payload