Como configuro um widget de chat para meu aplicativo que interage de forma nativa com as APIs do Amazon Connect e do Amazon Connect Participant Service?

Solução

Para iniciar contatos de chat com clientes diretamente do seu aplicativo com as APIs do Amazon Connect e do Amazon Connect Participant Service, faça o seguinte:

Chame a API StartChatContact Amazon Connect quando um cliente iniciar um contato por chat

Configure seu aplicativo para chamar a API StartChatContact do Amazon Connect quando um cliente iniciar um contato por chat. A resposta da API retorna um valor de ParticipantToken. Esse valor é necessário para chamar a API CreateParticipantConnection.

Importante: o cliente que faz a chamada de API deve ter permissões do AWS Identity and Access Management (IAM) para realizar a ação connect:StartChatContact.

Use o modelo amazon-connect-chat-ui-examples do AWS CloudFormation no site do GitHub para implantar os recursos necessários para chamar a API StartChatContact. O modelo cria um endpoint do Amazon API Gateway que invoca uma função do AWS Lambda com as permissões de IAM necessárias. A função do AWS Lambda invoca a API StartChatContact do Amazon Connect e retorna o resultado dessa chamada.

Exemplo de solicitação da API StartChatContact (JavaScript)

Se você usa axios em seu aplicativo, use o seguinte código JavaScript para chamar a API StartChatContact:

const startChatApi = "https://xxxxxxxxxx.execute-api.<region>.amazonaws.com/Prod"; // API endpoint you deployed with the CloudFormation template.
...

axios.post(
  startChatApi,
  {
    ParticipantDetails: {
      DisplayName: "CUSTOMER" // A display name of your customer during a chat contact
    }
  }
);

Para obter mais informações, consulte o comando axios no site do GitHub.

Chame a API CreateParticipantConnection do Amazon Connect Participant Service e passe o valor de ParticipantToken

Configure seu aplicativo para chamar a API CreateParticipantConnection do Amazon Connect Participant Service depois que um contato de chat for iniciado.

Quando você invoca a API CreateParticipantConnection, ela retorna um URL do WebSocket e um ConnectionToken. Os clientes devem se conectar manualmente ao URL do WebSocket e assinar o tópico desejado "aws/chat" para criar a conexão do participante do bate-papo.

Observação: as APIs do Amazon Connect Participant Service não usam Signature Version 4 authentication. Para o valor do cabeçalho da solicitação X-Amz-Bearer, você deve usar o valor ParticipantToken ou ConnectionToken. O valor ParticipantToken é usado somente para chamar a API CreateParticipantConnection. Outras APIs do Amazon Connect Participant Service exigem que você passe o valor ConnectionToken.

Exemplo de solicitação da API CreateParticipantConnection (JavaScript):

Se você usa axios em seu aplicativo, use o seguinte código JavaScript para chamar a API CreateParticipantConnection:

const participantServiceEndpoint = "https://participant.connect.<region>.amazonaws.com";// Replace <region> with the one that you are using. i.e. us-west-2. Endpoint list is available in https://docs.aws.amazon.com/general/latest/gr/connect_region.html

...

const requestHeaders = {
  "X-Amz-Bearer": "ParticipantToken", // Replace "ParticipantToken" with the one you obtained from the response of StartChatContact API
  "Content-type": "application/json"
};
const requestBody = {
  "Type": ["WEBSOCKET", "CONNECTION_CREDENTIALS"]
};

axios.post(participantServiceEndpoint + "/participant/connection", requestBody, {
  headers: requestHeaders
});

Crie uma conexão WebSocket com o URL do WebSocket retornado e inscreva o aplicativo no tópico "aws/chat"

Depois de invocar a API CreateParticipantConnection, o cliente deve se conectar manualmente ao URL do WebSocket retornado e assinar o tópico "aws/chat".

Para obter mais informações, consulte CreateParticipantConnection na referência da API do Amazon Connect Participant Service.

Exemplo de código JavaScript que cria uma conexão WebSocket e inscreve um cliente no tópico “aws/chat”:

const ws = new WebSocket(websocketUrl); // Here, you use the websocket URL that you obtained from the response of CreateParticipantConnection API
const initialMessage = {
  topic: "aws/subscribe",
  content: {
    topics: ["aws/chat"]
  }
};
ws.addEventListener("open", () => {
  ws.send(JSON.stringify(initialMessage))
});

Receba eventos e mensagens de chat por meio da conexão WebSocket

Depois de abrir a conexão WebSocket e assinar o tópico "aws/chat", você pode receber eventos e mensagens de chat por meio do WebSocket. Para fazer isso, adicione um receptor de eventos para o evento "message".

Exemplo de código JavaScript que cria um receptor de eventos para o evento "message":

ws.addEventListener("message", (event) => {
  // process event here
  const response = JSON.parse(event.data);
  if (response.topic === "aws/chat") {
  const responseMessage = JSON.parse(response.content);
    if (responseMessage.Type === "MESSAGE") {
      // display message in interface here
    }
  }
}

Para obter mais informações sobre a estrutura do objeto responseMessage, consulte Item na documentação do Amazon Connect.

Envie mensagens de chat ou eventos por meio das APIs do Amazon Connect Participant Service

Observação: você não pode enviar mensagens ou eventos diretamente pela conexão WebSocket. Em vez disso, você deve usar uma das APIs do Amazon Connect Participant Service.

Para enviar mensagens de chat, chame a API SendMessage do Amazon Connect Participant Service. Ou, para enviar eventos, chame a API SendEvent do Amazon Connect Participant Service.

Importante: Para o cabeçalho de solicitação X-Amz-Bearer, use o valor ConnectionToken que é retornado pela API CreateParticipantConnection.

Exemplo de solicitação da API SendMessage (JavaScript)

Se você usa axios em seu aplicativo, use o seguinte código JavaScript para chamar a API SendMessage:

const requestHeaders = {  "X-Amz-Bearer": "ConnectionToken", // Replace "ConnectionToken" with the one you obtained from the response of CreateParticipantConnection API
  "Content-type": "application/json"
};
const requestBody = {
  "ClientToken": "unique string", // [Optional] A unique, case-sensitive identifier that you provide to ensure the idempotency of the request
  "Content": message, // The actual chat message
  "ContentType": "text/plain", // Currently, supported type is text/plain
};

axios.post(participantServiceEndpoint + "/participant/message", requestBody, {
  headers: requestHeaders
  });

Exemplo de solicitação da API SendEvent (JavaScript)

Se você usa axios em seu aplicativo, use o seguinte código JavaScript para chamar a API SendEvent:

const requestHeaders = {  "X-Amz-Bearer": "ConnectionToken", //Replace "ConnectionToken" with the one you obtained from the response of CreateParticipantConnection API
  "Content-type": "application/json"
};
const requestBody = {
  "ClientToken": "unique string", //[Optional] A unique, case-sensitive identifier that you provide to ensure the idempotency of the request
  "ContentType": "application/vnd.amazonaws.connect.event.typing", //Typing event. You can specify "application/vnd.amazonaws.connect.event.connection.acknowledged" for acknowledged event
};

axios.post(participantServiceEndpoint + "/participant/event", requestBody, {
  headers: requestHeaders
});