Registrando atividade com um webhook

Plus

É possível registrar uma atividade fazendo uma chamada para um serviço ou aplicativo externo toda vez que um cliente envia entrada para o assistente.

Um webhook é um mecanismo que você pode usar para chamar um programa externo com base em eventos do seu programa.

Esse recurso está disponível apenas para usuários dos planos Plus e Enterprise. O plano Plus permite não mais do que 5 webhooks de log por instância. Esse limite não se aplica às instâncias do plano Enterprise.

Adicione um webhook de registro ao seu assistente se quiser usar um serviço externo para registrar a atividade. É possível registrar dois tipos de atividade:

Mensagens e respostas: O webhook de registro é acionado sempre que o assistente responde à entrada do cliente. É possível usar essa opção como uma alternativa para o recurso de analítica integrado para que você mesmo manipule a criação de log. (Para obter mais informações sobre o suporte de analítica integrada, consulte Revisar o assistente inteiro em uma visão rápida.)

Se você estiver usando um canal personalizado, o webhook de registro funcionará somente com a API /message v2 (sem estado e com estado). Para obter mais informações, consulte a referência da API. Todas as integrações de canais embutidos usam essa API.
Registros de detalhes de chamadas (CDRs): O webhook de registro é acionado após cada chamada telefônica que um usuário faz para o seu assistente que usa a integração telefônica. Um Registro de detalhes de chamada (CDR) é um relatório resumido que documenta os detalhes de uma chamada telefônica, incluindo números de telefone, duração da chamada, latência e outras informações de diagnóstico. Os registros de CDR são apenas para assistentes que usam a integração telefônica.

O webhook de log não retorna nada para o seu assistente.

Para ambientes nos quais os terminais privados estão em uso, tenha em mente que um webhook envia tráfego pela internet.

Definindo o webhook

É possível definir uma URL de webhook para registrar cada mensagem recebida ou evento CDR.

A chamada programática para o serviço externo deve atender a esses requisitos:

A chamada deve ser uma solicitação de HTTP POST.

Para incluir detalhes do webhook, conclua as etapas a seguir:

Em seu assistente, abra o ambiente no qual você deseja configurar o webhook
Clique no ícone para abrir as configurações do ambiente.
Na página de configurações do ambiente, clique em Log webhook.
1. Ou, se você estiver usando a experiência clássica, abra a página Assistentes.
2. Para o assistente que você deseja configurar, clique no ícone e, em seguida, escolha Configurações
3. Clique em Webhooks, em seguida, clique em Log webhook.
Configure o comutador Webhook de log para Ativado.

Se não for possível ativar o webhook, talvez seja necessário fazer o upgrade do plano de serviço.
No campo URL, inclua a URL para o aplicativo externo para o qual você deseja enviar callouts de solicitação de POST HTTP. Por exemplo, https://example.com/my_log_service.

Deve-se especificar uma URL que use o protocolo SSL, portanto, especifique uma URL que comece com https.
No campo Segredo, inclua um token para passar com a solicitação que possa ser usado para autenticação com o serviço externo.

O segredo deve ser especificado como uma sequência de texto, como purple unicorn. O comprimento máximo é de 1.024 caracteres. Não é possível especificar uma variável de contexto.

É responsabilidade do serviço externo conferir e verificar o segredo. Se o serviço externo não exigir um token, especifique qualquer cadeia de caracteres que você desejar. Não é possível deixar esse campo vazio.

Se desejar ver o segredo à medida que for inserido, clique no ícone Mostrar senha antes de começar a digitar. Após salvar o segredo, a sequência é substituída por asteriscos e não pode ser visualizada novamente.
Clique nas caixas de seleção apropriadas para selecionar quais tipos de atividade deseja registrar:
- Para registrar mensagens e respostas, selecione Assinar logs de conversa.
- Para registrar eventos CDR para a integração telefônica, selecione Assinar CDR (Registros de detalhes de chamada).
Na seção Cabeçalhos, inclua quaisquer cabeçalhos que deseja transmitir ao serviço, um por vez, clicando em Incluir cabeçalho.

O serviço envia automaticamente um cabeçalho Authorization com um JWT; não é preciso incluir um. Se você quiser lidar com a autorização por conta própria, adicione seu próprio cabeçalho de autorização e ele será usado.

Após salvar o valor do cabeçalho, a sequência é substituída por asteriscos e não pode ser visualizada novamente.

Os detalhes de seu webhook são salvos automaticamente.

Removendo o webhook

Se decidir que não deseja registrar mensagens com um webhook, conclua as etapas a seguir:

Em seu assistente, vá em Ambientes e abra o ambiente onde você deseja configurar o webhook.
Clique no ícone para abrir as configurações do ambiente.
Na página de configurações do ambiente, clique em Log webhook.
1. Ou, se você estiver usando a experiência clássica, abra a página Assistentes.
2. Para o assistente que você deseja configurar, clique no ícone e, em seguida, escolha Configurações
3. Clique em Webhooks, em seguida, clique em Log webhook.
Execute um dos seguintes procedimentos:
- Para mudar o webhook que deseja chamar, clique em Excluir webhook para excluir a URL e o segredo atualmente especificados. Em seguida, você pode adicionar um URL e outros detalhes.
- Para parar de chamar um webhook para registrar cada mensagem e resposta, clique no comutador Webhook de log para desativar totalmente o webhook.

