Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Guia da API da plataforma de chat

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

Terminologia

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

Cliente:o cliente da Contact Center AI Platform (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 o chat ao consumidor enviando solicitações de webhook para o 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.

O 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 app Ruby on Rails de amostra:

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 da API da plataforma de chat é o seguinte. Os pontos principais são numerados e as observações são fornecidas para mais contexto. O cliente é responsável apenas por implementar o lado "Cliente" do diagrama, enquanto a Contact Center AI Platform processa os lados do sistema e do agente do diagrama. A inclusão deles no diagrama tem como objetivo apenas dar ao leitor o contexto do fluxo geral de um chat.

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 que um chat seja criado.
Os usuários finais são identificados de maneira exclusiva pelo atributo identifier, que é um valor de string fornecido pelo consumidor. É possível que um usuário final já exista no sistema se ele tiver usado os SDKs da Web ou para dispositivos móveis. O endpoint POST /end_users é implementado como um upsert idempotente. Portanto, no caso de um usuário final já existente, tentar criá-lo novamente vai 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 na 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. Recomendamos processar o evento chat_created e a resposta da API de criação de chat de maneira idempotente para evitar bugs no consumidor.
Como criar chats com transcrições:a API da plataforma de chat oferece suporte à criação de um chat com uma transcrição de uma conversa existente, para 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 de chat 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 de filas para novos chats.

As etapas a seguir precisam ser realizadas para configurar o agente virtual:

Crie um agente virtual designado para essa finalidade e atribua-o 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 novo chat com o endpoint POST ou chats, inclua um payload de contexto personalizado que inclua algum contexto no chat criado que o agente virtual possa usar para determinar para qual fila o chat precisa ser encaminhado. O payload de contexto pode conter qualquer dado personalizado definido pelo cliente, mas precisa estar no formato a seguir 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 o chat para a fila selecionada. Se não houver um agente disponível na fila de destino (como um cenário em que uma fila está fora do horário comercial ou acima da capacidade), o encaminhamento será desviado, e o consumidor receberá um webhook indicando o motivo do desvio e as opções de desvio disponíveis.

Desvios de encaminhamento para um supervisor: os encaminhamentos para um supervisor 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 para o 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 PATCH /chats/:id endpoint 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: essa é tecnicamente uma opção de desvio válida mas não faz sentido usar o VA de seleção de fila, já que o VA tentaria encaminhar o chat novamente.
Continuar esperando um agente humano: essa opção só pode ser usada para encaminhamentos com um motivo de over_capacity. Se o usuário final escolher essa opção, atualize o desvio de encaminhamento com PATCH chats/:id/escalations/:id with deflection_channel=human_agent
- Link de desvio externo: avise o usuário final que selecionar um link fornecido no desvio vai encerrar o chat. Se um link for selecionado, encerre o chat 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 POST /chats/:id/message endpoint, conforme definido no documento da API. Para receber mensagens, ouça o evento de webhook message_received. Observação: o consumidor da API vai receber um evento message_received para todas as mensagens enviadas usando a API, incluindo as mensagens enviadas pelo usuário final.
Conteúdo de fotos e vídeos: o conteúdo de fotos e vídeos é enviado buscando um URL de upload pré-assinado para um serviço configurado do Cloud Storage na Contact Center AI Platform, fazendo upload para o serviço de armazenamento e enviando o URL de armazenamento em um payload de mensagem para a Contact Center AI Platform.
1. Como buscar o URL pré-assinado: busque um URL de upload pré-assinado na Contact Center AI Platform usando o 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 pré-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 tempo de expiração é 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, é necessário solicitar um URL pré-assinado para cada um.
2. Como fazer upload do arquivo de mídia: para fazer upload do arquivo de mídia, faça 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 de campos na solicitação de URL pré-assinado.
3. Como 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 oferece suporte ao envio de uma matriz de fotos, enquanto o endpoint de vídeo só oferece suporte a um vídeo por vez.
  - O parâmetro do corpo da solicitação s3_path precisa ter o mesmo valor do campo key da resposta do URL pré-assinado.
  - A solicitação vai retornar dois campos em caso de sucesso. Recomendamos salvar ou armazenar em cache um mapeamento de media_id para URL no consumidor da API, já que todas as mídias nas mensagens de chat serão referenciadas 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 de chat.
4. Como 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">,
    "media_id": < media_id returned as described in 2.c >
  }
}
```

Esperar chaves JSON não reconhecidas nas respostas da API

Todas as atualizações da API são compatíveis com versões anteriores. Reservamos o direito de introduzir novas chaves JSON nas respostas da API a qualquer momento. Recomendamos processar as respostas de forma defensiva, ignorando as 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.