Vinculação de Conta

A Vinculação de Conta é separada dos outros recursos de webView disponíveis na plataforma do Messenger. Ela pode ser iniciada somente por meio de botões Entrar, não por meio do menu persistente do bot, de botões de URL, de um fluxo do webView já aberto nem da plugin de bate-papo.

Agora, os desenvolvedores que usam esses recursos podem obter, com segurança, o número de identificação do usuário por meio da função getContext() nas extensões do Messenger. Os bots podem usar isso para vincular a conta do usuário ou personalizar a experiência.

No momento, a Vinculação de Contas é compatível somente com o app do Messenger para iOS e Android.

Quando um usuário iniciar uma conversa com sua empresa, será conveniente identificá-lo como um cliente que já tem conta na sua empresa. Para auxiliar nisso, criamos um protocolo seguro para vincular e desvincular a identidade do usuário do Messenger com a identidade de usuário da sua empresa.

A Vinculação de Conta permite que você convide usuários para fazer login com seu fluxo de autenticação e receba um ID no escopo da página (PSID) do Messenger na conclusão. Assim, você poderá oferecer uma experiência mais segura, personalizada e relevante aos usuários.

Conteúdo

Processo de vinculação
Retorno de chamada
Evento de webhook
Ponto de extremidade de desvinculação de conta
Boas práticas

Processo de vinculação

O fluxo de Vinculação de Conta segue algumas etapas simples.

Registre uma URL de retorno de chamada usando o botão Entrar.
A plataforma do Messenger invoca a URL registrada quando um usuário inicia esse fluxo. Os parâmetros redirect_uri e account_linking_token são anexados ao retorno de chamada registrado.
Depois de concluir a vinculação, redirecione os usuários ao local fornecido por redirect_uri e anexe um parâmetro authorization_code (definido por você) para confirmar a vinculação.
Opcionalmente, recupere o ID do usuário no escopo da página (PSID) usando o ponto de extremidade de vinculação de conta. Esta etapa deve ser seguida somente em casos especiais, quando o PSID é necessário para o processo de vinculação.

A desvinculação de conta pode ser iniciada destas formas:

Pelo usuário, ao tocar no botão Sair enviado pelo desenvolvedor
Pela empresa, por meio do ponto de extremidade de desvinculação de conta

Retorno de chamada

A URL de Vinculação de Conta é invocada pela plataforma do Messenger quando um usuário aciona a vinculação de conta. Os parâmetros redirect_uri e account_linking_token são anexados ao retorno de chamada da URL.

<yourAccountLinkingUrl>
  ?account_linking_token=ACCOUNT_LINKING_TOKEN
  &redirect_uri=CALLBACK_URL

Se a vinculação for bem-sucedida, conclua o fluxo ao redirecionar o navegador à URL definida no parâmetro redirect_uri e anexar um parâmetro authorization_code definido por você. Talvez a URL já contenha parâmetros. Por isso, você deve anexar o código de autorização corretamente:

<redirect_uri>
  &authorization_code=AUTHORIZATION_CODE

Se a vinculação de conta tiver falhado, redirecione o navegador ao redirect_uri passado para você como um parâmetro, mas não anexe o parâmetro authorization_code.

Parâmetros

Nome do parâmetro	Descrição
`redirect_uri`	URI de redirecionamento que será adicionada pelo Messenger. Você precisa redirecionar o navegador para esse local no fim do fluxo de autenticação. Ele poderá conter parâmetros codificados da URL.
`account_linking_token`	Token de curta duração passado pelo Messenger, que você precisa passar de volta como parte do esquema de redirecionamento. Esse token é válido por apenas cinco minutos, sendo criptografado e exclusivo para cada usuário. Para buscar o PSID correspondente, faça uma chamada ao ponto de extremidade de recuperação do PSID com esse token.
`authorization_code`	Código fornecido por você para confirmar a vinculação. A plataforma do Messenger passará esse código de volta com o PSID do usuário como o evento de webhook de Vinculação de Conta. Se esse parâmetro não for passado, o processo de vinculação será cancelado.

Evento de webhook

Se o fluxo de vinculação for bem-sucedido, um evento de Vinculação de Conta será disparado para passar o ID do usuário no escopo da página (PSID).

É preciso registrar o evento de retorno de chamada de vinculação de conta. Não reconhecer esse evento de webhook fará com que o processo de vinculação seja cancelado.

Ponto de extremidade de recuperação de PSID

Em certos casos, será preciso recuperar o ID do usuário no escopo da página (PSID) durante o fluxo de vinculação. Para ajudar nessa situação, disponibilizamos um ponto de extremidade de recuperação de PSID, que permite buscar o PSID do usuário mediante um account_linking_token válido e não expirado.

Solicitação

curl -X GET "https://graph.facebook.com/v2.6/me?access_token=PAGE_ACCESS_TOKEN \
      &fields=recipient \
      &account_linking_token=ACCOUNT_LINKING_TOKEN"

Resposta

{
  "id": "PAGE_ID",
  "recipient": "PSID"
}

Ponto de extremidade de desvinculação de conta

Em certos casos, será preciso desvincular o ID do usuário no escopo da página (PSID) do back-end de forma programática. Para ajudar nessa situação, disponibilizamos um ponto de extremidade de desvinculação de PSID, que permite desvincular a conta do usuário mediante um PSID válido.

Solicitação

curl -X POST -H "Content-Type: application/json" -d '{
   "psid":"PSID"
}' "https://graph.facebook.com/v2.6/me/unlink_accounts?access_token=PAGE_ACCESS_TOKEN"

Resposta

{
  "result": "unlink account success"
}

Boas práticas

Use a Vinculação de Conta quando tiver um sistema de conta de usuário que se estende além do Messenger.

Permita que as pessoas criem uma conta no Messenger que ficará disponível em outros locais.

Solicite o login quando o contexto exigir (ou seja, quando o usuário do bot vir a vantagem disso).

Pense em como o bot deve se comportar se um usuário recusar o login.

Forneça uma confirmação clara e uma mensagem de boas-vindas amigável após o login.

Não use a Vinculação de Conta se as pessoas forem interagir com você somente no Messenger. É possível armazenar informações de conta por meio do ID da conversa.

Não solicite a Vinculação de Conta imediatamente, se possível. Primeiro, deixe que as pessoas conheçam seu bot.

Fluxo de design recomendado

Solicite o login com uma mensagem que inclua nosso botão Vinculação de Conta.
Mostre sua página de login (incluindo a opção Criar conta) no webView de Vinculação de Conta. Verifique se a aparência e o funcionamento estão adequados para telas de dispositivos móveis.
Depois do login, mostre uma mensagem de confirmação no webView. Os usuários precisarão ignorar a mensagem por conta própria.
Depois disso, exiba uma mensagem de agradecimento e/ou as próximas etapas na conversa, incluindo a opção Sair.