Como configuro um widget de conversa para minha aplicação que interaja de maneira nativa com as APIs do Amazon Connect e do Amazon Connect Participant Service?

Resolução

Para iniciar contatos de conversa de clientes diretamente de sua aplicação usando as APIs do Amazon Connect e do Amazon Connect Participant Service, configure sua aplicação para as ações a seguir.

Chamar a API StartChatContact do Amazon Connect quando um cliente iniciar um contato por conversa

Configure a aplicação para chamar a API StartChatContact do Amazon Connect quando um cliente iniciar um contato por conversa. A resposta da API retorna um valor ParticipantToken que é necessário para chamar a API CreateParticipantConnection na próxima etapa.

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

Para implantar os recursos necessários para chamar a API StartChatContact da sua aplicação, você pode usar o seguinte modelo do AWS CloudFormation no GitHub: amazon-connect-chat-ui-examples. O modelo cria um endpoint do Amazon API Gateway que invoca uma função do AWS Lambda que inclui as permissões do 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ê estiver usando axios em sua aplicação, poderá usar 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" // This is going to be a display name of your customer during a chat contact
    }
  }
);

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

Configure sua aplicação para chamar a API CreateParticipantConnection do Amazon Connect Participant Service depois que um contato de conversa for iniciado.

Chamar a API CreateParticipantConnection retorna um URL do WebSocket e um ConnectionToken. Os clientes devem se conectar manualmente ao URL do WebSocket e se inscrever no tópico desejado (“aws/chat”) para criar a conexão do participante da conversa.

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

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

Se você estiver usando axios em sua aplicação, poderá usar 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
});

Criar uma conexão WebSocket usando o URL do WebSocket retornado e inscrever a aplicação no tópico “aws/chat”

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

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

Exemplo de código JavaScript que cria uma conexão do 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))
});

Enviar mensagens de conversa ou eventos chamando as APIs do Amazon Connect Participant Service

Observação: não é possível enviar mensagens ou eventos diretamente por meio da conexão do WebSocket. Em vez disso, você deve usar uma das APIs do Amazon Connect Participant Service.

Para enviar mensagens de conversa, 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, certifique-se de usar o valor de ConnectionToken retornado pela API CreateParticipantConnection.

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

Se você estiver usando axios em sua aplicação, poderá usar 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ê estiver usando axios em sua aplicação, poderá usar 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
});

---