Documento API
de Integração
Abaixo segue as informações sobre o funcionamento da
integração via API da plataforma ChatHub com
demais aplicações.
INTRODUÇÃO
Nós não temos WEBHOOKS ou API. Não é possível enviar mensagens sem que o contato solicite algo.
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ívelacompanhar 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.
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
- *contact: informações do contato em nosso
- *uid: código do
- *type: origem do contato, podendo ter as opções: WHATSAPP, FACEBOOK e
- *key: número do telefone ou código do canal do cliente
- *name: nome do
- *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:
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.
○ *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:
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.
- *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:
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 anexo
Veja um exemplo do JSON que deverá vir no RESPONSE:
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:
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_COSTOMER_SERVICE.
- *departmentUUID: uuid do departamento.
- userUUID: uuid do atendente.
Veja um exemplo do corpo da resposta para criar apenas para o departamento:
Veja um exemplo do corpo da resposta para criar para o departamento e atendente:
