Botmaker API
Aqui vamos aprender como acessar a Botmaker API.

Acceso

Para poder acessar os métodos da API e a sua especificação swagger, você deve seguir os seguintes passos que te permitirão obter um token de acesso. Para isso, siga:
    1.
    Acessar a página de configuração de canais
    2.
    Selecionar Botmaker API - Credenciais
    3.
    Gerar um token ou utilizar o que já está gerado. Em particular, é importante guardar o Access Token
Uma vez com o Token, acesse o swagger: https://go.botmaker.com/apidocs/.
Clique no botão Authorize (canto superior direito) e insira o token de acesso no segundo campo de texto, como abaixo. Clique em Authorize.

Modelo de dados

Customer

Em um modelo de dados, um customer simboliza um usuário ou cliente que tenha interagido com o bot. Todas as interações que se realizem em um mesmo canal (WhatsApp, Webchat, Messenger, Twitter, Google Assistant, etc.) seguirão fazendo referência ao mesmo customer.
O customer se compõe dos seguintes dados:
    BUSINESS_ID: o id do bot do qual pertence o usuário. Para um mesmo bot, todos os customers terão o mesmo número identificador.
    CREATION_TIME: data de criação do customer, ou seja, de sua primeira interação.
    CHAT_PLATFORM_ID: representa a plataforma por qual o usuário interagiu. Pode ser WhatsApp, Webchat, Messenger, Twitter, Google Assistant, Microsoft Teams, etc.
    CHAT_CHANNEL_ID: é o canal por qual interagiu o usuário na plataforma. É um id formado pela plataforma + o id do canal. Diferentes páginas no Facebook, por exemplo.
    PLATFORM_CONTACT_ID: id específico gerado pela plataforma do canal utilizado. Junto com o id do canal, permite identificar individualmente o usuário.
    BOT_MUTED: indica se o bot se encontra mutado para este usuário. Quando o bot está apagado, não enviará respostas automáticas ao usuário. O bot se desmuta novamente após 60 minutos de inatividade do usuário.
    PENDING_MSGS: quantidade de mensagens que o bot não entendeu e estão pendentes para serem lidas por um agente humano.
    FIRST_NAME y LAST_NAME: nome e sobrenome do usuário respectivamente.
    LAST_SEEN: data na qual o usuário falou pela última vez.
    PICTURE_URL: imagem do usuário no canal em que pertence.
    _id_: id do usuário
    Variables: o usuário também se compõe de variáveis, que são dados que vão sendo obtidos nas interações com o bot.
    Esses valores fazem parte do customer e aparecerão na API com o último valor que fora obtido de certa variável.
    As variáveis são configuradas (como em linguagens de programação) para salvar seus possíveis valores e podem ser visualizadas ou modificadas na plataforma, na seção de variáveis.
    Tags: são etiquetas que se aplicam a um usuário para posterior identificação. A tag pode ser considerada como uma variáveis booleana (acesa ou apagada).
    Um usuário possui um tag pelas seguintes razões:
      O usuário fala sobre um tema específico com o bot, o qual o tagea automaticamente por esse tópico;
      Em certa intenção há o processo do bot tagear especificamente o usuário para posterior visualização de métricas ou geração de audiências para envio de mensagens push.

Messages

message/download

O objetivo desse endpoint é obter o histórico das mensagens de uma conversa. Cada chamado retorna 500 registros de mensagens, junto com o status do usuário e um operador humano no momento de envio da mensagem.​​‌

Modo de uso

Esse serviço deve ser chamado periodicamente, guardando os dados retornados na sua própria base de dados, para depois analisá-los de acordo com sua necessidade. Cada pedido atualiza na API a data da última mensagem descarregada. Cada novo chamado continua onde terminou o chamado anterior.​ A estrutura JSON devolvida é:
1
{
2
hasMore: Boolean (si hay mas mensajes para pedir; usarlo como condicion de loop)
3
messages: Lista de mensajes
4
count: cantidad de mensajes
5
}
Copied!
​Estes são alguns dos campos do objeto mensagens:‌
    id: id da mensagem
    datas: creation_time, message_date, message_year, message_month, message_week, message_day, message_quarter, message_dayofweek, message_time, message_hour, message_minute, message_second, message_day_name, message_semester, message_bimester
    msg_from, msg_to (me é um usuário, e bot a plataforma)
    sent_by_platform, sent_by_bot, sent_by_user: quando esse parâmetro estiver preenchido com "1" quer dizer que essa informação é verdadeira, se estiver preenchido com " " (nulo, zero, vazio) quer dizer que essa informação é falsa; ou seja, se "sent_by_platform = 1" quer dizer que essa mensagem foi enviada pela plataforma.
    sent_by: neste campo é possível identificar qual agente enviou a mensagem, pode ser: platform, bot, user ou operator.
    message: texto da mensagem enviada
    chat_channel_id: o canal da mensagem (webchat, WhatsApp, Messenger, etc).
    dados do usuário: customer_id, customer_last_seen, customer_platform_contact_id, customer_first_name, customer_last_name, customer_email, customer_has_talked
    dados do usuário no bot: campos uservar_*.​
Exemplo:
A seguir está um exemplo em node.js como deverá ser consumido o serviço:
1
const rp = require('request-promise');
2
3
(async () => {
4
let results = await rp.post('https://go.botmaker.com/api/v1.0/message/download', { headers: { 'access-token': 'your-bot-access-token' }, json: true
5
});
6
7
while (results.hasMore) {
8
results = await rp.post('https://go.botmaker.com/api/v1.0/message/download', { headers: { 'access-token': 'your-bot-access-token' }, json: true });
9
results.messages.forEach(message => saveInDB(message));
10
}
11
12
console.log('done!') })();
Copied!

Parametro fromDate

O parametro fromDate permite rebobinar o ponteiro interno para voltar a pedir os dados em caso de erro ao salvá-los. fromDate pode ser no mínimo de uma semana anterior ao momento atual.‌

Intents

post
https://go.botmaker.com/api/
v1.0/intent/trigger
/intent/trigger
Last modified 1yr ago