Guia de integração da API da plataforma de chat

Use este guia para criar uma integração de chat do lado do servidor com a API do Google Apps. Ao final, sua integração poderá:

  • Autentique-se na API Apps.

  • Crie ou atualize um usuário final.

  • Inicie uma conversa com esse usuário final.

  • Receber e verificar eventos de webhook da Contact Center AI Platform.

  • Envie mensagens de texto no chat.

  • Lidar com ramificações opcionais, como importação de transcrição pré-chat, roteamento de agente virtual de seleção de fila, desvios de escalonamento e anexos de mídia.

  • Encerre o chat quando a conversa terminar.

Este guia é para desenvolvedores que estão criando um serviço de back-end que conecta uma experiência de chat de propriedade do cliente à CCAI Platform. Ele pressupõe que você pode criar credenciais de API na plataforma CCAI, hospedar um endpoint de webhook HTTPS, armazenar secrets com segurança e fazer solicitações HTTP do seu servidor.

Este guia complementa os endpoints de chat da API Apps. Use a referência da API para o esquema exaustivo de solicitação e resposta e este guia para o fluxo de implementação de ponta a ponta recomendado.

Terminologia

As definições a seguir são aplicáveis a este documento:

  • Cliente: o cliente da plataforma CCAI que está implementando a integração do chat no próprio software.

  • Consumidor: o aplicativo do lado do servidor de propriedade do cliente que faz solicitações para a API Apps e recebe eventos de webhook da plataforma CCAI.

  • Usuário final: a pessoa que usa o software do cliente para iniciar ou continuar uma conversa com um agente ou agente virtual.

  • Chat: o recurso de conversa da plataforma CCAI criado pela API Apps.

  • Endpoint do webhook: o endpoint HTTPS no aplicativo do consumidor que recebe eventos de chat da plataforma CCAI.

Antes de começar

Antes de começar, certifique-se de ter:

  • Credenciais da API Apps

    • Crie credenciais de API na plataforma CCAI em Configurações > Configurações de desenvolvedor > Credenciais de API.

    • Armazene o secret da credencial com segurança. Não exponha a chave no navegador ou no código do cliente móvel.

  • Detalhes do URL do locatário

    • Identifique seu subdomínio e domínio da CCAI Platform.

    • O URL base da API Apps é: https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • Endpoint do webhook

    • Hospede um endpoint HTTPS público que possa receber solicitações POST da plataforma CCAI.

    • Configure o endpoint nas configurações de desenvolvedor da plataforma CCAI.

    • Gere e armazene os secrets primários e secundários do webhook.

  • Configuração de fila ou menu

    • Identifique a fila ou o menu em que as novas conversas entram.

    • Se você usar um agente virtual de seleção de fila, configure-o e atribua-o à fila de entrada antes de criar chats pela API.

  • Identidade do usuário final

    • Decida qual identificador estável seu sistema vai usar para cada usuário final.

    • Armazene o ID do usuário final da plataforma CCAI retornado pela API Apps.

  • Processamento de limitação de taxa

    • A plataforma CCAI limita a taxa da API Apps. Crie novas tentativas e espera exponencial na sua integração e evite enviar rajadas de solicitações para um único locatário.

Segurança de autenticação e webhook

Sua integração usa dois caminhos de autenticação:

  • Autenticação da API Apps para solicitações do seu servidor à CCAI Platform.

  • Verificação de assinatura de webhook para solicitações da CCAI Platform ao seu servidor.

Autenticar solicitações da API Apps

As solicitações usam autenticação HTTP básica. Crie um token de API na plataforma CCAI em Configurações > Configurações do desenvolvedor > Credenciais da API e transmita-o no campo senha (recomendado). Se o locatário usar o caminho de autenticação legado, transmita a chave da empresa como nome de usuário e o segredo da empresa como senha. Consulte a referência da API Apps para a configuração completa da autenticação. O exemplo a seguir demonstra como autenticar uma solicitação de API Apps usando a autenticação básica:

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

