Documentação da API do Bot Woztell - Referência e Códigos de Erro

BotAPI

API de Bot é construída em torno de REST. Você pode chamar nossas APIs através de uma solicitação HTTP padrão com a chave da API colocada no parâmetro da consulta. Em seguida, o WOZTELL retornará uma resposta codificada em JSON, com os dados correspondentes que podem determinar se as operações relacionadas foram concluídas.

Antes de começar, você pode primeiro baixar a Coleção do Postman da API do Bot e Ambiente no formato JSON.

Se o seu navegador não conseguir baixar os arquivos JSON após clicar no URL...
Por favor, clique com o botão direito e "Inspecionar" para abrir as ferramentas de desenvolvedor. Selecione "Fonte" e clique com o botão direito para baixar o arquivo de origem clicando em "Salvar como..."

Autenticação​​

accessToken​

O token de acesso deve ser colocado como um parâmetro de consulta como accessToken na solicitação. O token de acesso pode ser gerado seguindo este guia.

Cada API pode ter um escopo diferente, escolher qualquer escopo é suficiente para chamar a API.

Tipo de Esquema de Segurança Nome do parâmetro da consulta
Chave da API accessToken
dica

Alternativamente, o Token de Acesso pode também ser colocado no cabeçalho de autorização como Bearer Token.


Enviar Respostas​

Para enviar respostas em nome do seu chatbot para um membro específico no WOZTELL.

Gerar Modelo em JSON​

O WOZTELL permite criar e gerenciar modelos de mensagens na plataforma. Ao enviar respostas com Bot API, há uma maneira conveniente de obter o conteúdo de um modelo em JSON.

  1. Em "Recursos", selecione "Respostas".
  1. Selecione "+ Nova Resposta".
  1. Expanda a guia. Selecione "Adicionar Plataforma" e selecione "WhatsApp Cloud". Isso permitirá aplicar tipos de mensagem específicos para o WhatsApp Cloud.
  1. Selecione "Modelo de mensagem" entre os tipos de mensagem.
  1. Selecione a "Integração" relevante e clique em "Atualizar Modelo de Mensagem".
  1. Escolha o "Modelo de Mensagem" que você gostaria de usar. Em seguida, selecione a "Política de Idioma" e o "Idioma" relevantes.
  1. Preencha os componentes necessários no modelo, como imagens e parâmetros. Clique em "Confirmar" para sair desta janela.
  1. Na resposta, altere para "Avançado" para obter o conteúdo do modelo em JSON.


Solicitação​

Autorização: accessToken(bot:sendResponses, bot:admin)

Parâmetros de consulta:

Parâmetro de consulta Obrigatório Tipo Descrição
accessToken Sim apiKey O token de acesso deve ser colocado como um parâmetro de consulta como accessToken na solicitação. O token de acesso pode ser gerado seguindo este guia. Cada API pode ter um escopo diferente, escolher qualquer um escopo é suficiente para chamar a API

Esquema do corpo da solicitação: application/json

Campo Obrigatório Tipo Descrição
channelId Sim String ID do canal no WOZTELL
memberId Não String Either memberId, recipientId
ID do membro no WOZTELL
recipientId Não String Either memberId, recipientId
ID do destinatário na integração. Exemplo: PSID no Facebook, número de telefone no WhatsApp, etc (Não garantido, consulte o criador da integração, se necessário)
response Sim array Os dados que você deseja enviar como resposta. Você pode construir o objeto de resposta consultando as documentações de integração ou copiando do Bot builder.

Exemplo de Solicitação:

  • WhatsApp
  • Facebook

{
  "channelId": "5fe729b3094223123123",
  "recipientId": "85291239123",
  "response": [
    {
      "type": "TEMPLATE",
      "elementName": "testing",
      "languageCode": "zh_CN",
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "video",
              "video": {
                "id": "caf8bc1a-fbc0-4dc3-9d08-434sdf6df"
              }
            }
          ]
        },
        {
          "type": "button",
          "sub_type": "quick_reply",
          "index": "0",
          "parameters": [
            {
              "type": "payload",
              "payload": "123"
            }
          ]
        }
      ]
    }
  ]
}
Copiar


Resposta​

