Guia da API da plataforma de chat

A página mostra como usar os endpoints de chat, conforme descrito em Endpoints da API da plataforma de chat.

Terminologia

Para fins de clareza, confira algumas definições importantes ao usar este documento.

Cliente:o cliente da plataforma Contact Center AI (CCAI Platform) que está implementando a API da plataforma de chat no software.
Consumidor:o software que faz solicitações à API da plataforma de chat.
Usuário final:o usuário do software do cliente que está tentando conversar com um agente.

Autenticação de webhook

A API da plataforma de chat comunica eventos que ocorrem durante a conversa ao consumidor enviando solicitações de webhook ao servidor dele. Os payloads e tipos de webhook são definidos na especificação da API. Cada solicitação de webhook contém dois cabeçalhos, X-Signature e X-Signature-Timestamp.

X-Signature contém uma assinatura de webhook com o seguinte formato: primary=<primary_signature> secondary=<secondary_signature>

As assinaturas primária e secundária são um resumo sha256 codificado em base64 dos segredos de webhook primário ou secundário, respectivamente, com uma string concatenada do cabeçalho X-Signature-Timestamp e o payload JSON da solicitação.

Confira a seguir um exemplo de implementação de autorização para as solicitações de webhook em um aplicativo de amostra do Ruby on Rails:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Visão geral

Em geral, o fluxo básico de uma conversa com a API de uma plataforma de chat é o seguinte: Os pontos principais são numerados, e há observações para mais contexto. O cliente é responsável apenas por implementar o lado "Cliente" do diagrama, enquanto a Contact Center AI Platform lida com os lados do sistema e do agente. A inclusão deles no diagrama tem apenas o objetivo de dar ao leitor um contexto do fluxo geral de uma conversa.

O fluxo de uma conversa da API de uma plataforma de chat é mostrado.

Criar usuários finais

Os chats exigem um ID de usuário final válido quando são criados, o que significa que um usuário final precisa existir no sistema da Contact Center AI Platform antes da criação de um chat.
Os usuários finais são identificados de forma exclusiva pelo atributo identifier, que é um valor de string fornecido pelo consumidor. É possível que um usuário final já exista no sistema se tiver usado os SDKs para Web ou dispositivos móveis. O endpoint POST /end_users é implementado como uma inserção ou atualização idempotente. Portanto, no caso de um usuário final existente, tentar criá-lo novamente atualizará todos os dados alterados e retornará as informações do usuário final.

Criar chats

Para criar chats usando a API da plataforma de chat, siga estas etapas:

Como processar novos payloads de chat:o processo de inicialização do chat acontece de forma assíncrona em relação à solicitação POST /chats. Por isso, o evento chat_created pode ser recebido antes ou depois da resposta da API do endpoint de criação POST /chats. É recomendável processar o evento chat_created e a resposta da API de criação de chat de maneira idempotente para evitar bugs no consumidor.
Criação de chats com transcrições:a API da plataforma de chat permite criar um chat com a transcrição de uma conversa existente, em um cenário em que um chat acontece na plataforma de um cliente, por exemplo, com um chatbot, antes de ser enviado para a Contact Center AI Platform. Isso fornece ao agente que responde ao chat mais informações sobre a sessão e ajuda a evitar que o usuário final se repita. Para o formato de payload da transcrição, consulte chat_platform_openapi.yaml.

O agente virtual de seleção de fila

Para simplificar a seleção de menus para consumidores de API, a API da plataforma de chat foi projetada para ser usada em conjunto com um agente virtual do Dialogflow para ajudar na colocação em fila de espera para novos chats.

Siga estas etapas para configurar o agente virtual:

Crie um agente virtual designado para essa finalidade e atribua a uma fila. Todos os novos chats criados pela API da plataforma de chat precisam ser criados nessa fila. A criação e configuração de um novo agente virtual estão fora do escopo deste documento.
Ao criar um chat com o endpoint POST ou "chats", inclua um payload de contexto personalizado com informações sobre o chat criado que o agente virtual pode usar para determinar a qual fila ele deve ser encaminhado. O payload de contexto pode conter qualquer dado personalizado conforme definido pelo cliente, mas precisa estar no seguinte formato para que os dados sejam acessíveis pelo agente virtual atribuído à fila.
- Exemplo: "context": {"value": {"foo": "bar" } } permitiria que o agente virtual lesse $session.params.context.foo com um valor de bar.
Usando os dados contidos no campo de contexto, o agente virtual (com base em como o cliente o configurou) encaminha a conversa para a fila selecionada. Se não houver um agente disponível na fila de destino (por exemplo, um cenário em que uma fila está fora do horário de expediente ou acima da capacidade), o encaminhamento será desviado, e o consumidor vai receber um webhook indicando o motivo do desvio e as opções disponíveis.

