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 Apps. Ao final, sua integração poderá:

  • Autenticar-se na API Apps.

  • Criar ou atualizar um usuário final.

  • Inicie um chat para esse usuário final.

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

  • Enviar mensagens de texto no chat.

  • Processar 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 é destinado a desenvolvedores que estão criando um serviço de back-end que conecta uma experiência de chat de propriedade do cliente à plataforma CCAI. Ele pressupõe que você pode criar credenciais de API na CCAI Platform, 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 completo de solicitação e esquema de resposta, e use este guia para o fluxo de implementação completo recomendado.

Terminologia

As seguintes definições se aplicam a este documento:

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

  • Consumidor: o aplicativo do lado do servidor de propriedade do cliente que faz solicitações à 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 CCAI Platform que a API Apps cria.

  • 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 CCAI Platform em Configurações > Configurações do desenvolvedor > Credenciais de API.

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

  • Detalhes do URL do locatário

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

    • O URL de 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ário e secundário do webhook.

  • Configuração de fila ou menu

    • Identifique a fila ou o menu em que os novos chats 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.

  • Tratamento de limite de taxa

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

Autenticação e segurança de webhook

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

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

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

Autenticar solicitações da API Apps

As solicitações usam a autenticação básica HTTP. Crie um token de API na CCAI Platform 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, você poderá transmitir a chave da empresa como o nome de usuário e o secret da empresa como a senha. Consulte a referência da API Apps para ver a configuração completa de 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 de secrets 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 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 bruta:

X-Signature-Timestamp + raw_request_body

No gerenciador de webhook:

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

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

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

  4. Leia o corpo bruto da solicitação 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. Aceitar a solicitação se houver uma correspondência com algum secret ativo.

O exemplo de implementação em Ruby a seguir demonstra como verificar assinaturas de webhook da 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 forma idempotente. A entrega do 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 CCAI Platform, troca mensagens e encerra o chat.

Criar ou atualizar o usuário final

Objetivo: garantir que a plataforma CCAI tenha um registro de 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 CCAI Platform vai criar um novo registro.

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

Criar o chat

Meta:iniciar um novo chat da CCAI Platform para o usuário final.

Endpoint

Use o seguinte endpoint para iniciar um novo chat:

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 roteamento de agente virtual

Se o agente virtual de seleção de fila precisar de contexto do seu aplicativo, inclua um payload de contexto ao criar o chat, como 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 recebe 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 de webhook podem chegar em qualquer ordem. Trate ambos como atualizações do mesmo registro de chat, com chave pelo ID do chat.

Processar eventos de webhook do Chat

Meta: 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 plataforma CCAI. 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.

  • Dados de encaminhamento ou desvio quando o evento descreve o comportamento de roteamento.

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 duplicatas.

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

  • Processe efeitos colaterais downstream de forma assíncrona quando possível.

O que esperar

O aplicativo atualiza o estado do chat quando a CCAI Platform 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

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

Endpoint

Use o seguinte endpoint para enviar uma mensagem de texto no 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 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 agente virtual.

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

Receber e mostrar mensagens da plataforma CCAI

Meta:mostrar mensagens de agentes ou agentes virtuais 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 de chat do cliente.

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

O que esperar

A UI de chat 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 os carimbos de data/hora dos eventos e sua própria camada de persistência para reconciliar a ordem de exibição.

Encaminhar de um agente virtual para um agente humano

Objetivo:mover o chat do agente virtual para uma fila humana quando o usuário final precisar da ajuda de um agente.

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

Endpoint

Use o endpoint a seguir para encaminhar uma conversa 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 uma conversa:

{
  "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 agente.

  • Se a fila não puder receber o chat e as alternativas de desvio estiverem configuradas, a CCAI Platform vai manter o chat com o agente virtual e enviar um evento de webhook escalation_deflected com as alternativas disponíveis para o usuário final. As alternativas nunca chegam na resposta de encaminhamento.

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

Registrar uma escolha de desvio de encaminhamento

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

Quando a CCAI Platform oferecer opções de desvio de encaminhamento, registre a escolha do usuário final com o endpoint de atualização de encaminhamento.

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 desvio de e-mail.

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

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

Exemplo de solicitação

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

{
  "deflection_channel": "email"
}

Envie apenas um valor de 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 desvio externo, o chat é encerrado.

O que esperar

A CCAI Platform registra a escolha no encaminhamento. Registrar uma escolha não encaminha o chat. Sua integração atua na seleção, por exemplo, fechando o chat para um desvio de e-mail ou enviando um novo encaminhamento com force_escalate: true para uma escolha de continuar esperando.

Encerre o bate-papo.

Meta: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 uma conversa:

{
  "ended_by_user_id": 456
}

O que esperar

  • A CCAI Platform encerra o chat.

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

  • O aplicativo marca o chat como concluído e para de aceitar novas mensagens do usuário final para esse chat.

Se o chat estiver terminando porque o usuário final selecionou uma opção de desvio, não use esse endpoint em vez de registrar essa seleção. Registre a escolha no encaminhamento primeiro ou registre-a e encerre o chat em uma única solicitação com PATCH /apps/api/v1/chats/{chat_id}, fornecendo escalation_id e deflection_channel junto com o status. Uma conversa que termina sem uma escolha registrada deixa a escolha não registrada no encaminhamento e ausente dos relatórios de resultados de desvio.

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 tido uma conversa no seu sistema antes de você criar o chat da CCAI Platform, como uma conversa de chatbot.

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

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

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

Use esse fluxo quando o aplicativo enviar todos os novos chats para uma fila de entrada e permitir que um agente virtual decida a fila de destino final.

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

  2. Atribua o agente virtual à fila de entrada.

  3. Inclua contexto ao criar o chat.

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

  5. Gerencie as opções de desvio se a fila de destino estiver indisponí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 pré-assinado para fazer upload de uma foto ou um 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é-assinado.

Etapa 3: adicionar o arquivo enviado à conversa

Use os seguintes endpoints para adicionar uma foto ou um vídeo enviado à conversa:

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

Armazene o media_id que a plataforma CCAI retorna. Os payloads de mensagens de chat se referem à mídia pelo ID da mídia.

Etapa 4: enviar a mídia como uma mensagem

Use o seguinte endpoint para enviar uma mensagem de mídia no 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": "Photo of the damaged item",
    "media_id": 789
  }
}

O endpoint aceita type, content e media_id como valores simples. Um objeto aninhado fornecido em content é descartado, e a referência de mídia é perdida. Use o tipo de mensagem video e o vídeo media_id para mensagens de vídeo. media_id é um irmão de content.

Enviar dados do cliente durante um chat

Use o endpoint a seguir quando sua integração precisar anexar um 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 endpoint a seguir 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 um chat ativo e sua integração precisar que a plataforma CCAI associe o chat à identidade atualizada do usuário final.

Coletar dados de CSAT ou classificação

Use os seguintes endpoints de CSAT e classificação de chat quando sua integração for responsável pela 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 saber as regras de qualificação e os payloads de classificação exatos, consulte a referência da API Apps.