Exemplo de experiência do Messenger com a Original Coast Clothing

A Original Coast Clothing (OCC, pelas iniciais em inglês) é uma marca de roupas fictícia criada para apresentar os principais recursos da plataforma do Messenger. Este guia mostra como baixar o código do exemplo de app no seu ambiente local ou no servidor remoto para saber mais sobre os recursos que o Messenger tem a oferecer.

Para mostrar a experiência completa do Messenger com vários pontos de entrada, nossa empresa fictícia tem os seguintes recursos:

Uma experiência automatizada do Messenger para alcances orgânicos
Geração de cadastros no Messenger com acompanhamento habilitado pela API. Insira este anúncio de geração de cadastros para demonstrar isso
Um QR code que aciona um desconto promocional na coleção de verão
Uma Página do Facebook com um anúncio de clique para o Messenger exibido como uma publicação da Página
Uma experiência do Instagram
Um site de comércio eletrônico com um plugin de bate-papo do cliente

Ver a experiência do Messenger com a OCC

Recursos da plataforma

Este exemplo de app usa os seguintes recursos:

Como implantar a experiência no Messenger

Quando chegar ao final deste guia, você terá um app completo do Messenger rodando no servidor e respondendo a mensagens da sua Página de teste.

Antes de começar

Você precisará do seguinte:

Uma identificação da Página do Facebook – Pode ser a identificação da sua Página do Facebook publicada ou de uma Página de teste.
Uma conta de desenvolvedor da Meta
O ID do app da Meta
A chave secreta do app da Meta
Um token de acesso à Página solicitado por uma pessoa que pode executar a tarefa CREATE_CONTENT na Página
As permissões pages_messaging, pages_show_list e pages_manage_metadata

Um código de exemplo localizado no GitHub

Se você tiver ambientes de desenvolvimento, preparação e produção separados, cada um deles precisará ter o próprio app da Meta e a própria Página do Facebook.

Configuração do ambiente local

Para executar o exemplo de app no seu ambiente local, você precisará do NodeJS 10.x ou de uma versão mais recente.

Etapa 1: clone o repositório do exemplo de app

Clone o repositório de original-coast-clothing na sua máquina local.

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

Etapa 2: instale as dependências do código

yarn install

Etapa 3: obtenha um endereço externo

Para receber mensagens, é necessário ter uma forma de receber webhooks dos nossos servidores.

Caso você precise de um endereço externo, use ngrok, que fornece um endereço HTTPS externo com direcionamento ao app no NodeJS.

Instale ngrok

npm install -g ngrok

Solicite um túnel para o servidor local com sua porta de preferência

ngrok http 3000

A tela deve exibir o status de ngrok:

Session Status                online
Account                       Redacted (Plan: 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

Connections                   ttl     opn     rt1     rt5     p50     p90
0       0       0.00    0.00    0.00    0.00

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

Etapa 4: defina Webhooks e o perfil do Messenger

Copie o modelo de amostra de ambiente no seu app

mv .sample.env .env

Adicione os valores do ambiente

Edite o arquivo .env para adicionar os valores do ID do app do Facebook, da identificação da Página do Facebook, do token de acesso à Página e da chave secreta do app. Defina o valor de VERIFY_TOKEN como uma string aleatória. O app usará esse valor para validar as chamadas de API.

Etapa 5: execute o app

node app.js

Agora, você pode acessar o app no navegador em http://localhost:3000.

Etapa 6: configure o app

Execute o comando a seguir para definir as configurações de assinatura de webhooks do app e do perfil do Messenger da Página. Lembre-se de usar o valor de VERIFY_TOKEN adicionado ao arquivo .env.

http://localhost:3000/profile?mode=all&verify_token=<VERIFY_TOKEN>

Etapa 7: testar a configuração do app

Envie uma mensagem à sua Página do Facebook ou no Messenger. Se o webhook receber um evento, o app estará completamente configurado.

Faça uma alteração no código

Vamos editar o arquivo locales/en_US.json substituindo a mensagem em get_started.welcome e alterando de "Oi, {{userFirstName}}! Bem-vindo(a) à Original Coast Clothing..." para algo diferente.

Voltando para o primeiro terminal, sempre que você alterar o código, precisará reiniciar o servidor NodeJS. Interrompa o servidor com o comando Ctrl-C e execute-o novamente para recarregar o código novo.

node app.js

Abra o Messenger e envie uma mensagem à sua Página com a palavra "Oi". Você receberá a nova mensagem.

Configuração do Heroku

A instância do Heroku pode ajudar a hospedar o ambiente de produção ou preparação do site ou do app da sua empresa.

Etapa 1: crie um app do Heroku

git init
heroku apps:create
# Creating app... done, ⬢ YOUR-APP-NAME
# Created http://YOUR-APP-NAME.herokuapp.com/ | git@heroku.com:YOUR-APP-NAME.git

Etapa 2: implante o código no Heroku

heroku git:remote -a YOUR-APP-NAME
git push heroku master

Etapa 3: defina variáveis de ambiente

Encontre as variáveis de configuração do seu app no painel do Heroku, em Configurações. Adicione os valores do ID do app do Facebook, da identificação da Página do Facebook, do token de acesso à Página e da chave secreta do app. Depois, crie um VERIFY_TOKEN.

Etapa 4: defina webhooks e o perfil do Messenger

Agora, você pode acessar o app. Use a opção VERIFY_TOKEN que você criou nas variáveis de configuração e chame o ponto de extremidade /profile.

https://YOUR-APP-NAME.herokuapp.com/profile?mode=all&verify_token=<VERIFY_TOKEN>

Opcional. A URL acima retornará os números de identificação das personas carregadas. Como isso é retido na memória, adicione os IDs retornados como variáveis de configuração para que persistam depois de recarregar.

heroku config:set PERSONA_BILLING=<PERSONA_ID> -a YOUR-APP-NAME
heroku config:set PERSONA_ORDER=<PERSONA_ID> -a YOUR-APP-NAME
heroku config:set PERSONA_SALES=<PERSONA_ID> -a YOUR-APP-NAME

Etapa 5: teste o app

Envie uma mensagem à sua Página do Facebook ou no Messenger. Se o webhook receber um evento, o app estará totalmente configurado.

Solução de problemas

Executar novamente o app no local

Depois de executar o ngrok, um novo endereço externo será fornecido. Atualize o endereço APP_URL no arquivo .env e execute o servidor NodeJS.

node app.js

Atualize o endereço de webhook nas configurações do app do Facebook ao acessar http://localhost:3000/profile?mode=webhook&verify_token=<VERIFY_TOKEN>.

Minha Página só responde para mim, mas não para outras pessoas

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