Este guia tem como objetivo ensinar sobre nossas ferramentas de API e o que você pode fazer com o Bloco Dinâmico e a Solicitação Externa. Idealmente, após este guia, você terá um novo nível de compreensão para essas ferramentas e será capaz de resolver qualquer problema que possa encontrar.
Também é importante entender que as Ferramentas de Desenvolvimento não são semelhantes a outros instrumentos no ManyChat. Enquanto as Ferramentas de Crescimento e o Construtor de Fluxos foram criados por nós, as Ferramentas de Desenvolvimento são semelhantes aos instrumentos de API que são 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 requisições de API. Vamos cobrir todos esses pontos abaixo.
Para solucioná-los, você precisa entender as mesmas coisas e lembrar que os problemas com eles não estão diretamente relacionados aos sistemas do ManyChat por si só - são problemas que você encontraria em qualquer outro instrumento similar em qualquer outro serviço.
1. O que é API (Interface de Programação de Aplicativos)?
API é um método de interação entre diferentes aplicativos ou dentro de um único aplicativo. A API é a base de nossa (ManyChat) interação com o Facebook. Há uma ótima documentação sobre API do Facebook que você pode consultar para obter mais informações.
A API é usada para se conectar com o aplicativo de fora e alterar/modificar/enviar algo dentro dele. A base da API é um conjunto de métodos. A interface é caracterizada por métodos.
2. O que são nós?
Os fluxos consistem em nós. Há um nó de conteúdo (nó de envio de mensagem). Ele consiste em blocos. Este nó é o que usamos para enviar mensagens para os contatos do ManyChat. Desmontamos os nós em partes, os transformamos no formato compreensível para o Facebook e enviamos para o Facebook por meio da API.
3. O que é um Nó Dinâmico?
É um processo no qual o ManyChat interrompe o processamento do fluxo, vai para outras ações (como uma solicitação de servidor externo, alguma ação, etc.) e depois volta para o fluxo.
4. A solicitação consiste em
1. Método ou tipo de solicitação (GET/POST/etc),
2. link,
3. opcionalmente - cabeçalho (incluindo chaves de API e autorização),
4. opcionalmente - corpo (com o conteúdo dentro) se for do tipo de solicitação POST.
Existem duas coisas que completam o formato dos dados na solicitação:
1. Versão do protocolo que usamos (atualmente é v2).
2. Conteúdo: mensagens, ações, Respostas Rápidas, etc. Isso é exatamente da mesma forma que o nó de conteúdo do MC parece. O MC suporta apenas as ações disponíveis no MC. Aqui estão elas como exemplos.
A opção de fallback é ativada em caso de resposta errada do servidor no Bloco Dinâmico - geralmente quando o servidor retorna um erro. Se um administrador escolher algum conteúdo no Fallback, este conteúdo será entregue a esses contatos para os quais a solicitação falhou.
Se não houver Fallback e a solicitação falhar, então o restante do fluxo não será processado e tudo parará. Recomendamos usar o Fallback para notificar os usuários de que algo deu errado no servidor, mas não para construir a lógica do fluxo sobre ele: Fallback é usado em situações excepcionais.
5. O que é o caminho JSON?
É um protocolo cujo formato é usado para extrair a resposta de um sistema externo e registrá-la em Campo Personalizado: o servidor retorna uma resposta que consiste em propriedades e seus valores.
O mapeamento de resposta permite salvar alguns dos valores nos Campos Personalizados inserindo o Caminho JSON para esses valores.
Todas as nossas integrações (Hubspot, ConvertKit) e o próprio Facebook o usam.
6. Como é usado nosso API público?
Isso ajuda a alterar o estado dos contatos a qualquer momento e enviá-los mensagens - basicamente, permite que você execute certas ações de fora do Manychat. Serve para eventos externos dos quais o Manychat não tem conhecimento e sobre os quais ele 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 o método para este contato específico para notificá-lo, e ele recebe a mensagem.
7. O que são os métodos POST e GET?
O método POST altera os dados do contato, por exemplo, com "Definir Campo Personalizado", "Enviar Mensagem", "Definir Campo do Bot". O método POST também é usado para passar parâmetros para o servidor que são necessários para realizar determinadas ações.
Vamos pegar o API "setCustomField" como exemplo - se você deseja definir um Campo Personalizado para um valor específico para um contato específico, você precisa informar ao servidor o ID do contato, o nome do campo e o valor que deseja definir.
O método GET é usado para obter as informações do contato ou da página por meio de solicitações como "Get user", "Get Bot Field", etc. Em solicitações como essa, esperamos uma resposta do servidor externo imediatamente. A solicitação GET não tem um Corpo.
Um exemplo mais simples: GET encontrará e retornará o valor do Campo Personalizado, POST mudará ou enviará o valor do Campo Personalizado para algum lugar.
O método de solicitação "SendContent" aceita mensagens recebidas no mesmo formato JSON que é usado para o Bloco Dinâmico.
Nota: Os métodos POST e GET podem ser usados para ações e solicitações semelhantes, mas é comumente aceito que o GET obtém os dados de algum lugar e o POST modifica/envia dados.
8. O que o Bloco Dinâmico faz?
O propósito mais básico do Bloco Dinâmico é ir para o servidor externo, obter o código JSON lá, transformá-lo na mensagem e enviar essa mensagem para o usuário.
O Bloco Dinâmico pode ser usado para acionar nosso API, mas não é seu principal propósito, e não garantimos que funcionará corretamente e que nosso API possa não retornar nada para o Bloco Dinâmico. Quase todas as solicitações configuradas dessa maneira podem ser duplicadas por meio da interface interna nativa.
Uma observação importante sobre o uso de Node_Buttons: se o Bloco Dinâmico tentar acessar nosso API público com o código que inclui o botão/Resposta Rápida "Ir para o Nó", não funcionará. O Bloco Dinâmico funciona dentro do contexto do Fluxo, mas quando está acionando o API público, sai desse contexto e o Fluxo não será encontrado.
9. O que a Solicitação Externa faz?
O objetivo mais básico da Solicitação Externa é ir para o servidor externo e
1. Salvar alguns dados lá;
2. Alterar dados lá;
3. Obter alguns dados lá e retorná-los ao Manychat com o Mapeamento de Solicitação.
4. Alguma ou todas as opções acima.
A Solicitação Externa também pode ser usada para acionar nosso API público com alguns valores pré-definidos internamente. Por exemplo, para enviar o valor do Campo Personalizado de um usuário para outro dentro de um único bot.
Exemplo de notificação.
10. O que é a Chave de API?
É um código usado para identificar o usuário, desenvolvedor ou programa chamador de um site. O Manychat fornece Chave de API (recurso PRO) para uso com o API Público da Conta. A Chave Pública do API pode ser encontrada em Configurações ⇒ API.
Há também um API Público de Perfil que é usado para conexão com coisas não específicas do bot como Modelos. Ele requer uma chave diferente que pode ser encontrada aqui.
Solução de problemas
Erros específicos e conselhos de configuração serão abordados abaixo, aqui vamos elaborar a introdução e aprofundar na solução de problemas.
1. Se você não sabe o que está acontecendo, pesquise o erro no Google.
Sem brincadeira: muitas vezes você encontrará a solução nos fóruns do Stack Overflow ou em qualquer site de programação, incluindo os fóruns de suporte do Facebook; Lembre-se de que os erros das Ferramentas de Desenvolvimento não são exclusivos do Manychat: eles são comuns a todas as ferramentas como esta. Aqui está a lista dos códigos de status de erro comuns do protocolo HTTP para orientação.
2. É altamente recomendável que você se familiarize com nossas solicitações de API disponíveis e exemplos de código JSON.
Esses dois links são a resposta para todas as perguntas sobre as possibilidades do nosso API público. Se você não conseguir ver um método que está procurando, então não há um método como este. Mas você pode postar uma solicitação de recurso aqui.
3. Você pode precisar do Jsonlint para verificar se não há nada de errado com o código JSON que nosso verificador pode ter ignorado, mas isso acontece raramente. Lembre-se de que você pode precisar desabilitar a caixa de seleção "Codificar para JSON" e não há necessidade de colocar os Campos Personalizados inseridos entre "".
O que é a caixa de seleção "Codificar para JSON"?
Todos os sites têm um determinado protocolo para aceitar solicitações. A maioria deles tem toneladas de bandeiras, filtros e decodificadores que transferirão o código JSON enviado do nosso lado para algo que o site possa entender. Alguns deles aceitam apenas código JSON estrito. Codificar para JSON permite que você transforme o valor nos campos em JSON - isso também é necessário quando você está tendo apenas variáveis no Corpo da Resposta, como com {{Dados do Assinante Completo}}.
4. Este site permitirá que você verifique e teste rapidamente qualquer solicitação de API.
5. Links que o ajudarão a resolver qualquer pergunta de caminho JSON (Mapeamento de Solicitação):
O formatador JSON ajudará a formatar a string JSON em um código mais fácil de ler e entender.
Este caminho JSON lhe dirá tudo sobre os comandos de caminho JSON, sua formatação correta e fornecerá alguns exemplos.
Este site ajudará você a testar rapidamente um caminho JSON específico em relação ao código JSON fornecido.
Dicas e limites
1. Se você quiser ver como o Bloco Dinâmico funciona com uma mensagem de um servidor externo, você pode criar o seu próprio em questão de minutos - siga as etapas deste artigo.
2. Você também pode testar uma chamada de API (para Manychat ou o serviço do cliente) em sua própria conta do MC.
Se for um método POST, você pode editar o corpo da solicitação em sua conta até encontrar uma solução funcionando.
Se for uma chamada para o API do Manychat, você precisará de seu próprio token de API no cabeçalho, e se for o serviço do cliente que requer autorização, use os mesmos cabeçalhos que o cliente definiu em sua ferramenta de desenvolvimento.
3. Se o servidor do cliente não exigir autorização e você quiser ver qual resposta ele retorna em uma nova guia, você pode instalar uma extensão do Google Chrome como o JSON Formatter para vê-lo estruturado em linhas:
4. Você também pode copiar a resposta da guia ou da ferramenta de desenvolvimento após testar a solicitação e usar um formatador JSON online como este para estruturá-lo em linhas:
Também permitirá que você veja a que certos colchetes pertencem no código.
5. Brinque com nossas ferramentas de desenvolvimento o máximo que puder para entender melhor como elas funcionam - tente criar solicitações que fariam o mesmo na interface do MC, como enviar uma mensagem, definir um campo personalizado, etc.
Coisas que você deve saber:
1. O comprimento dos URLs de solicitação é limitado a 2.000 símbolos.
2. Se você preencher um CUF dentro do cartão de contato, o limite é de 4.000 caracteres. Mas se você salvar o valor da mensagem do contato no Messenger com Entrada de Usuário, o limite é cerca de 20.000 - é o limite de caracteres para uma mensagem no Messenger. Para API e campos de bot, não há limite real.
3. O tempo limite é limitado a 10 segundos. Não pode ser alterado.
4. "https://" no endereço da solicitação é necessário na caixa de URL da solicitação, mesmo que haja um campo que já contenha isso.
5. A URL da solicitação suporta apenas "https".
6. Não é possível mapear a mensagem de erro se o código retornado não for 200 OK e de alguma forma reagir a cada erro específico.
7. Não é possível mapear os valores de resposta ao testar a solicitação - só é bem-sucedido quando você testa a ferramenta de desenvolvimento como um contato ou visualiza o Fluxo.
8. É apenas possível mapear o código JSON, XML ou algo parecido. Outros códigos podem ser enviados como uma string de texto dentro do código JSON no máximo, e é apenas uma má solução alternativa.
9. "\n" permite adicionar quebras de linha à sua mensagem dentro de "conteúdo" > "mensagens".
Exemplos de configuração
1. Este Flow ajudará a demonstrar como você pode enviar uma notificação ao usuário não-administrador do seu bot.
2. Este Flow demonstra como você pode iniciar um gerador de números aleatórios.
3. Você pode obter o status atual do contato usando este método de API. Você precisa do campo status no objeto de dados. O contato ativo tem status = ativo.