API e Webhook

Opção: caso prefira para a sua integração via webhook utilize o Pluga.co

Introdução

Não é possível enviar mensagens sem que o contato solicite algo. (Para isto utilize as mensagens programadas) Nossa integração é feita através dos menus do bot. A resposta para o contato deve ser feita no RESPONSE de cada REQUEST enviada para as URLs configuradas nos menus. É possível acompanhar todas as integrações no painel do gestor, em: Relatórios > Integrações.

IMPORTANTE: Caso aconteça algum erro na integração, por padrão, será enviado o menu inicial para o contato. Fluxo da Integração Quando o contato selecionar o menu de Integração, será feito um REQUEST do tipo POST para a URL configurada no MENU, enviando o JSON com todos os dados dele. No RESPONSE deverá ser retornado o JSON com um dos padrões abaixo, dependendo do que deseja responder para ele. Na solicitação HTTP, será incluído o header mz-integration, contendo a informação configurada no menu. Esse header serve apenas para você fazer algum tipo de controle de segurança, então você pode colocar qualquer informação nesse campo.

Fluxo de Integração

Quando o contato selecionar o menu de Integração, será feito um REQUEST do tipo POST para a URL configurada no MENU, enviando o JSON com todos os dados dele. No RESPONSE deverá ser retornado o JSON com um dos padrões abaixo, dependendo do que deseja responder para ele. Na solicitação HTTP, será incluído o header mz-integration, contendo a informação configurada no menu. Esse header serve apenas para você fazer algum tipo de controle de segurança, então você pode colocar qualquer informação nesse campo.

REQUESTS

O corpo da solicitação HTTP é enviado no formato JSON e atende o padrão abaixo. Os atributos com asterisco, são obrigatórios. ● *id: código da solicitação. ● *text: texto que o contato digitou. ● *contact: informações do contato em nosso sistema. ○ *uid: código do contato. ○ *type: origem do contato, podendo ter as opções: WHATSAPP, FACEBOOK e BOTSITE.

○ *key: número do telefone ou código do canal do cliente

○ *name: nome do contato.

○ *fields: campos de segmentação. ● data: o conteúdo desse atributo será dinâmico, pois você irá informar na resposta de uma solicitação. Veja um exemplo do corpo da solicitação que será enviada no início da integração:

{
"id": 215123,
"text": "Hello world!",
"contact": {
"uid": "15295",
"type": "WHATSAPP",
"key": "5513999999999",
"name": "Robson",
"fields": {
"cpf": "111.111.111-11",
"celular": "(11) 11111-1111"
}
},
"data": {}
}

RESPONSE

As mensagens que são retornadas de seus sistema, deverão seguir alguns critérios para tudo funcionar perfeitamente. Cada tipo de mensagem tem um comportamento diferente em nosso Bot. MENU É possível retornar novos menus dinâmicos, para o cliente navegar. Será enviada uma mensagem de texto para o contato na estrutura de menus, podendo conter anexos, exigindo a escolha de uma das opções listadas.

O corpo da solicitação HTTP é enviado no formato JSON e atende padrão abaixo.

Os atributos com asterisco, são obrigatórios.

● *type: MENU.

● *text: texto que será enviado para o contato.

● attachments: lista de anexos que serão enviados.

○ *position: a posição do anexo, referente ao texto, podendo ser: BEFORE (antes) ou AFTER (depois).

○ *type: tipo do anexo, podendo ser: IMAGE (imagem) ou DOCUMENT (documento).

○ *name: o nome do anexo.

○ url: o caminho público onde está o anexo.

○ base64: arquivo no formato base64 (utilizado caso a URL não seja pública)

● *items: opções que serão listadas para o contato.

○ *number: número da opção.

○ *text: texto que será apresentado após o número.

○ *callback: o caminho que será solicitado quando o contato escolher essa opção.

■ *endpoint: o caminho público que será solicitado.

■ data: estrutura em JSON, contendo informações adicionais que serão enviadas na solicitação.

Veja um exemplo do JSON que deverá vir no RESPONSE:

{
"type": "MENU",
"text": "My first menu integration.",
"attachments": [{
"position": "BEFORE",
"type": "IMAGE",
"name": "image.png",
"url": "https://yourdomain.com/cdn/logo.png"

}],
"items": [{
"number": 1,
"text": "Menu 1",
"callback": {
"endpoint": "https://yourdomain.com/api/menu_1",
"data": {
"example": "Additional information"
}
}
},
{
"number": 2,
"text": "Menu 2",
"callback": {
"endpoint": "https://yourdomain.com/api/menu_2",
"data": {}
}
}]
}

PERGUNTA

Será enviada uma mensagem de texto para o contato, podendo conter anexos, esperando apenas uma mensagem de texto do contato. O corpo da solicitação HTTP é enviado no formato JSON e atende o padrão abaixo.

Os atributos com asterisco, são obrigatórios.

● *type: QUESTION.

● *text: texto que será enviado para o contato.

● attachments: lista de anexos que serão enviados.

○ *position: a posição do anexo, referente ao texto, podendo ser: BEFORE (antes) ou AFTER (depois).

○ *type: tipo do anexo, podendo ser: IMAGE (imagem) ou DOCUMENT (documento).

○ *name: o nome do anexo.

○ url: o caminho público onde está o anexo.

○ base64: arquivo no formato base64 (utilizado caso a URL não seja pública)

● *callback: o caminho que será solicitado quando o contato escolher essa opção.

