Este guia lhe ensinará sobre nossas ferramentas de API e o que você pode fazer com blocos dinâmicos e solicitações externas. O ideal é que, depois de lê-lo, você tenha um novo nível de compreensão dessas ferramentas e consiga resolver quaisquer problemas que possa encontrar.
Também é importante entender que as DevTools não são semelhantes a outros instrumentos na Manychat. Enquanto gatilhos e o construtor de fluxos foram criados por nós, as DevTools são semelhantes aos instrumentos de API usados em toda a Internet.
Para usá-las, você precisa entender os conceitos básicos de programação, conexão cliente-servidor, uso de API e estrutura de solicitação de API. Abordaremos tudo isso abaixo.
Para solucioná-los, você precisa entender as mesmas coisas e lembrar que problemas com elas não estão relacionados aos sistemas Manychat por si só — você encontraria esses problemas em qualquer instrumento semelhante em qualquer outro serviço.
Este artigo abordará as seguintes questões:
- O que é uma API?
- O que são nós?
- O que é um nó dinâmico?
- Estrutura de solicitações
- O que é um caminho JSON?
- Como nossa API pública é usada?
- O que são os métodos POST e GET?
- O que um bloco dinâmico faz?
- O que uma solicitação externa faz?
- O que é uma chave de API?
- Solução de problemas
- Dicas e limites
- Informações que você deve saber
O que é uma API?
API é a sigla para Application Programming Interface, um método de interação entre diferentes aplicativos ou dentro de um único aplicativo. APIs são a base da nossa interação (Manychat) com a Meta. Há uma ótima documentação sobre APIs da Meta, que você pode consultar para obter mais informações.
APIs são usadas para se conectar com um aplicativo externo e alterar/modificar/enviar algo de dentro dele. A base de uma API é um conjunto de métodos, e a interface é caracterizada por métodos.
O que são nós?
Automações consistem em nós. Há um nó de conteúdo (nó "Enviar mensagem"), que consiste em blocos. Usamos esse nó para enviar mensagens para contatos da Manychat. Desmembramos os nós, os alteramos para um formato compreensível para a Meta e os enviamos para a Meta por meio de API.
O que é um nó dinâmico?
É um processo em que a Manychat interrompe o processamento da automação, vai para outras ações (como uma solicitação de servidor externo, alguma ação etc.) e então retorna para a automação.
Estrutura de solicitações
Uma solicitação consiste em:
- Método ou tipo de solicitação (GET/POST/etc)
- Link
- Opcionalmente – Cabeçalhos (incluindo autorização e chaves de API)
- Opcionalmente – Corpo (com o conteúdo dentro) se for o tipo de solicitação POST
Duas coisas completam o formato de dados na solicitação:
- A versão do protocolo que usamos (no momento, v2)
- Conteúdo: mensagens, ações, respostas rápidas, etc. É exatamente assim que os nós de conteúdo da Manychat se parecem. A Manychat oferece suporte apenas a ações disponíveis na Manychat. Aqui estão alguns exemplos.
A opção de fallback é ativada quando há uma resposta errada do servidor em um bloco dinâmico – geralmente quando o servidor retorna um erro. Se um membro da equipe especificar algum conteúdo no fallback, esse conteúdo será entregue aos contatos para os quais a solicitação falhou.
Se não houver fallback e a solicitação falhar, o restante da automação não será processado e tudo será interrompido. Recomendamos usar fallback para notificar os usuários de que algo deu errado no servidor, mas não para criar a lógica de automação nele. Fallback é usado em situações excepcionais.
O que é um caminho JSON?
Caminho JSON é um protocolo cujo formato é usado para extrair uma resposta de um sistema externo e salvá-la em um campo de usuário personalizado: o servidor retorna uma resposta que consiste em propriedades e seus valores.
O mapeamento de resposta permite que você salve alguns dos valores em campos de usuário personalizados inserindo o caminho JSON para esses valores.
Nossas integrações (Hubspot, ConvertKit, etc.) e Meta o utilizam.
Como nossa API pública é usada?
Nossa API pública pode ser usada para alterar o estado de contatos a qualquer momento, além de enviar mensagens para eles – basicamente, ela permite que você execute certas ações de fora da Manychat. Ela serve para eventos externos que a Manychat não conhece e sobre os quais precisa notificar os contatos.
Por exemplo, você tem um serviço de entrega. As informações de rastreamento do produto foram atualizadas e você sabe de quem é o pedido. Você chama um método para notificar esse contato específico, e ele receberá uma mensagem.
O que são os métodos POST e GET?
O método POST altera os dados da conta ou do contato, por exemplo, com Definir campo personalizado, Enviar conteúdo ou Definir campo de bot. Ele também é usado para passar parâmetros ao servidor para execução de determinadas ações.
Vamos usar a API setCustomField como exemplo. Se você quiser definir um campo de usuário personalizado com um determinado valor para um contato específico, será necessário informar ao servidor o ID do contato, o nome do campo e o valor que você deseja definir.
O método GET obtém informações de conta ou contato por meio de Obter informações, Obter campos de bot etc. Em solicitações como essa, esperamos uma solicitação do servidor externo imediatamente. Uma solicitação GET não tem um corpo.
Um exemplo mais simples: GET encontrará e retornará o valor de um campo de usuário personalizado, e POST alterará ou enviará o valor do campo de usuário personalizado para algum lugar.
A solicitação do método SendContent aceita mensagens no mesmo formato JSON usado para Dynamic Block.
Os métodos POST e GET podem ser usados para ações e solicitações semelhantes, mas normalmente GET obtém dados de algum lugar, e POST modifica/envia dados.
O que um bloco dinâmico faz?
O objetivo mais básico do bloco dinâmico é ir até o servidor externo, obter o código JSON de lá, transformá-lo em uma mensagem e enviá-la a um contato.
O bloco dinâmico pode ser usado para acionar nossa API, mas esse não é seu propósito principal. Não garantimos que ele funcionará corretamente e nossa API poderá não retornar nada para o bloco dinâmico. Quase todas as solicitações definidas dessa maneira podem ser criadas na interface interna nativa.
Uma observação importante sobre o uso de botões de nó: se um bloco dinâmico tentar acessar nossa API pública com código que inclua um botão/uma resposta rápida Ir para nó, isso não funcionará. O bloco dinâmico funciona dentro do contexto de automação, mas quando aciona a API pública, ele sai desse contexto e a automação não é encontrada.
💡 Você pode verificar os logs de erro e aviso relacionados às solicitações de bloco dinâmico em Configurações → Logs.
O que uma solicitação externa faz?
O objetivo mais básico de uma solicitação externa é ir ao servidor externo e:
- Salvar alguns dados lá
- Alterar dados lá
- Obter alguns dados lá e retorná-los à Manychat com o mapeamento de solicitação
- Alguns ou todos os itens acima
Solicitações externas também podem ser usadas para acionar nossa API pública com alguns valores predefinidos internamente. Por exemplo, para enviar o valor de um campo de usuário personalizado de um contato para outro dentro de um bot.
O que é uma chave de API?
Chave de API é um código usado para identificar o usuário, desenvolvedor ou programa de chamada de um site. A Manychat fornece chave de API (recurso PRO) para uso com a API pública da conta. A chave de API pública está disponível em Configurações → API.
Há também uma API pública de perfil usada para conexão com o que não é específico a bots, como modelos. Isso requer uma chave diferente que pode ser encontrada aqui.
Solução de problemas
Erros específicos e conselhos sobre configuração serão abordados abaixo. Aqui, elaboraremos sobre a introdução e nos aprofundaremos em solução de problemas.
Se você não sabe o que está acontecendo, procure o erro online. Muitas vezes você encontrará a solução em fóruns do Stack Overflow ou qualquer site de programação, incluindo fóruns de suporte da Meta. Lembre-se de que erros das DevTools não são exclusivos da Manychat: eles são comuns em todas as ferramentas como essa. Aqui está a lista de códigos de status de erro comuns do protocolo HTTP.
É altamente recomendável que você se familiarize com nossas solicitações de API disponíveis e exemplos de código JSON.
Esses dois links respondem a todas as perguntas sobre as possibilidades da nossa API pública. Se você não conseguir ver o método que está procurando, então não existirá um método como esse. No entanto, você pode postar uma solicitação de recurso aqui.
Você precisa usar o JSON Lint ou uma ferramenta semelhante para verificar se o código JSON está correto, o que nosso verificador pode ter deixado passar, mas isso raramente acontece. Lembre-se de que talvez seja necessário desmarcar a caixa de seleção Codificar para JSON, e não há necessidade de colocar campos de usuário personalizados inseridos entre "".
O que é a caixa de seleção Codificar para JSON?
Todos os sites têm um certo protocolo para aceitar solicitações. A maioria deles tem vários sinalizadores, filtros e decodificadores que transferirão o código JSON enviado de nossa parte para algo que o site possa entender. Alguns deles aceitam apenas códigos JSON estritos. Codificar para JSON permite que você transforme o valor dos campos em JSON – isso também é necessário quando você tem apenas variáveis no corpo da solicitação, como com {{Full Contact Data}}.
Postman permitirá que você verifique e teste rapidamente qualquer solicitação de API.
Links que ajudarão você a resolver qualquer dúvida sobre caminho JSON (mapeamento de solicitações):
- O JSON Formatter ajudará você a formatar a string JSON em um código que seja fácil de ler e entender
- Essa documentação de caminho JSON explicará os comandos de caminho JSON e sua formatação correta, além de fornecer alguns exemplos
- O JSONPath Expression Tester ajudará você a testar rapidamente um caminho JSON específico com um código JSON
Dicas e limites
Se você quiser ver como um bloco dinâmico funciona com uma mensagem de um servidor externo, crie o seu próprio em questão de minutos – siga as etapas neste artigo.
Se um servidor que você estiver chamando não exigir autorização e você desejar ver qual resposta ele retornará em uma nova guia, instale uma extensão do Google Chrome como JSON Formatter para vê-la estruturada em linhas:
Você também pode copiar a resposta da guia ou da DevTool após testar a solicitação e usar um formatador JSON online como este para estruturá-la em linhas:
Isso também permitirá que você veja a que certos colchetes pertencem no código.
Informações que você deve saber
- O comprimento do URL de solicitação é limitado a 2.000 símbolos.
- Se você preencher um campo de usuário personalizado dentro do cartão do contato, o limite será 4.000 caracteres. Mas se você salvar o valor da mensagem de um contato no Messenger com um bloco de Coleta de Dados, o limite será cerca de 20.000 – limite de caracteres para uma mensagem no Messenger. Não há limite real para campos de API e bot.
- O tempo limite é restrito a 10 segundos. Ele não pode ser alterado.
- "https://" será necessário na caixa de URL da solicitação, mesmo que um campo já contenha isso.
- O URL de solicitação aceita apenas links https.
- Não será possível mapear uma mensagem de erro se o código retornado não for 200 OK e de alguma forma reagir a cada erro específico.
- Não é possível mapear os valores de resposta ao testar a solicitação. Isso só funciona quando você aciona a DevTool como um contato ou visualiza a automação.
- Só é possível mapear um código JSON. Outros formatos não são aceitos.