Objetivo

A API de Eventos permite consultar os eventos disparados nos atendimentos de um determinado Assistente do Zenvia NLU.

API de eventos

Permite consultar os eventos disparados nos atendimentos de um determinado Assistente do Zenvia NLU.

Request

Endpoint: POST https://api.altubots.com/events/<instancia>

Header: x-api-key: <token>

Body template:

{
    "filters": {
       "assistantId": "ID do assistente",
       "identifier": "Identificador do contato",
       "contactId": "ID do atendimento",
       "environment": "Ambiente (dev, homol ou prod)",
       "externalId": "ID do sistema externo quando o evento é relativo a uma integração, por exemplo",
       "eventName": "Nome (identificador) do evento",
       "startDate": "Início do período da consulta (Y-M-d H:m:s)",
       "endDate": "Fim do período da consulta (Y-M-d H:m:s)",
       "limit": "Quantidade de resultados por página", //Default: 100 - max: 1000
       "sort": "Define a ordem de retorno sendo ASC|DESC - o padrão é DESC" 
    },
    "pagination": "Hash para consultar a próxima página"
}

 

Response

Status 200 (OK - Eventos encontrados)

Body (exemplo):

{
      "events": [
         ...
         {
             "id": 13213,
             "assistantId": 1,
             "channel": "whatsapp"
             "contactId": 16267,
             "externalId": null,
             "eventId": 12,
             "eventName": "transbordo",
             "extra1": null,
             "extra2": null,
             "details": {
                  "cpf": "12345678909",
                  "skill": "assistencia_tecnica"
             },
             "date": "2020-12-04T14:53:11"
          },
          ...
    ],
    "resultCount": 150,
    "pagination": "Hash para consultar a próxima página"
}

 

Atributos de um evento:

• id: ID único do evento
• assistantId: Assistente em que o evento foi gerado
• channel: canal do atendimento
• contactId: Atendimento em que o evento foi gerado
• externalId: ID do sistema externo, caso o evento seja relacionado a uma integração, por exemplo.
• eventId: ID do tipo do evento
• eventName: Identificador do tipo do evento
• extra1: Atributo extra 1.
• extra2: Atributo extra 2.
• details: Objeto que contém todos os dados referentes ao evento. Esse objeto é flexível e os dados podem variar de evento para evento.
• date: Data em que o evento foi disparado (UTC).

Status code 400 (Bad Request)

Body:

{
     "status": "error",
     "message": "Bad request",
     "invalidParams": [
            ...
   ]
}

 

Status code 401 (Unauthorized)

Body:

{
       "status": "error",
       "message": "Unauthorized"
}

 

Status code 404 (Not Found - Eventos não encontrados)

Body:

{
     "status": "ok",
     "events": [],
     "resultCount": 0
}

 

Status code 500 (Internal Server Error)

Body:

{
    "status": "error",
    "message": "Unexpected error"
}

 

Observações

• Máximo de resultados por consulta: 1000
  
  • Utilizar pagination para buscar páginas seguintes
• O resultado sempre será ordenado pelos eventos mais recentes
• Os filtros não são obrigatórios. Caso nenhum for passado, o resultado trará os eventos mais recentes da instância
• Limite de 50000 consultas por dia e 10 por segundo

Dados dos atendimentos na API de Eventos

A API de eventos agora tem um campo extra com informações sobre o atendimento:

"flags":{
       "includeContactsData": true
  }

 

Por padrão, esse campo recebe o valor de false, mas ao incluí-lo na chamada da API o retorno terá um campo com dados como ID, nome, CPF, e-mail e phone atrelados aos eventos.

Exemplo de resposta parcial da api com o campo igual a true:

{
      "id": 1232,
      "assistantId": 29,
      "contactId": 730,
      "externalId": "ckhzb8v2p003x0un3cs7basdx",
      "eventId": 16,
      "eventName": "saudacoes",
      "extra1": null,
      "extra2": null,
      "details": {
           "mensagem_bot": "ola"
      },
      "date": "2020-12-04T14:53:11",
      "contact": {
           "id": 730,
           "name": null,
           "cpf": null,
           "email": null,
           "phone": null
      }
}

 

Nota: O campo date retorna o valor em horário UTC - 3 (Fortaleza).

API de disparo de eventos

Permite disparar eventos de API.

As credenciais a serem usadas são as mesmas que para a API de eventos.

Para usar a API, copie o endpoint que se encontrará na aba api de disparo de eventos e preencha o body com as informações necessárias. Segue um template de exemplo:

{
      "assistant_id": <id do assistente>,
      "contact_id": <id do contato>
      "event_name": <nome do evento de api>,
      "extra1": <extra1>,
      "extra2": <extra2>,
      "details": {
           "field1": "<value1>",
           "field2": "<value2>"
 },
      "channel": <channel por onde o atendimento será feito>
}

 

Atributos:

• dcassistant_id: id do assistente;
• contact_id (opcional): id do contato (deve ser um id de um contato existente)
• event_name: nome do evento (deve ser Evento de api e deve existir)
• extra1 (opcional);
• extra2 (opcional);
• details (opcional): limite de 1024 caracteres e deve ser um objeto. Qualquer tipo diferente vai ser salvo como {}
• channel
  
  • Se o contact_id estiver presente, ele se torna opcional
  • Caso não tiver o contact_id, ele se torna obrigatório
  • Channels aceitos: api, apple, facebook, gbm, rcs, whatsapp, widget, workplace

Na seção de eventos no nó em builder, não será possível disparar um evento de apipois ela é reservada apenas para disparo de eventos personalizados.

Caso tente utilizar um evento de api, não será disparado e surgirá um issue do tipo Evento inválido.