Código de Status Descrição
200 Esta solicitação retorna o código HTTPS 200 se o bot iniciar a execução. No corpo da resposta, uma String JSON contendo uma flag "ok" com valor 1 indicando sucesso na execução.

Esquema do Corpo da Resposta: application/json


Objeto Tipo Descrição
ok Int Valor: 1, status que indica se esta solicitação foi bem-sucedida ou não
membro String ID do Membro WOZTELL
sendResult Objeto Objeto do resultado do envio
sendResult.ok Int Indica se o servidor de integração conseguiu receber a resposta
sendResult.member String ID do Membro WOZTELL
sendResult.result Objeto Array de resultados de envio do servidor de integração, deve conter ok, messageEvent, error (Opcional) campos para exibir o resultado de cada resposta
Código de Status Descrição
500 Esta solicitação retornará o código HTTPS 500 se encontrar um erro antes da execução do bot.

Esquema do Corpo da Resposta: application/json

Objeto Tipo Descrição
ok Int Sempre 0, indica que o Bot encontrou um erro antes de enviar a resposta para o servidor de integração
err_code String Código de erro no WOZTELL
erro String Mensagem de erro


Resposta de Exemplo

  • Código de Status: 200
  • Tipo de Conteúdo: application/json
  • Sucesso
  • Falha

{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResult": {
    "ok": 1,
    "member": "5ece50f3bf385b25c4e08db5",
    "result": [
      {
        "result": {
          "messages": [
            {
              "id": "gBGGhSZphigfAglySd38a9T4jAE"
            }
          ],
          "meta": {
            "api_status": "stable",
            "version": "2.31.5"
          }
        },
        "messageEvent": {
          "from": 85291239123,
          "to": 85232193219,
          "data": {
            "text": "Hello World"
          },
          "type": "TEXT",
          "timestamp": 1611900841740,
          "messageId": "gBGGhSZphigfAglySd38a9T4jAE"
        },
        "chatId": "5ece50f3bfa915g5c4e08db5"
      },
      {
        "result": {
          "messages": [
            {
              "id": "gBGGhSZafi5th8lySd38a9T4jAE"
            }
          ],
          "meta": {
            "api_status": "stable",
            "version": "2.31.5"
          }
        },
        "messageEvent": {
          "from": 85291239123,
          "to": 85232193219,
          "data": {
            "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
          },
          "type": "IMAGE",
          "timestamp": 1611900841740,
          "messageId": "gBGGhSZafi5th8lySd38a9T4jAE"
        },
        "chatId": "5ece50f3bfa915g5c4e08db6"
      }
    ]
  }
}
Copiar

  • Código de status: 500
  • Tipo de conteúdo: application/json
{
  "ok": 0,
  "err": "User is not authorized."
}
Copiar

Redirecionar Membro para o Nó​

Redirecionando um membro para um nó específico na árvore e executando todos ou alguns componentes do nó. Isso é útil para realizar operações complexas em um membro e manter toda a lógica do bot na árvore, em vez de codificar diretamente em uma API.

Se o memberId não for fornecido, o sistema buscará um membro com o recipientId fornecido.

Objeto Meta​

Para usar o objeto meta passado pela API na transformação da resposta ou nas ações do nó direcionado, use o seguinte código para acessar seu meta.

this.agendaMeta
Copiar

Exemplo:

To access in transform response or actions
return new Promise((resolve, reject) => {
  // ...
  const name = this.agendaMeta.name // "Sanuker"
  const orderId = this.agendaMeta.orderId // "5ecf6be76fcfda6b139d802c"
  // ...
})
Copiar

Solicitação​

POST https://bot.api.woztell.com/redirectMemberToNode

Autorizações: accessToken(bot:redirectMemberToNode, bot:admin, api:admin)

Parâmetros da Consulta:

Parâmetro da Consulta Obrigatório Tipo Descrição
accessToken Sim apiKey O token de acesso deve ser colocado como um parâmetro de consulta chamado accessToken na solicitação. O token de acesso pode ser gerado seguindo este guia. Cada API pode ter um escopo diferente, mas basta escolher qualquer escopo para chamar a API

Esquema do Corpo da Solicitação: application/json

