Exemplo de experiência do serviço da API do Messenger para Instagram – Original Coast Clothing

A OC (Original Coast Clothing) é uma marca de roupas fictícia criada para apresentar os principais recursos da Plataforma do Instagram por meio de uma ótima experiência do cliente. Usando essa demonstração como inspiração, qualquer pessoa pode criar uma experiência agradável do serviço da API do Messenger para Instagram com recursos de automação e suporte ao cliente em tempo real. Oferecemos o código aberto para o app e um guia de implementação da experiência no seu ambiente local ou servidor remoto. Além disso, apresentamos um exemplo de experiência no Messenger. Faça o teste agora mesmo. Basta enviar uma mensagem para @originalcoastclothing ou comentar em uma publicação.

Recursos da plataforma

Esta experiência usa os recursos da plataforma a seguir. Se você decidir implantar a experiência na sua Página, o código usará todos eles:

• Mensagens

  • Prévias de textos, imagens e links
  • Modelos genéricos
• Webhooks
• Respostas rápidas
• Perfis de usuário
• Respostas privadas
• Quebra-gelos

Implantação da experiência no Instagram

Quando chegar ao fim deste guia, você terá um app completo do Instagram rodando no servidor e respondendo a mensagens da sua conta.

O código que possibilita criar essa experiência é aberto. Qualquer pessoa pode começar a desenvolver de maneira descomplicada uma ótima experiência de troca de mensagens para uma empresa.

O código é liberado sob a Licença BSD, que permite o uso gratuito para atender às suas necessidades. O código fica hospedado no GitHub para referência futura.

Requisitos para implantar um app do Instagram

• Uma conta profissional do Instagram (uma conta de criador de conteúdo ou empresarial).
• Uma Página do Facebook conectada a essa conta do Instagram. Verifique se a sua Página do Facebook representa a sua identidade profissional quando você se conecta com os usuários. Para criar uma Página, acesse https://www.facebook.com/pages/create. Também é possível configurar uma Página de teste para começar.
• Uma conta de desenvolvedor que possa executar tarefas na sua Página. Com essa conta, é possível criar novos apps, que são o principal elemento de qualquer integração do Facebook. Para se inscrever como desenvolvedor, acesse o site do Facebook for Developers e clique no botão "Primeiros passos".
• Um app do Facebook com as configurações básicas definidas. Para criar um app, acesse https://developers.facebook.com/ e clique em Adicionar novo app.

Etapas de configuração

O objetivo desta seção é reunir todos os tokens de acesso e IDs necessários para que o app do Instagram envie e receba mensagens com sucesso. Antes de começar, verifique se você seguiu todos os requisitos listados acima. Neste momento, você tem uma Página, um app do Facebook registrado e uma conta profissional do Instagram.

Se você acabou de criar um novo app do Facebook, é provável que ele esteja no modo de desenvolvimento. Nesse modo, um app só pode enviar mensagens a pessoas que estão conectadas a ele (administradores, desenvolvedores e testadores). Você pode continuar usando o guia nesse modo. Porém, quando estiver pronto para se tornar público, o app precisará passar pelo processo de análise para obter a permissão instagram_manage_messages. Para saber mais, consulte Análise do aplicativo.

1. Siga a documentação de Introdução para configurar a integração do Instagram.
2. Adicione algumas contas de teste do Instagram que serão usadas para testar a experiência.

Nesse momento, você tem o seguinte:

• ID do app
• Chave secreta do app
• Identificação da Página
• Token de acesso à Página
• Conta do Instagram conectada à Página
• Contas do Instagram registradas como contas de teste

Instalação

Você precisará do seguinte:

• Node 10.x ou posterior
• Um servidor para o seu código. As opções incluem:

  • Serviço de tunelamento local, como ngrok
  • Serviço de servidor remoto, como Heroku ou Glitch
  • Seu próprio servidor da web

Como implantar com um clique usando o Heroku ou o Glitch

A experiência pode ser implantada automaticamente no Heroku ou no Glitch usando os botões abaixo. Você precisará inserir as variáveis de ambiente necessárias para concluir a configuração.

Como implantar localmente usando o ngrok