Armazene as credenciais em um repositório secreto do lado do servidor, faça a rotação delas de acordo com sua política de segurança e nunca as envie em navegadores ou apps para dispositivos móveis.

Verificar solicitações de webhook

A plataforma CCAI envia eventos de chat para o endpoint do webhook. Cada solicitação de webhook inclui:

  • X-Signature

  • X-Signature-Timestamp

O cabeçalho X-Signature pode conter uma assinatura principal, uma assinatura secundária ou ambas:

primary=<primary_signature> secondary=<secondary_signature>

Cada assinatura é um resumo HMAC-SHA256 codificado em Base64. O valor assinado é o cabeçalho de carimbo de data/hora concatenado com o corpo da solicitação JSON bruto:

X-Signature-Timestamp + raw_request_body

No seu manipulador de webhook:

  1. Leia X-Signature e X-Signature-Timestamp.

  2. Rejeite a solicitação se um dos cabeçalhos estiver faltando.

  3. Rejeite carimbos de data/hora desatualizados para reduzir o risco de repetição.

  4. Leia o corpo da solicitação bruta antes de analisar o JSON.

  5. Calcule a assinatura esperada usando cada secret de webhook ativo.

  6. Compare a assinatura recebida e a esperada usando uma comparação de tempo constante.

  7. Aceite a solicitação se algum segredo ativo corresponder.

O exemplo de implementação em Ruby a seguir demonstra como verificar assinaturas de webhook do UJET:

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

Se a verificação for bem-sucedida, retorne uma resposta de sucesso rapidamente e processe o evento de maneira idempotente. A entrega de webhook e as respostas da API podem chegar em ordens diferentes. Por isso, crie sua integração para tolerar o recebimento da mesma mudança de estado mais de uma vez sem criar registros duplicados.

O fluxo de integração

O fluxo a seguir cria um usuário final, inicia um chat, recebe eventos da plataforma CCAI, troca mensagens e encerra o chat.

Criar ou atualizar o usuário final

Objetivo:garantir que a plataforma CCAI tenha um registro do usuário final antes de criar o chat.

Endpoint

Use o seguinte endpoint para criar ou atualizar um usuário final:

POST /apps/api/v1/end_users

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para criar ou atualizar um usuário final:

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

O que armazenar

Armazene o ID do usuário final da plataforma CCAI da resposta no seu sistema. Use esse ID ao criar uma conversa.

O que esperar

  • Se o usuário final não existir, a plataforma CCAI vai criar um novo registro.

  • Se um usuário final já existir com o mesmo identificador, a plataforma CCAI vai atualizar o registro e retornar as informações do usuário final atual.

Criar o chat

Objetivo:iniciar uma nova conversa da plataforma CCAI para o usuário final.

Endpoint

Use o seguinte endpoint para iniciar uma nova conversa:

POST /apps/api/v1/chats

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para criar uma conversa:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Contexto opcional para o roteamento de agentes virtuais

Se o agente virtual de seleção de fila precisar de contexto do seu aplicativo, inclua um payload de contexto ao criar o chat, conforme mostrado no exemplo a seguir:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

Um agente virtual pode usar valores desse contexto para decidir qual fila vai receber o chat.

O que esperar

  • A API Apps retorna o recurso de chat.

  • A plataforma CCAI envia um evento de webhook chat_created para o endpoint de webhook configurado.

  • A resposta da API e o evento do webhook podem chegar em qualquer ordem. Trate os dois como atualizações do mesmo registro de chat, com chave pelo ID do chat.

Processar eventos de webhook do chat

Objetivo:manter o aplicativo do consumidor sincronizado com o estado do chat da plataforma CCAI.

O endpoint do webhook processa o ciclo de vida do chat e os eventos de mensagem da CCAI Platform. No mínimo, armazene:

  • ID do chat.

  • Tipo de evento.

  • Carimbo de data/hora do evento.

  • Remetente, tipo e conteúdo da mensagem quando o evento contém uma mensagem.

  • Todos os dados de encaminhamento ou redução quando o evento descreve o comportamento de encaminhamento.