Campo Obrigatório Tipo Descrição
channelId Sim String ID do Canal no WOZTELL
memberId Não String Ou memberId, recipientId
ID do Membro no WOZTELL
recipientId Não String Ou memberId, recipientId
ID do destinatário na integração. Exemplo: PSID no Facebook, número de telefone no WhatsApp, etc (Não garantido, consulte o criador da integração, se necessário)
redirect Sim Objeto O nó de destino para o qual você deseja redirecionar.
redirect.tree Sim String Árvore de destino para a qual você deseja redirecionar.
redirect.nodeCompositeId Sim String Nó de destino para o qual você deseja redirecionar.
redirect.runPreAction Não Booleano Executa a ação anterior ao redirecionamento; pode ser configurado como true ou false
redirect.sendResponse Não Booleano Redireciona e envia a resposta; pode ser configurado como true ou false
redirect.runPostAction Não Booleano Executa a ação pós-redirecionamento; pode ser configurado como true ou false
meta Não Objeto Opcional
Objeto meta fornecido para o nó.
O objeto meta pode ser acessado no nó de destino via this.agendaMeta.

Solicitação de Exemplo

Tipo de conteúdo: application/json

{
  "channelId": "5ece50e72efaabd58ef55027",
  "memberId": "5ece50f3bf385b25c4e08db5",
  "recipientId": null,
  "redirect": {
    "tree": "5ecf6cfba3b6643c33a64079",
    "nodeCompositeId": "j4Bivxm0GWhnNV1m",
    "runPreAction": true,
    "sendResponse": true,
    "runPostAction": true
},
  "meta": {
    "name": "Sanuker",
    "orderId": "5ecf6be76fcfda6b139d802c"
  }
}
Copiar

Resposta​

Código de Status Descrição
200 Esta solicitação retornará o código HTTPS 200 se o bot iniciar a execução.

Esquema do Corpo da Resposta: application/json

Objeto Tipo Descrição
ok Int Sempre 1, indica que o Bot executou o comando de envio de resposta
membro String ID do Membro WOZTELL
sendResult Objeto Resultado do envio
sendResult.ok Int Indica se o servidor de integração recebeu a resposta com sucesso
sendResult.member String ID do Membro WOZTELL
sendResult.result [Objeto] Array de resultados de envio do servidor de integração, deve conter ok, messageEvent, error (Opcional) campos para exibir o resultado de cada resposta

Código de Status Descrição
500 Esta solicitação retornará o código HTTPS 500 se encontrar um erro antes da execução do bot.
Objeto Tipo Descrição
ok Int Sempre 0, indica que o Bot encontrou um erro antes de enviar a resposta ao servidor de integração
err_code Int Código de erro no WOZTELL
erro String Mensagem de erro

Resposta de Exemplo

  • Código de Status: 200
  • Conteúdo: application/json
{
  "ok": 1,
  "member": "5ece50f3bf385b25c4e08db5",
  "sendResult": {
    "ok": 1,
    "member": "5ece50f3bf385b25c4e08db5",
    "result": [
      {
        "ok": 1,
        "messageEvent": {
          "from": 85291239123,
          "to": 85232193219,
          "data": {
            "url": "https://miro.medium.com/max/1200/1*mk1-6aYaf_Bes1E3Imhc0A.jpeg"
          },
          "type": "IMAGEM",
          "timestamp": 1611900841740,
          "messageId": "gBGGhSZphigfAglySd38a9T4jAE"
        }
      }
    ]
  }
}
Copiar
  • Código de Status: 500
  • Conteúdo: application/json
{
  "ok": 0,
  "err_code": 108,
  "err": "channelId é obrigatório."
}
Copiar

Códigos de Erro​

WOZTELL retornará os códigos de erro correspondentes para o lado da solicitação quando ocorrer um erro.

Código Descrição
100 O número de telefone fornecido é inválido. Ou o número não existe ou não possui uma conta do WhatsApp vinculada
104 PSID do Facebook inválido ou o token de acesso no canal designado é inválido
108 Parâmetro(s) está(ão) faltando
112 Canal com o channelId correspondente não pode ser encontrado
113 Erro no servidor do WhatsApp
Última atualização em