Desvios de encaminhamento: os encaminhamentos de chat na API da plataforma de chat oferecem suporte às seguintes opções de desvio, se configuradas no portal da Contact Center AI Platform:

E-mail: peça ao usuário final para enviar um e-mail ao suporte e encerrar o chat. Quando um usuário final seleciona essa opção, depois que o e-mail é enviado, o cliente precisa marcar o chat como desviado e encerrado usando o endpoint PATCH /chats/:id com os seguintes parâmetros no corpo da solicitação: "status": "finished" , "escalation_id": <id of escalation> , e "deflection_channel": "email"
Continuar com o agente virtual: tecnicamente, essa é uma opção de redirecionamento válida, mas não faz sentido usar o agente virtual de seleção de fila, já que ele tentaria encaminhar a conversa novamente.
Aguardar um representante humano: essa opção só pode ser usada para encaminhamentos com o motivo over_capacity. Se o usuário final escolher essa opção, atualize a prevenção de escalonamento com PATCH chats/:id/escalations/:id with deflection_channel=human_agent.
- Link de redirecionamento externo: avise ao usuário final que selecionar um link fornecido no redirecionamento vai encerrar a conversa. Se um link for selecionado, encerre a conversa e use external_link para o parâmetro deflection_channel.

Enviar e receber mensagens

Para enviar ou receber mensagens, siga estas etapas:

Conteúdo de texto: para enviar mensagens de texto, use o endpoint POST /chats/:id/message conforme definido na documentação da API. Para receber mensagens, aguarde o evento de webhook message_received. O consumidor da API vai receber um evento message_received para todas as mensagens enviadas usando a API, incluindo mensagens enviadas pelo usuário final.
Conteúdo de foto e vídeo: o conteúdo de foto e vídeo é enviado buscando um URL de upload pré-assinado para um serviço do Cloud Storage configurado na Contact Center AI Platform, fazendo upload para o serviço de armazenamento e enviando o URL de armazenamento em uma carga útil de mensagem para a Contact Center AI Platform.
1. Buscar o URL pré-assinado: busque um URL de upload pré-assinado da Contact Center AI Platform usando POST /v1/chats/:chat_id/photos/upload ou POST /v1/chats/:chat_id/videos/upload endpoints. Esse endpoint retorna um URL pré-assinado, além de uma coleção de campos para encaminhar ao serviço de armazenamento ao fazer upload do arquivo. Os uploads assinados têm as seguintes restrições:
  - O Content-Type é image/jpeg para fotos e video/mp4 para vídeos.
  - O tamanho máximo da foto é de 2 MB. O tamanho máximo do vídeo é de 20 MB.
  - O prazo de validade é de 5 minutos.
  - O cliente precisa redimensionar e ajustar a orientação da foto antes de fazer o upload.
  - Cada URL pré-assinado é para uma única foto ou vídeo. Para enviar vários anexos, solicite um URL pré-assinado para cada um.
2. Upload do arquivo de mídia: para fazer upload do arquivo de mídia, crie uma solicitação POST para o URL pré-assinado buscado em 2a com o seguinte no corpo da solicitação:
  - "file": o arquivo a ser enviado
  - Todos os campos retornados no objeto "fields" na solicitação de URL pré-assinada.
3. Adicionar o arquivo de mídia ao chat: para adicionar o arquivo de mídia ao chat, use o endpoint POST /chats/:id/photos ou POST /chats/:id/videos. O endpoint de fotos permite enviar uma matriz de fotos, enquanto o de vídeo permite apenas um vídeo por vez.
  - O parâmetro de corpo da solicitação s3_path precisa ter o mesmo valor do campo key da resposta do URL pré-assinada.
  - A solicitação vai retornar dois campos se for bem-sucedida. Recomendamos salvar ou armazenar em cache um mapeamento de media_id para URL no consumidor da API, já que toda a mídia nas mensagens de chat será referenciada apenas por media_id.
    - url: o URL somente leitura do S3 ou do Cloud Storage em que o arquivo está localizado.
    - media_id: o ID do arquivo de mídia na Contact Center AI Platform. Esse é o ID pelo qual a mídia será referenciada nos payloads do chat.
4. Enviar o arquivo de mídia como uma mensagem de chat: para enviar o arquivo de mídia como uma mensagem de chat, envie o seguinte payload para o POST /chats/:id/message endpoint:
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

Esperar chaves JSON não reconhecidas em respostas da API

Todas as atualizações de API são compatíveis com versões anteriores. Reservamos o direito de introduzir novas chaves JSON em respostas de API atuais a qualquer momento. Recomendamos processar as respostas de forma defensiva, ignorando chaves não reconhecidas para manter a funcionalidade.

Guia da API da plataforma de chat Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.