Segurança do webhook

Para autenticar a solicitação do webhook, verifique o JSON Web Token (JWT) que é enviado com a solicitação. O microserviço de webhook gera automaticamente um JWT e o envia no cabeçalho Authorization com cada chamada de webhook. É sua responsabilidade incluir um código no serviço externo que verifica o JWT.

Por exemplo, se você especificar purple unicorn no campo Segredo, poderá incluir código como:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Corpo de solicitação de Webhook

O corpo da solicitação que o webhook envia ao serviço externo é um objeto JSON com a seguinte estrutura:

{
  "event": {
    "name": "{event_type}"
   },
  "payload": {
    ...
  }
}

em que {event_type} é message_logged (para mensagens e respostas) ou cdr_logged (para eventos CDR).

O objeto payload contém os dados do evento a serem registrados. A estrutura do objeto payload depende do tipo de evento.

Carga útil do evento de mensagens

Para eventos message_logged, o objeto payload contém dados sobre uma solicitação de mensagem que é enviada ao assistente e a resposta da mensagem que é retornada ao aplicativo de integração ou cliente. Para obter mais informações sobre os campos que fazem parte de solicitações de mensagens e respostas, consulte a Referência da API.

A carga útil do webhook de log pode incluir dados que não são suportados atualmente pela API. Quaisquer campos que não estejam definidos na documentação de referência da API estão sujeitos a mudança.

Carga útil de eventos CDR

Para eventos cdr_logged, o objeto payload contém dados sobre um evento CDR (Registro de detalhes de chamada) que foi manipulado por integração telefônica. A estrutura do objeto payload para um evento CDR é como mostrado por este exemplo:

{
  "primary_phone_number": "+18005550123",
  "global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
  "failure_occurred": false,
  "transfer_occurred": false,
  "active_calls": 0,
  "warnings_and_errors": [
    {
      "code": "CWSMR0033W",
      "message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
    },
    {
      "code": "CWSMR0070W",
      "message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
    }
  ],
  "realtime_transport_network_summary": {
    "inbound_stream": {
      "average_jitter": 4,
      "canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
      "maximum_jitter": 18,
      "packets_lost": 0,
      "packets_transmitted": 952,
      "tool_name": ""
    },
    "outbound_stream": {
      "average_jitter": 0,
      "canonical_name": "voice.gateway",
      "maximum_jitter": 0,
      "packets_lost": 0,
      "packets_transmitted": 838,
      "tool_name": "IBM Voice Gateway/1.0.7.0"
    }
  },
  "call": {
    "start_timestamp": "2021-10-12T20:54:02.591Z",
    "stop_timestamp": "2021-10-12T20:54:20.375Z",
    "milliseconds_elapsed": 17784,
    "outbound": false,
    "end_reason": "assistant_hangup",
    "security": {
      "media_encrypted": false,
      "signaling_encrypted": false,
      "sip_authenticated": false
    }
  },
  "session_initiation_protocol": {
    "invite_arrival_time": "2021-10-12T20:54:00.565Z",
    "setup_milliseconds": 2026,
    "headers": {
      "call_id": "17465345_115257202@10.90.150.99",
      "from_uri": "sip:+18885550456@pstn.twilio.com",
      "to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
    }
  },
  "max_response_milliseconds": {
    "assistant": 339,
    "text_to_speech": 535,
    "speech_to_text": 0
  },
  "assistant_interaction_summaries": [
    {
      "session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
      "assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
      "turns": [
        {
          "assistant": {
            "log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
            "response_milliseconds": 339,
            "start_timestamp": "2021-10-12T20:54:00.722Z"
          },
          "request": {
            "type": "start"
          },
          "response": [
            {
              "barge_in_occurred": true,
              "streaming_statistics": {
                "response_milliseconds": 301,
                "start_timestamp": "2021-10-12T20:54:00.722Z",
                "stop_timestamp": "2021-10-12T20:54:01.023Z",
                "transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
              },
              "type": "text_to_speech"
            }
          ]
        },
        {
          "assistant": {
            "log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
            "response_milliseconds": 158,
            "start_timestamp": "2021-10-12T20:54:05.621Z"
          },
          "request": {
            "type": "dtmf"
          },
          "response": [
            {
              "type": "disable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": false,
              "streaming_statistics": {
                "transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
                "start_timestamp": "2021-10-12T20:54:06.321Z",
                "stop_timestamp": "2021-10-12T20:54:14.338Z",
                "response_milliseconds": 535
              }
            },
            {
              "type": "enable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": true,
              "streaming_statistics": {
                "transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
                "start_timestamp": "2021-10-12T20:54:14.795Z",
                "stop_timestamp": "2021-10-12T20:54:20.388Z",
                "response_milliseconds": 447
              }
            }
          ]
        },
        {
          "assistant": {
            "log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
            "response_milliseconds": 0,
            "start_timestamp": "2021-10-12T20:54:20.377Z"
          },
          "request": {
            "type": "hangup"
          },
          "response": []
        }
      ]
    }
  ]
}

Para obter mais informações sobre a estrutura da carga útil do evento CDR, consulte Referência do evento de registro CDR.