Comportamento recomendado

  • Verifique todas as assinaturas de webhook antes de processar o evento.

  • Armazene IDs de eventos processados ou uma chave de evento determinista para que as novas tentativas não criem duplicados.

  • Retorne uma resposta 2xx depois de aceitar o evento.

  • Sempre que possível, processe efeitos colaterais downstream de forma assíncrona.

O que esperar

O aplicativo atualiza o estado do chat quando a plataforma CCAI envia eventos como criação de chat, mensagens recebidas, mensagens do agente, mudanças de encaminhamento e conclusão do chat.

Enviar uma mensagem de texto

Objetivo:enviar uma mensagem do usuário final do aplicativo do consumidor para o chat da plataforma de CCAI.

Endpoint

Use o seguinte endpoint para enviar uma mensagem de texto para o chat:

POST /apps/api/v1/chats/{chat_id}/message

Exemplo de solicitação

O exemplo a seguir mostra um corpo de solicitação para enviar uma mensagem de texto:

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

O que esperar

  • A plataforma CCAI aceita a mensagem.

  • A mensagem aparece na conversa com o agente ou o agente virtual.

  • O endpoint do webhook recebe um evento de mensagem, incluindo mensagens que seu próprio aplicativo enviou pela API Apps.

Receber e mostrar mensagens da plataforma CCAI

Objetivo:mostrar mensagens do agente ou do agente virtual na experiência de chat do cliente.

Quando o endpoint do webhook recebe um evento de mensagem:

  1. Verifique a assinatura do webhook.

  2. Verifique se o evento é novo.

  3. Identifique a conversa pelo ID.

  4. Identifique o remetente e o tipo de mensagem.

  5. Renderize a mensagem na UI do chat de propriedade do cliente.

  6. Persista o evento para que atualizações ou novas tentativas não percam o histórico de conversas.

O que esperar

A UI do chat de propriedade do cliente mostra as mensagens enviadas por agentes, agentes virtuais e o usuário final na ordem correta. Se os eventos chegarem fora de ordem, use carimbos de data/hora de evento e sua própria camada de persistência para conciliar a ordem de exibição.

Escalonar de um agente virtual para um atendente

Objetivo:transferir o chat do atendimento do agente virtual para uma fila de atendimento humano quando o usuário final precisar de ajuda.

Se a integração usar um agente virtual de seleção de fila, configure o agente virtual para encaminhar chats à fila de destino. Se o servidor iniciar o encaminhamento diretamente, use o endpoint de encaminhamento da API Apps.

Endpoint

Use o seguinte endpoint para encaminhar um chat de um agente virtual para um agente humano:

POST /apps/api/v1/chats/{chat_id}/escalations

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para encaminhar um chat:

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

O que esperar

  • Se a fila de destino estiver disponível, o chat será encaminhado para o atendimento de um agente.

  • Se a fila estiver indisponível devido a condições fora do horário de expediente ou de capacidade excessiva, a plataforma CCAI poderá retornar ou enviar opções de redirecionamento pelo fluxo de chat.

  • Sua integração renderiza as opções de evasão disponíveis para o usuário final.

Registrar uma opção de redução de encaminhamento para um supervisor

Objetivo:informar à plataforma CCAI qual opção de desvio o usuário final selecionou.

Quando a plataforma CCAI oferecer opções de redução de escalonamento, registre a escolha do usuário final com o endpoint de atualização de escalonamento.

Endpoint

Use o endpoint a seguir para atualizar um registro de encaminhamento com uma opção de desvio:

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Valores de deflection_channel aceitos:

  • email: o usuário final escolhe a opção de redirecionamento de e-mail.

  • virtual_agent: o usuário final escolhe continuar com um agente virtual.

  • human_agent: o usuário final escolhe continuar esperando um atendente humano. Esse valor se aplica apenas a desvios de capacidade excessiva.

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para registrar uma opção de evasão:

{
  "deflection_channel": "email"
}

Envie apenas um valor deflection_channel compatível para esse endpoint. external_link não é um valor válido para o endpoint de atualização de encaminhamento. Quando o usuário final segue um link de evasão externa, a conversa termina.

