Validação e eventos Webhook no WOZTELL | Integração segura

Ganchos da Web

VALIDAÇÃO

Todos os eventos webhook virão com uma assinatura ("X-Woztell-Signature") no cabeçalho para fins de validação. Cada evento webhook pode ser validado usando o método a seguir.
  1. Usando o algoritmo HMAC-SHA256 com o segredo do canal como chave secreta, calcule o digest do corpo da requisição.
  2. Confirme que o digest codificado em Base64 corresponde à assinatura no cabeçalho da requisição X-Woztell-Signature.

Mensagens recebidas

Ao assinar este webhook, você receberá os eventos normalizados que o WOZTELL pré-processou para todas as plataformas suportadas.

Exemplo do WhatsApp

Mensagem de texto:

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "Olá"
  }
  "member": "memberId",
  "channel": "channeId",
  "app": "appId",
  "memberExtraData": {
    "field": "Teste Metadata",
    "path": "gender"
  }
}


Mensagem de vídeo:

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "MISC",
  "data": {
    "attachments": [{
      "type": "VIDEO",
      "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
    }],
  }
  "member": "memberId",
"channel": "channeId",
"app": "appId",
"memberExtraData": {
"field": "Teste Metadata",
"path": "gender"
}
}

Atualização do status da mensagem

Além do evento de mensagem, você também pode receber atualizações do status da mensagem assinando as mensagens recebidas, como os eventos ENVIADO, ENTREGUE e LIDO do WhatsApp.

Exemplo do WhatsApp

Quando o status da mensagem se tornar LIDO:

{
  "to": "85268227287",
  "timestamp": 1701914905000,
  "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA",
  "from": "85254063598",
"data": {
    "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA"
  },
  "type": "READ",
  "eventType": "INBOUND"
  ,
  "member": "MEMBER_ID",
  "channel": "CHANNEL_ID",
  "app": "APP_ID"

Mensagens enviadas

body


PropriedadeTipoDescrição
typeStringPode ser BOT ou MANUAL. Indica se a mensagem enviada é do chatbot ou da API/Broadcast
memberStringID do membro
channelStringID do canal
appStringID do app
metaObjectapiSource que inclui informações da integração de origem
memberExtraDataObjectDados extras do membro e um caminho válido para o membro
customHeadersDataObjectChave e valor personalizados do cabeçalho
messageEventObjectObjeto messageEvent contendo a mensagem normalizada


messageEvent


PropriedadeTipoDescrição
fromStringID do remetente
toStringID do destinatário
timestampNúmeroTimestamp Unix
typeStringTipo de mensagem
dataObjetoDados da mensagem para o tipo de mensagem correspondente
messageIdStringID da mensagem na plataforma externa (esta propriedade pode não existir)


meta


PropriedadeTipoDescrição
agentUserIdStringID do usuário que enviou a mensagem.
sourceObjectInformações da integração de origem; idêntico ao apiSource
apiSourceObjectInformações da integração de origem; será descontinuado em breve


_source_


PropriedadeTipoDescrição
integrationIdStringTipo de integração da origem
buildNúmeroVersão da integração
appIntegrationStringID da integração


Evento de exemplo


{
  "type": "MANUAL",
  "app": "APP_ID",
  "channel": "CHANNEL_ID",
  "member": "MEMBER_ID",
  "eventType": "API_OUTBOUND",
  "meta": {
    "agentUserId": "59cb495865243d002c6fc1f5",
    "apiSource": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    }
},
    "__source__": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    }
},
  "messageEvent": {
    "from": "14132521446",
    "to": "85260903521",
"data": {
"text": "hihi"
},
"type": "TEXT",
"timestamp": 1712807869354,
"messageId": "wamid.HBgLODUyNjA5MDM1MjEVAgARGBJFMkI5MkQwODQ1NDc3Q0UwM0QA"
  }, 
}

Ideia
NOTA

O agentUserId na mensagem enviada pode ser usado para obter informações do membro da equipe com a Open API consulta:

query getTeamMembersUserIdAndEmail
{
  apiViewer {
    app {
      teamMembers {
        user {
          _id
          email {
            email
          }
        }
      }
    }
  }
}

Mensagens de saída do bot

As mensagens de resposta do chatbot serão enviadas para o webhook designado.

Mensagens de saída da API

As mensagens enviadas via API SendResponse serão enviadas para o webhook designado.

Mensagens de saída de broadcast

As mensagens enviadas via Broadcast serão enviadas para o webhook designado.

Eventos de atualização de membros

Ao assinar estes eventos, você receberá notificações sempre que houver alteração no status de um membro deste canal.

Os Eventos de atualização de membros incluem: Criação de membro, Atualização do status de assinatura do membro, Atualização do status do livechat do membro, Atualização dos meta dados do membro, Atualização dos dados temporários do membro e Atualização das tags do membro.

body


