{"section":"tutorials","requestedLocale":"pt","requestedSlug":"servico-externo","locale":"pt","slug":"servico-externo","path":"docs/pt/tutorials/weni-by-vtex/integrações/servico-externo.md","branch":"main","content":"Esta documentação descreve como configurar e integrar um **canal externo** para que a plataforma receba e envie mensagens usando um serviço externo. Ela complementa o material existente e detalha os campos e opções disponíveis para que a conexão funcione corretamente.\n\n## Visão geral\n\nUm **canal externo** é uma integração que permite que o sistema de atendimento se conecte a serviços de mensageria de terceiros (ex.: telefones, redes sociais, bots, etc.). Para cada canal é preciso configurar alguns campos básicos e opções, como o tipo de identificador (URN Type), endereço, método HTTP, codificação e tipo de conteúdo. Este documento explica o propósito de cada campo, quando usá-los e quais são os valores disponíveis.\n\n## Tipo de URN (URN type)\n\nO campo **Tipo de URN** indica qual forma de identificador será usada para enviar ou receber mensagens. Cada tipo corresponde à forma como o contato do usuário é representado no canal externo (por exemplo, número de telefone, identificador do WhatsApp, handle do Twitter, etc.). A lista completa de opções é exibida na interface e inclui diversos canais suportados.\n\nO valor **Identificador Externo** (destacado na lista) é o mais indicado quando você quer centralizar diferentes canais em uma mesma integração. Ele permite trabalhar com canais que não correspondem a um tipo específico da lista.\n\n### Principais tipos disponíveis\n\n| Tipo de URN                                                                                                | Exemplo de uso                  |\n| ---------------------------------------------------------------------------------------------------------- | ------------------------------- |\n| **Número de telefone**                                                                                     | Mensagens SMS ou ligações       |\n| **Identificador do Facebook**                                                                              | Messenger/Chat do Facebook      |\n| **Instagram identifier**                                                                                   | Instagram Direct                |\n| **Twitter handle / ID**                                                                                    | Contas no Twitter               |\n| **Identificador Viber / LINE**                                                                             | Apps de mensagens variados      |\n| **Identificador do Telegram**                                                                              | Bots/usuários do Telegram       |\n| **Email**                                                                                                  | Contato via correio eletrônico  |\n| **Identificador do WhatsApp**                                                                              | Integrações via WhatsApp        |\n| **Identificador do Discord / Slack / Teams**                                                               | Plataformas de chat corporativo |\n| **Identificador Freshchat, VK, Rocket.Chat, JioChat, WeChat, Firebase Cloud Messaging, WeniWebChat, etc.** | Outros serviços suportados      |\n\n> **Recomendação:** se você não tiver certeza de qual tipo escolher ou se o canal não se enquadrar em nenhuma categoria específica, selecione **Identificador Externo**. Esse tipo é genérico e permite identificar contatos de diferentes origens.\n\n## Endereço (address)\n\nO campo **Endereço** ou **address** deve ser preenchido **apenas com um nome ou rótulo** que identifique de forma legível o contato ou canal que está sendo recebido. Este campo não deve conter o número de telefone real nem o identificador completo do usuário; seu objetivo é facilitar a identificação interna do endereço quando houver diversas integrações configuradas.\n\n## Método HTTP\n\nO campo **HTTP Method** define como as mensagens serão enviadas ao serviço externo. Estão disponíveis três métodos:\n\n- **GET** – envia dados como parâmetros de URL. Use apenas quando o serviço externo aceitar parâmetros em uma chamada GET.\n- **POST** – envia dados no corpo da requisição. Este é o método mais comum para integrações de mensagens.\n- **PUT** – semelhante ao POST, mas usado quando o serviço externo espera atualizações de recursos existentes.\n\n> **Nota:** ao escolher **POST** ou **PUT** você deve definir também o **Content-Type** (veja a seção 5). Para **GET** o campo Content-Type não é obrigatório.\n\n## Codificação (encoding)\n\nO campo **Codificação** controla como os caracteres da mensagem são processados antes do envio. Isso é útil para evitar erros em plataformas que têm limitações de caracteres ou de texto. As opções são:\n\n| Codificação                 | Quando utilizar                                                                                                                                                                                                  |\n| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Codificação Padrão**      | Envia o texto sem alterações ou codificações extras. Indicado para a maioria dos canais.                                                                                                                         |\n| **Codificação Inteligente** | Efetua substituições e remoção de símbolos potencialmente problemáticos (por exemplo, convertendo emojis em textos). Útil quando o canal externo possui limitações de caracteres ou não suporta certos símbolos. |\n| **Codificação Unicode**     | Converte a mensagem para a forma unicode, preservando todos os caracteres especiais. Use quando o canal exige envio de caracteres em formato unicode                                                             |\n\n## Content-type\n\nO campo **Content type** informa ao serviço externo em qual formato os dados estão sendo enviados. Ele **só é obrigatório** quando o método HTTP selecionado é **POST** ou **PUT**. Para requisições **GET** o campo pode ficar em branco. As opções disponíveis são:\n\n| Content-Type                                           | Descrição                                                                                                                            |\n| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |\n| **URL codificado – application/x-www-form-urlencoded** | Envia os dados no corpo da requisição usando pares chave=valor, codificados como formulário. É o formato padrão de formulários HTML. |\n| **JSON – application/json**                            | Formato JSON, recomendável para APIs modernas.                                                                                       |\n| **XML – text/xml; charset=utf-8**                      | Formato XML, utilizado em algumas integrações legadas.                                                                               |\n\n> **Dica:** sempre verifique a documentação do serviço externo para saber qual Content-Type ele espera. Para APIs REST é comum utilizar application/json.\n\n## Limite de caracteres (max_length)\n\nO campo max_length (ou Maximum length) define a quantidade máxima de caracteres permitida por mensagem enviada. Se o conteúdo da mensagem exceder esse limite, ele será automaticamente dividido em duas ou mais mensagens.\n\nPor exemplo, se o canal externo só permite mensagens com até 1000 caracteres e o texto enviado possui 1500 caracteres, defina max_length = 1000. Nessa configuração a plataforma enviará uma primeira mensagem com 1000 caracteres e uma segunda mensagem com os 500 restantes.\n\n**Observação:** é importante conhecer o limite de caracteres do serviço que você está integrando. Definir max_length com um valor maior do que o suportado pelo canal pode fazer com que as mensagens sejam cortadas ou rejeitadas.\n\n## Exemplo de body e retorno\n\nAbaixo está um exemplo de corpo de requisição (request body) enviado para o canal externo. As variáveis entre chaves (\\{\\{...\\}\\}) serão substituídas dinamicamente pelo sistema quando a mensagem for enviada:\n\n```json\n{\n  \"id\": {{id}},\n  \"text\": {{text}},\n  \"to\": {{to}},\n  \"to_no_plus\": {{to_no_plus}},\n  \"from\": {{from}},\n  \"from_no_plus\": {{from_no_plus}},\n  \"channel\": {{channel}},\n  \"quick_replies\": {{quick_replies}}\n}\n```\n\nEsses campos significam:\n\n| Campo               | Descrição                                                                                                                     |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| ID                  | identificador único da mensagem ou interação                                                                                  |\n| text                | conteúdo da mensagem que está sendo enviada ao serviço externo                                                                |\n| to / to_no_plus     | identificador do destinatário, podendo incluir (to) ou não (to_no_plus) o sinal +. O formato depende do tipo de URN escolhido |\n| from / from_no_plus | identificador do remetente, no mesmo padrão de to                                                                             |\n| quick_replies       | estrutura de botões rápidos caso o canal suporte respostas pré-definidas                                                      |\n\n## Cabeçalho de autorização (authorization)\n\nAlguns serviços externos exigem um token ou chave para autenticação. Se este for o caso, utilize o campo **Valor de Autorização do Cabeçalho** para informar o valor do token. Esse valor será enviado no cabeçalho HTTP com a chave Authorization em todas as requisições originadas do canal.\n\nPor exemplo, se seu serviço exigir um token Bearer 12345, preencha o campo com o valor `Bearer 12345`. A plataforma adicionará automaticamente o cabeçalho:\n\n```\nAuthorization: Bearer 12345\n```\n\nDeixe este campo em branco caso o serviço externo não exija autenticação via cabeçalho.\n\n## Urls de envio e métodos HTTP\n\nA forma de construção da requisição varia de acordo com o método HTTP selecionado:\n\n### Get (somente enviar URL)\n\nSe o método escolhido for **GET**, somente o campo **Enviar URL** estará disponível.\n\nVocê deve preencher esse campo com a URL do seu serviço (endpoint), incluindo os parâmetros desejados em formato de query string. Os valores entre \\{\\{...\\}\\} serão substituídos dinamicamente pela plataforma.\n\n**Por exemplo**, para enviar as variáveis from, text, to e quick_replies via GET, a URL pode ser:\n\n```\nhttps://send.weni.ai/api/v2?from={{from}}&text={{text}}&to={{to}}{{quick_replies}}\n```\n\nNa chamada acima, a plataforma realizará um GET para a URL informada sempre que houver uma mensagem de saída, substituindo as variáveis pelos valores reais. Não existe corpo de solicitação no método GET e, portanto, o Content-Type é ignorado.\n\n### Post ou put (enviar URL + corpo da solicitação)\n\nQuando o método selecionado for **POST** ou **PUT**, além do campo **Enviar URL** surge o campo **Corpo da solicitação**.\n\nNesses métodos o envio das variáveis ocorre no corpo da requisição, respeitando o Content-Type selecionado. O **Content-Type** deve sempre corresponder ao formato utilizado no corpo:\n\n- **application/x-www-form-urlencoded** – o corpo deverá conter pares chave=valor separados por &.\n- **application/json** – o corpo deverá ser um objeto JSON válido.\n- **text/xml; charset=utf-8** – o corpo deverá estar em formato XML.\n\nPara um serviço que aceita JSON, a configuração pode ser:\n\n- Method: HTTP POST\n- Content-type: JSON – application/json\n- Enviar URL: https://send.weni.ai/api/v2\n- Corpo da solicitação:\n\n```json\n{\n  \"id\": {{id}},\n  \"text\": {{text}},\n  \"to\": {{to}},\n  \"to_no_plus\": {{to_no_plus}},\n  \"from\": {{from}},\n  \"from_no_plus\": {{from_no_plus}},\n  \"channel\": {{channel}},\n  \"quick_replies\": {{quick_replies}}\n}\n```\n\nCom essa configuração a plataforma fará um POST para https://send.weni.ai/api/v2 enviando o JSON acima.\n\nSe você optar por application/x-www-form-urlencoded, o corpo poderá ser:\n\n```\nid={{id}}&text={{text}}&to={{to}}&to_no_plus={{to_no_plus}}&from={{from}}&from_no_plus={{from_no_plus}}&channel={{channel}}&quick_replies={{quick_replies}}\n```\n\n## Checagem de resposta (mt)\n\nO campo **Checagem de resposta** (por vezes exibido como **MT** ou _match text_) permite definir uma string ou expressão que será procurada na resposta do serviço externo para determinar se a requisição foi bem-sucedida.\n\nPor exemplo, se o serviço externo retorna `{\"status\":\"OK\"}` ao receber uma mensagem com sucesso, você pode preencher o campo com OK. Assim, a plataforma considerará a requisição bem-sucedida quando a resposta conter esse texto.\n\nCaso o campo seja deixado em branco, a plataforma validará o sucesso apenas pelo status HTTP 200.\n\n## Urls de retorno (callbacks) da plataforma\n\nApós configurar o canal externo, a plataforma gera um conjunto de URLs que devem ser utilizadas pelo seu serviço para garantir o ciclo completo de mensagens. Essas URLs estão disponíveis na seção **External API Configuration** e correspondem a pontos de retorno (callbacks) que o seu serviço deve chamar quando determinados eventos ocorrerem.\n\nAs principais URLs são:\n\n### Enviar URL (send)\n\nA URL utilizada para enviar mensagens **será exatamente aquela definida por você no campo Enviar URL** na etapa 9. Ou seja, quando a plataforma precisar encaminhar uma mensagem de saída ao canal externo, ela executará um GET/POST/PUT para a URL que você configurou, incluindo os parâmetros e/ou o corpo definidos.\n\nPor exemplo, se na etapa 9 você configurou a URL https://send.weni.ai/api/v2 com o método POST e escolheu o formato JSON, a chamada de envio terá a seguinte estrutura:\n\n```\nPOST https://send.weni.ai/api/v2\n{\n  \"id\": \"1241244\",\n  \"text\": \"Love is patient. Love is kind.\",\n  \"to\": \"+2520788123123\",\n  \"to_no_plus\": \"2520788123123\",\n  \"from\": \"weni\",\n  \"from_no_plus\": \"weni\",\n  \"channel\": \"15292\",\n  \"quick_replies\": [\"One\", \"Two\", \"Three\"]\n}\n```\n\nSe o método configurado for **GET**, a plataforma chamará a URL com os parâmetros na query string conforme exemplificado na seção 9.1.\n\n### URL recebidas (receive)\n\nEsta é a URL que **seu serviço** deve chamar quando receber uma mensagem de um usuário. Sempre que uma nova mensagem chegar ao seu canal externo, envie um POST para esse endpoint com os parâmetros:\n\n- from – URN do usuário (identificador único definido por você)\n- text – conteúdo da mensagem enviada pelo usuário\n- date (opcional) – data e hora em formato ISO-8601 (AAAA-MM-DDThh:mm:ssZ) indicando quando a mensagem foi recebida\n\nPor exemplo:\n\n```\nPOST https://flows.weni.ai/c/ex/<ID>/receive\nfrom=%2B2520788123123&text=Love+is+patient.+Love+is+kind.&date=2012-04-23T18:25:43.511Z\n```\n\nAo receber esta requisição, a plataforma processará a mensagem e enviará uma resposta através da URL configurada anteriormente, fechando o ciclo.\n\n### URL enviadas (sent) – opcional\n\nSeu serviço pode notificar a plataforma sempre que uma mensagem for **enviada** com sucesso para o usuário. Para isso, faça um POST para essa URL, passando o identificador da mensagem no body:\n\n```\nPOST https://flows.weni.ai/c/ex/<ID>/sent?id=1234\n```\n\n### URL entregues (delivered) – opcional\n\nCaso deseje informar à plataforma que uma mensagem foi **entregue** ao destinatário final, faça um POST para essa URL com o parâmetro id igual ao identificador da mensagem:\n\n```\nPOST https://flows.weni.ai/c/ex/<ID>/delivered?id=234\n```\n\n### URL de desativação / parada do contato (stopped)\n\nSe o seu canal fornecer uma maneira de os usuários optarem por **parar de receber mensagens**, você deve notificar a plataforma. Quando um usuário se descadastrar, seu serviço deve enviar um POST para essa URL com o parâmetro from contendo o URN do usuário que pediu a desativação:\n\n```\nPOST https://flows.weni.ai/c/ex/<ID>/stopped?from=%2B2520788123123\n```\n\nEsta notificação é opcional, mas recomenda-se enviá-la para que o usuário seja marcado como opt-out e não receba novas mensagens.\n\n---\n\nEm caso de dúvida, procure o suporte técnico ou consulte a documentação oficial do serviço que está integrando."}