Um serviço de tunelamento expõe o seu servidor da web local a uma URL externa que pode ser acessada por webhooks do Facebook. Existem vários serviços desse tipo. Neste exemplo, usaremos o ngrok.

1. Clone o repositório

Clone o repositório para a sua máquina local:

git clone https://github.com/fbsamples/original-coast-clothing-ig.git
cd original-coast-clothing-ig

2. Instale o serviço de tunelamento

Caso ainda não tenha feito isso, instale o ngrok via download ou linha de comando:

$ npm install -g ngrok

No diretório desse repositório, solicite um túnel para o servidor local com a sua porta de preferência.

$ ngrok http 3000

A tela mostra o status do ngrok:

Session Status                online
Account                       Redacted (Plan:iuluufkccebegkhifrlgfhudrtbthgln Free)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://1c3b838deacb.ngrok.io -> http://localhost:3000
Forwarding                    https://1c3b838deacb.ngrok.io -> http://localhost:3000

Observe a URL https do servidor externo que é encaminhado para a sua máquina local. No exemplo acima, ela é https://1c3b838deacb.ngrok.io.

3. Instale as dependências

Também no diretório do repositório, abra uma nova aba de terminal.

$ npm install

Se preferir, use o Yarn:

$ yarn install

4. Configure o arquivo .env

Copie o arquivo .sample.env para .env.

$ cp .sample.env .env

Edite o arquivo .env para adicionar todos os valores do app e da página.

5. Execute o app localmente

$ node app.js

Agora, você pode acessar a página-padrão do aplicativo no navegador em http://localhost:3000.

Confirme que você também pode acessar o aplicativo na URL externa da etapa 2.

Como implantar usando o Heroku

1. Clone o repositório

Clone o repositório para a sua máquina local:

git clone https://github.com/fbsamples/original-coast-clothing-ig.git
cd original-coast-clothing-ig

2. Instale a CLI do Heroku

Se o diretório ainda não for um repositório do git, crie um:

$ git init
Initialized empty Git repository in .git/
$ git add .
$ git commit -m "My first commit"     

3. Instale a CLI do Heroku

Se ainda não tiver instalado, baixe e instale a CLI do Heroku.

4. Crie um app a partir da CLI

$ heroku apps:create

Creating app... done, ⬢ mystic-wind-83
Created http://mystic-wind-83.herokuapp.com/ | git@heroku.com:mystic-wind-83.git

Observe o nome dado ao seu app. Neste exemplo, foi mystic-wind-83.

5. Defina as variáveis de ambiente

No Painel de Aplicativos do Heroku, localize o app e defina as variáveis de configuração seguindo os comentários exibidos no arquivo .sample.env.

Como alternativa, é possível definir variáveis env a partir da linha de comando, desta forma:

$ heroku config:set PAGE_ID=XXXX

6. Implante o código

$ git push heroku master

7. Visualize a saída do registro

$ heroku logs --tail

Conecte o webhook

Agora que o servidor está em execução, o ponto de extremidade do webhook está no caminho /webhook. No exemplo acima, no Heroku, isso seria http://mystic-wind-83.herokuapp.com/webhook.

Configure o webhook seguindo o [guia Webhooks para a plataforma do Messenger](https://developers.facebook.com/docs/messenger-platform/webhooks).

Após a validação da assinatura do webhook, assine os seguintes eventos:

• comments
• messages
• messaging_postbacks

Teste os webhooks clicando nos botões "Testar" ao lado dos eventos assinados. Os eventos de teste devem aparecer na saída do registro do servidor.

Como testar a configuração do app

Conectado na conta com a função de "testador do Instagram", envie uma mensagem para a conta do Instagram conectada à sua Página ou comente em uma publicação.

Se a configuração do app estiver concluída, você verá uma resposta à sua mensagem no Instagram! Pronto!

Solução de problemas

O app só responde para mim, mas não para outras pessoas.

É provável que o app do Facebook esteja no modo de desenvolvimento. Adicione um usuário como testador do app. Se o usuário aceitar, o app poderá enviar mensagens a ele. Quando estiver pronto, você poderá solicitar a permissão instagram_manage_messages para responder a qualquer pessoa.

Outros problemas

Este guia está errado? Preencha um formulário para relatar o problema.