Eventos de sessão externa

Com a capacidade de eventos de sessão externa, é possível fazer streaming de dados em tempo real da plataforma de CCAI para seus sistemas externos usando webhooks. Isso oferece visibilidade imediata dos ciclos de vida das sessões para relatórios personalizados, atualizações de registros de CRM ou fluxos de trabalho automatizados pós-interação.

Os eventos de sessão externa fornecem um mecanismo baseado em push para notificar seu servidor sempre que um chat ou uma chamada de voz muda de estado. Ao fornecer um endpoint de API, a plataforma da CCAI envia dados de eventos formatados em JSON para sua infraestrutura à medida que as transições ocorrem, por exemplo, chamada conectada, agente atribuído, sessão desconectada.

Configurar eventos de sessão externos

Para configurar eventos de sessão externa, siga estas etapas:

  1. No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.

  2. No painel Exportação de dados de sessão, clique em Gerenciar configurações de exportação de dados. A página Exportação de dados da sessão é exibida.

  3. Acesse o painel Eventos de sessão externa e clique no botão para ativar.

  4. Faça uma ou as duas ações a seguir:

    • Para configurar eventos de sessão de chamada externa, faça o seguinte:

      1. Marque a caixa de seleção Eventos de chamada - Enviar evento de sessões de chamada.

      2. No campo Endpoint da API, insira o URL HTTPS completo da API de destino.

      3. Digite o nome de usuário e a senha. A plataforma usa esses dados para autenticação básica.

    • Para configurar eventos de sessão de chat externo, faça o seguinte:

      1. Marque a caixa de seleção Eventos de chat: enviar evento de sessões de chat.

      2. No campo Endpoint da API, insira o URL HTTPS completo da API de destino.

      3. Digite o nome de usuário e a senha. A plataforma usa esses dados para autenticação básica.

  5. Clique em Salvar.

Ciclo de vida do evento e lógica de estado

À medida que uma sessão avança, a plataforma CCAI envia várias atualizações. Cada atualização enriquece o objeto item com mais metadados à medida que eles ficam disponíveis.

Tabela de progressão de estado

Ordem do evento Estado Status do participante Principais pontos de dados adicionados
1. Iniciar connected Externo: connected call_id, cliente dn (número de telefone).
2. Roteamento connected Externo: connected queue_path_names, initiator (agente virtual).
3. Atribuído connected Agente: accepted O nome e o ID do agente em tempo real são adicionados.
4. Ativo connected Agente: connected Fluxo de mídia estabelecido (a conversa começa).
5. Fim disconnected Ambos: disconnected O carimbo de data/hora ends_at está preenchido.
6. Final disconnected Agente: dispositionSubmitted Objeto dispositions que contém códigos de encerramento.

Referência do esquema de dados de eventos

Os eventos são enviados ao webhook em um objeto. Cada evento de webhook tem a mesma estrutura, mostrada na tabela a seguir:

Objeto raiz

Campo Tipo Descrição
count Número inteiro Número de objetos de evento no payload atual.
events Matriz Uma coleção de objetos de evento que contém detalhes da sessão.

Campos principais da sessão

  • event_id: um UUID para a notificação de evento.
  • timestamp: tempo de época em milissegundos de quando o evento foi gerado.
  • connected_at e ends_at: carimbos de data/hora ISO 8601 para a duração da sessão.
  • initiator: identifica a entidade que processou a mudança de estado, por exemplo, virtual_agent_15 ou agent_1.
  • dispositions: um objeto aninhado que contém code, custom_code_id e qualquer note do agente.

Segurança

Todas as solicitações são enviadas com um cabeçalho de autorização padrão: Authorization: Basic <base64_encoded_credentials>

Requisitos de envio

  • Método:POST
  • Content-Type:application/json
  • Tempo limite:seu servidor precisa responder em até cinco segundos.
  • Confirmação:seu endpoint precisa retornar um código de status 200 OK. A plataforma pode usar novas tentativas de espera exponencial se um código diferente de 200 for recebido.

Payloads de exemplo

Confira a seguir exemplos de payloads recebidos em mensagens de evento para o webhook.

Conversa ativa (mídia conectada)

{
  "count": 1,
  "events": [
    {
      "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "connected",
        "queue_path_names": "Test/Talk to Andrew/English",
        "participants": [
          { "state": "connected", "type": "external", "dn": "+15555555555" },
          { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
        ]
      }
    }
  ]
}

Disposição final (trabalho após a ligação)

{
  "count": 1,
  "events": [
    {
      "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "disconnected",
        "participants": [
          {
            "type": "agent",
            "state": "dispositionSubmitted",
            "dispositions": {
              "code": "Call completed",
              "custom_code_id": "callComplete",
              "note": "none"
            }
          }
        ]
      }
    }
  ]
}