PropriedadeTipoDescrição
eventTypeStringMEMBER_UPDATE
functionNameStringNORMAL_UPDATE_MEMBER: atualiza manualmente o membro na página de membros;
BOT_UPDATE_MEMBER: atualiza o membro com o bot
memberStringID do membro
channelStringID do canal
appStringID do app
beforeObjetoStatus do membro antes da alteração
afterObjetoStatus do membro após a alteração

Evento de exemplo

{
  "eventType": "MEMBER_UPDATE",
  "functionName": "NORMAL_UPDATE_MEMBER",
  "member": "memberId",
  "channel": "channelId",
  "app": "appId",
  "before": {
    "liveChat": false,
    "tempData": {
      "faqAns": [],
      "listLength": 5
    }
,
    "tags": [
      "test_broadcast"
    ]
  }
,
  "after": {
    "liveChat": true,
    "tempData": {
      "faqAns": [],
      "listLength": 1
    }
,
    "tags": [
      "test_broadcast",
      "testing_tag_2"
    ]
  }
}

Atualizações em lote de membros

Quando vários membros forem atualizados em lote ao mesmo tempo, você receberá o tipo de evento BATCH_MEMBER_UPDATE.

body

PropriedadeTipoDescrição
eventTypeStringBATCH_MEMBER_UPDATE
functionNameStringFunção de atualização em lote, incluindo OPEN_API_BATCH_CREATE_CHAT, OPEN_API_UPDATE_MEMBERS, OPEN_API_BATCH_UPDATE_MEMBERS, NORMAL_UPDATE_MEMBERS, BATCH_ADD_TAGS, BATCH_DELETE_TAGS, BATCH_REPLACE_TAGS
membersArrayArray de IDs de membros
channelStringID do canal
appStringID do app
updateObjetoDetalhes da atualização do membro

Evento de exemplo

{
  "eventType": "BATCH_MEMBER_UPDATE",
  "functionName": "BATCH_ADD_TAGS",
  "members": [
    "memberId_1",
    "memberId_2",
    "memberId_3",
    "memberId_4",
    "memberId_5",
    "memberId_6"
  ],
  "channel": "channelId",
  "app": "appId",
  "update": {
    "$addToSet": {
      "tags": {
        "$each": [
          "testing_tag_1"
        ]
      }
    }
}

Eventos acionados por nó

Ao assinar este evento, você receberá notificações sempre que um nó for acionado neste canal.

body

PropriedadeTipoDescrição
eventTypeStringNODE_TRIGGER
appStringID do app
channelStringID do canal
memberStringID do membro
timestampStringHora em que o nó foi acionado
nodeStringnodeId
compositeIdStringID único de um nó
treeStringID da árvore
messageEventObjetoObjeto messageEvent contendo a mensagem normalizada

Evento de exemplo

{
  "app": "appId",
  "channel": "channelId",
  "member": "memberId",
  "timestamp": 1680605255829,
  "node": "nodeId"
  ,
"eventType": "NODE_TRIGGER"
  ,
"messageEvent": {
    "to": "123461662163"
    ,
"timestamp": 1680605248000
    ,
"messageId": "wamid.HLavODUyNTpRNjM1OTgVAgASGBYzRUabcjRDNTcxQjhPQ8E3MEI0MkFCAA=="
    ,
"from": "85212345678"
    ,
"type": "TEXT"
    ,
"data": {
      "text": "Teste"
    }
  }
}

Gerenciar webhooks no canal

O novo sistema de webhook do canal permite melhor controle sobre os eventos recebidos pelo seu webhook. Na página "Ambiente" do canal, você pode gerenciar seus webhooks assinados para cada ambiente de um canal.



Ideia
NOTA

Se o seu sistema de webhook do canal ainda estiver na versão descontinuada, um lembrete de atualização será exibido sempre que você entrar no ambiente do canal.


Criar webhooks

  1. Para adicionar um webhook ao seu canal, selecione "+ Criar novo webhook".
  1. Insira a URL do webhook e selecione os eventos aos quais deseja assinar. Por fim, clique em "Confirmar" para confirmar as configurações do webhook.
  1. Após fechar o modal anterior, lembre-se de "Salvar" novamente as configurações do ambiente.

Editar webhooks

  1. Para editar seu webhook, clique em "mais" e selecione "Editar".
  1. Lembre-se de "Confirmar" as alterações feitas no webhook existente.

Remover webhooks

Para remover seu webhook, clique em "mais" e selecione "Remover".

  1. O novo sistema de webhook do canal também suporta o envio de Metadados do membro e Cabeçalhos personalizados. Para aplicá-los ao seu webhook, selecione "Mostrar menu avançado".
  1. Em seguida, você verá as seções de Metadados do membro e Cabeçalhos personalizados.
  1. Após preencher todos os valores necessários, você pode clicar em "Confirmar" para confirmar as configurações.

Última atualização em