○ *endpoint: o caminho público que será solicitado.

○ data: estrutura em JSON, contendo informações adicionais que serão enviadas na solicitação.

Veja um exemplo do JSON que deverá vir no RESPONSE:

{
"type": "QUESTION",
"text": "Enter your document number.",
"attachments": [{
"position": "BEFORE",
"type": "IMAGE",
"name": "image.png",
"url": "https://yourdomain.com/cdn/logo.png"
}],
"callback": {
"endpoint": "https://yourdomain.com/api/question",
"data": {
"example": "Additional information"
}
}
}

INFORMAÇÃO

Será enviada uma mensagem de texto para o contato, podendo conter anexos. O corpo da solicitação HTTP é enviado no formato JSON e atende o padrão abaixo.

Os atributos com asterisco, são obrigatórios.

● *type: INFORMATION.

● *text: texto que será enviado para o contato.

● attachments: lista de anexos que serão enviados.

○ *position: a posição do anexo, referente ao texto, podendo ser: BEFORE (antes) ou AFTER (depois).

○ *type: tipo do anexo, podendo ser: IMAGE (imagem) ou DOCUMENT (documento).

○ *name: o nome do anexo.

○ url: o caminho público onde está o contato.

○ base64: arquivo no formato base64 (utilizado caso a URL não seja pública)

● newTicket: criar um atendimento para o cliente

○ *departmentUUID: uuid do departamento.

○ userUUID: uuid do atendente.

Veja um exemplo do JSON que deverá vir no RESPONSE:

{
"type": "INFORMATION",
"text": "Your invoice.",
"attachments": [{
"position": "BEFORE",
"type": "IMAGE",
"name": "image.png",
"url": "https://yourdomain.com/cdn/logo.png"
},
{
"position": "AFTER",
"type": "DOCUMENT",
"name": "document.pdf",
"url": "https://yourdomain.com/cdn/document.pdf"
}]
}

DIRECIONAR PARA UM MENU ESPECÍFICO

O seu contato será direcionado para o menu informado. O corpo da solicitação HTTP é enviado no formato JSON e atende o padrão abaixo.

Os atributos com asterisco, são obrigatórios.

● *type: DIRECT_TO_MENU.

● *menuUUID: uuid do menu que será redirecionado.

Veja um exemplo do corpo da resposta:

{
"type": "DIRECT_TO_MENU",
"menuUUID": "88a4fbb2-7df3-4fd1-85ea-68956400cf88"
}

CRIAR UM ATENDIMENTO

Irá criar um atendimento para o departamento informado. O corpo da solicitação HTTP é enviado no formato JSON e atende o padrão abaixo.

Os atributos com asterisco, são obrigatórios.

● *type: CREATE_CUSTOMER_SERVICE.

● *departmentUUID: uuid do departamento.

● userUUID: uuid do atendente.

● *text: texto que será enviado para o contato.

● attachments: lista de anexos que serão enviados.

○ *position: a posição do anexo, referente ao texto, podendo ser: BEFORE (antes) ou AFTER (depois).

○ *type: tipo do anexo, podendo ser: IMAGE (imagem) ou DOCUMENT (documento).

○ *name: o nome do anexo.

○ url: o caminho público onde está o anexo.

○ base64: arquivo no formato base64 (utilizado caso a URL não seja pública)

Veja um exemplo do corpo da resposta para criar apenas para o departamento:

{
"type": "CREATE_CUSTOMER_SERVICE",
"departmentUUID": "88a4fbb2-7df3-4fd1-85ea-68956400cf88",
"text": "Your invoice.",
"attachments": [{
"position": "BEFORE",
"type": "IMAGE",
"name": "image.png",
"url": "https://yourdomain.com/cdn/logo.png"
},
{
"position": "AFTER",
"type": "DOCUMENT",
"name": "document.pdf",
"url": "https://yourdomain.com/cdn/document.pdf"
}]
}

Veja um exemplo do corpo da resposta para criar para o departamento e atendente:

{
"type": "CREATE_CUSTOMER_SERVICE",
"departmentUUID": "88a4fbb2-7df3-4fd1-85ea-68956400cf88",
"userUUID": "88a4fbb2-7df3-4fd1-85ea-68956400cf88",
"text": "Your invoice.",
"attachments": [{
"position": "BEFORE",
"type": "IMAGE",
"name": "image.png",
"url": "https://yourdomain.com/cdn/logo.png"
},
{
"position": "AFTER",
"type": "DOCUMENT",
"name": "document.pdf",
"url": "https://yourdomain.com/cdn/document.pdf"
}]
}

EXEMPLOS

No exemplo abaixo, foram criados dois menus de integração: um que retorna uma mensagem e um anexo, e outro que retorna só uma mensagem.

Foi criado o campo de segmentação CPF para auxiliar no exemplo.

É possível acompanhar o log e status das requisições pelo login do gestor, na tela de Relatórios > Integrações.

1º EX: MENSAGEM E ANEXO

Detalhes do menu de integração:

URL: http://demo2254389.mockable.io/chatbot/invoice

Assim que o contato navegar até o menu “Integração - Invoice”, será feita uma requisição POST para essa URL.

Lembrando que os campos de segmentação vão dentro do atributo “fields” no JSON.

2º EXEMPLO MENSAGEM E ANEXO

Detalhes do menu de integração:

URL: http://demo2254389.mockable.io/chatbot/information

Assim que o contato navegar até o menu “Mais informações”, será feita uma requisição POST para essa URL.