# API e Webhook {% hint style="info" %} Opção: caso prefira para a sua integração via webhook utilize o Pluga.co {% endhint %} ## 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.** {% hint style="info" %} **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. {% endhint %} ## 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**: ; 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**: ; Assim que o contato navegar até o menu “Mais informações”, será feita uma requisição **POST** para essa **URL**.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.simplesdesk.com.br/developers/api-e-webhook.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.