O que esperar

A plataforma CCAI atualiza o registro de encaminhamento e faz a transição da conversa de acordo com a opção selecionada.

Encerre o bate-papo.

Objetivo:fechar o chat quando a conversa terminar.

Endpoint

Use o seguinte endpoint para encerrar um chat ativo:

PATCH /apps/api/v1/chats/{chat_id}/end

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para encerrar um chat:

{
  "ended_by_user_id": 456
}

O que esperar

  • A CCAI Platform encerra o chat.

  • O endpoint de webhook recebe o evento final de estado do chat.

  • Seu aplicativo marca a conversa como concluída e para de aceitar novas mensagens do usuário final.

Fluxos avançados

As ramificações a seguir são opcionais. Implemente apenas os fluxos que se aplicam à sua integração.

Importar uma transcrição de pré-chat

Use esse fluxo quando o usuário final já tiver conversado no seu sistema antes de você criar o chat da plataforma do CCAI, como uma conversa com um chatbot.

Adicione o payload da transcrição ao criar a conversa. A transcrição dá contexto ao agente para que o usuário final não precise repetir informações.

A referência da API Apps inclui o esquema de transcrição exato.

Encaminhar chats com um agente virtual de seleção de fila

Use esse fluxo quando o aplicativo enviar todas as novas conversas para uma fila de entrada e permitir que um agente virtual decida a fila de destino final.

  1. Crie um agente virtual para seleção de fila.

  2. Atribua o agente virtual à fila de entrada.

  3. Inclua contexto ao criar a conversa.

  4. Configure o agente virtual para inspecionar o contexto e encaminhar o chat para a fila correta.

  5. Lidar com opções de redirecionamento se a fila de destino não estiver disponível.

Enviar fotos ou vídeos como anexos

Use esse fluxo quando o usuário final enviar mídia da UI de chat do cliente.

O fluxo de mídia tem quatro etapas.

Etapa 1: solicitar um URL de upload pré-assinado

Use os seguintes endpoints para solicitar um URL assinado para fazer upload de uma foto ou vídeo:

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

Etapa 2: fazer upload do arquivo para o URL de armazenamento retornado

Inclua o arquivo e todos os campos que a plataforma CCAI retorna na resposta de upload pré-assinada.

Etapa 3: adicionar o arquivo enviado ao chat

Use os seguintes endpoints para adicionar uma foto ou um vídeo enviado ao chat:

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Armazene o media_id retornado pela plataforma CCAI. Os payloads de mensagens de chat se referem à mídia pelo ID dela.

Etapa 4: enviar a mídia como uma mensagem

Use o seguinte endpoint para enviar uma mensagem de mídia ao chat:

POST /apps/api/v1/chats/{chat_id}/message

Exemplo de solicitação

O exemplo a seguir demonstra um corpo de solicitação para enviar um anexo de foto:

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": {
      "media_id": 789
    }
  }
}

Use o tipo de mensagem video e o vídeo media_id para mensagens de vídeo.

Enviar dados personalizados durante um chat

Use o endpoint a seguir quando a integração precisar anexar contexto definido pelo cliente a um chat ativo:

POST /apps/api/v1/chats/{chat_id}/custom_data

A referência da API Apps define o formato exato do payload e o comportamento da chave reservada.

Atualizar a identidade do usuário final durante uma conversa

Use o seguinte endpoint quando a identidade do usuário final mudar ou se tornar conhecida depois que o chat começar:

POST /apps/api/v1/chats/{chat_id}/end_user

Por exemplo, use esse endpoint quando um usuário final anônimo fizer login durante uma conversa ativa e sua integração precisar que a plataforma CCAI associe a conversa à identidade atualizada do usuário final.

Coletar dados de CSAT ou classificação

Use os seguintes endpoints de CSAT e classificação do chat quando sua integração for proprietária da experiência de classificação pós-chat:

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

Para conferir as regras de qualificação e os payloads de classificação exatos, consulte a referência da API Apps.