Eventos de sessão externa

O recurso de eventos de sessão externa permite o streaming de dados em tempo real da plataforma CCAI para seus sistemas externos usando webhooks. Isso oferece visibilidade imediata dos ciclos de vida da sessão 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 push para notificar seu servidor sempre que um chat ou uma ligação mudar de estado. Ao fornecer um endpoint de API, a plataforma CCAI vai POSTAR dados de eventos formatados em JSON na sua infraestrutura à medida que as transições ocorrem, por exemplo, chamada conectada, agente atribuído, sessão desconectada.

Configurar eventos de sessão externa

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 da sessão, clique em Gerenciar configurações de exportação de dados. A página Exportação de dados da sessão aparece.

  3. Acesse o painel Eventos de sessão externa e clique na alternância para a posição ativada.

  4. Faça uma ou ambas as 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 externa, 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, dn do cliente (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 ao vivo são adicionados.
4. Ativo connected Agente: connected Fluxo de mídia estabelecido (a conversa começa).
5. Finalizar disconnected Ambos: disconnected O carimbo de data/hora ends_at é preenchido.
6. Fim do processo disconnected Agente: dispositionSubmitted Objeto dispositions que contém códigos de finalização.

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.

Principais campos da sessão

  • event_id: um UUID para a notificação de evento.
  • timestamp: hora de época em milissegundos para 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:o servidor precisa responder em até cinco segundos.
  • Confirmação:o 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.

Exemplos de payloads

A seguir, mostramos exemplos de payloads recebidos em mensagens de eventos 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 pós-chamada)

{
  "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"
            }
          }
        ]
      }
    }
  ]
}