Protocolo de entrega

O protocolo de entrega da plataforma do Messenger transfere o controle de uma conversa de um app para outro, permitindo a participação de dois ou mais apps. Esse recurso é habilitado automaticamente nos apps inscritos em uma Página do Facebook.

Observação: o encaminhamento de conversas já está disponível e substituirá o protocolo de entrega em breve. Você deve atualizar seu app o quanto antes para usar o novo recurso.

Como funciona

Uma Página do Facebook ou uma conta profissional do Instagram pode usar vários apps de mensagem para se comunicar com clientes ou pessoas que tenham interesse no conteúdo publicado por ela. Por exemplo, no suporte ao cliente, o cliente pode ser encaminhado para uma experiência automatizada. Caso o problema não seja resolvido, ele poderá ser encaminhado a outro app com agentes de suporte ao vivo. Para transferir a conversa e os metadados relacionados entre apps ou entre um app e uma Caixa de Entrada da Página do Facebook ou do Instagram, é preciso que um passe o controle da conversa ao outro. Com o protocolo de entrega, essa transferência é possível.

Por padrão, quando um cliente envia uma mensagem para iniciar uma conversa, a conversa fica ociosa. Os apps receberão uma notificação de Webhooks avisando que uma mensagem foi recebida e está aguardando uma resposta. Para receber essa notificação, o app precisa assinar os Webhooks específicos de entrega.

Qualquer app pode controlar a conversa enquanto ela estiver ociosa. Porém, apenas o app no controle da conversa tem a capacidade exclusiva de responder à mensagem. Somente um app por vez pode ter o controle da conversa. Os outros apps não poderão enviar mensagens até que o controle seja liberado. Depois que o app liberar o controle, a conversa voltará a ficar ociosa, e outro app poderá controlá-la.

O app que controla a conversa receberá notificações dos webhooks de mensagens. Os outros apps receberão notificações de webhooks específicos de entrega.

As conversas retornarão automaticamente ao modo ocioso quando não tiverem atividade em 24 horas. Se necessário, o app controlador poderá estender o controle para além das 24 horas.

Se um app que não controla a conversa tentar enviar uma mensagem a alguém, um erro 400 será retornado com o subcódigo 2018300.

Destinatário principal

Se você quiser que as mensagens recebidas sejam gerenciadas por um app específico, defina-o como o destinatário principal. O destinatário principal recebe todas as mensagens em uma conversa. Além disso, ele poderá transferir o controle para outro app ou para a Caixa de Entrada da Página do Facebook ou do Instagram, bem como assumir o controle de uma conversa de outro app, se necessário. Quando um app que não é o destinatário principal termina uma conversa e libera o controle, a conversa é definida como ociosa.

Se a conversa estiver ociosa e uma pessoa enviar uma nova mensagem à sua Página ou conta, o destinatário principal terá o controle da conversa e receberá a notificação de webhook relacionada.

Observação: a configuração do destinatário principal não é obrigatória.

Caixa de Entrada

A Caixa de Entrada da Página do Facebook ou do Instagram não pode ser atribuída como destinatário principal. No entanto, se você mover a mensagem para a pasta principal ou enviar uma resposta em uma conversa não controlada pela caixa de entrada, ela assumirá o controle da conversa. Se você responder a uma mensagem marcada como Concluída na caixa de entrada, a conversa será controlada pelo último que a controlou, pelo destinatário principal (se definido) ou será liberada como ociosa.

Pontos de entrada da conversa

A conversa pode ser atribuída a um app específico quando o ponto de entrada de clique para o Messenger for usado. A empresa pode usar o clique para o Messenger caso queira iniciar conversas com clientes para gerar cadastros, aumentar o reconhecimento da marca e muito mais.

Menu persistente

Qualquer app pode definir o menu no nível da Página, a menos que um destinatário principal tenha sido definido. Nesse caso, somente ele poderá definir ou excluir um menu no nível da Página.

O app que controla a conversa pode definir ou excluir menus no nível do usuário, mesmo que o app não seja o destinatário principal. Além disso, qualquer app pode definir o menu no nível do usuário quando a conversa estiver ociosa.

Quando a pessoa selecionar um item do menu, o app que o criou terá o controle da conversa. Isso porque o app que criou o menu está configurado para administrar esses dados.

Chamada de ação de postback

Quando o cliente clica em uma chamada para ação de postback, o app que a criou assumirá o controle da conversa, mesmo que haja um app controlador. Isso porque o app que criou a chamada para ação de postback está configurado para administrar esses dados.

Pesquisas com clientes

Se uma pesquisa for enviada enquanto outro app controla a conversa, ela não será entregue até que o controle seja liberado e a conversa fique ociosa.

Componentes

Os componentes a seguir são necessários para implementar o protocolo de entrega para apps de mensagens inscritos na sua Página do Facebook.

Tokens de acesso

Nas chamadas para os pontos de extremidade do protocolo de entrega, é necessário um token de acesso à Página solicitado por uma pessoa que pode executar a tarefa MODERATE na Página.

Análise do app

O processo de análise é obrigatório para apps que:

serão usados por pessoas que não têm uma função no app;
permitirão que um agente humano responda aos clientes.

Recurso Human Agent

Um app poderá enviar uma mensagem a uma pessoa mesmo que não esteja no controle da conversa se tiver sido aprovado por meio do processo de análise para usar o recurso Human Agent. Além disso, a mensagem precisa ser marcada com a tag de agente humano. Apenas dessa forma uma mensagem poderá ser enviada por um app que não está no controle da conversa.

Permissões

A permissão pages_messaging é necessária para que os apps solicitem aos clientes a permissão para acessar dados de mensagens.

Webhooks

No protocolo de entrega, há dois conjuntos de webhooks que um app deve assinar: os webhooks de mensagens e os de espera. As notificações que o app recebe dependem do controle da conversa. Se for o controlador da conversa, o app receberá as notificações de webhook de mensagens. Se não, ele receberá somente as notificações de webhook de espera.

Usos comuns

Suporte ao cliente

Uma empresa usa um app para experiências automatizadas de perguntas frequentes, mas transfere o cliente a outro app com suporte ao vivo caso o problema não seja resolvido. O app automatizado foi definido como destinatário principal; por isso, todas as conversas pertencem a ele. Quando um agente de suporte ao vivo precisar participar da conversa, o app com suporte ao vivo pode solicitar o controle. Depois que a conversa com o agente for concluída, o controle da conversa será liberado de volta para o app de automação. Se o app do agente ao vivo precisar de mais tempo para gerenciar o problema, o app poderá solicitar uma extensão. Os dois apps devem assinar os webhooks para garantir que a conversa aconteça de forma organizada.

Campanha de marketing – Cadastros de produto

Uma empresa veicula uma campanha de marketing e usa uma experiência automatizada para qualificar cadastros ou fornecer recomendações de produtos com base em um questionário. Após a qualificação dos cadastros, a empresa usa a Caixa de Entrada da Página do Facebook ou do Instagram para acompanhar os clientes em potencial. O app automatizado foi definido como destinatário principal; por isso, todas as conversas pertencem a ele. Assim que o app automatizado concluir a fase de qualificação de cadastros, o controle da conversa será passado para a Caixa de Entrada da Página do Facebook ou do Instagram. Quando a conversa for finalizada na Caixa de Entrada da Página do Facebook ou do Instagram, marque a conversa como Concluída. Isso liberará o controle de conversa para o app principal. Os dois apps devem assinar os webhooks para garantir que a conversa aconteça de forma organizada.

Anúncios de clique para o Messenger

Uma empresa veicula uma campanha de marketing e envia os clientes em potencial para um app automatizado que oferece uma experiência do Messenger. O app automatizado foi definido como destinatário principal; por isso, todas as conversas pertencem a ele. Quando um agente de suporte ao vivo precisar participar da conversa, o app com suporte ao vivo pode solicitar o controle. Depois que a conversa com o agente for concluída, o controle da conversa será liberado de volta para o app de automação. Se o app do agente ao vivo precisar de mais tempo para gerenciar o problema, o app poderá solicitar uma extensão. Os dois apps devem assinar os webhooks para garantir que a conversa aconteça de forma organizada.

Boas práticas

Recomendamos que a experiência automatizada seja definida como destinatário principal, e não o app com agente ao vivo. Além disso, o app com agente ao vivo deve acompanhar os eventos de espera, realizando ações somente se necessário.
Sempre use a API de Controle da Conversa para verificar se você está controlando a conversa. Depois, faça outras chamadas de API com base no cenário. Não interfira nem faça interrupções se você não estiver no controle.
Não tente enviar mensagens no tópico quando outro app estiver controlando a conversa. Se você for um app principal, use a API de Controle da Conversa somente quando necessário. Caso não haja urgência ou você não seja o app principal, solicite o controle da conversa.
Respeite o evento de solicitação do controle da conversa por apps em todos os casos possíveis, atribuindo o controle para o solicitante. Caso você não consiga passar o controle de forma imediata, use a API de Transferência de Metadados para enviar contexto adicional ao solicitante e forme uma fila para transferir o controle de tópico quando possível.
Quando você concluir a conversa, passe o controle do tópico ao app solicitante que está na fila ou coloque o controle no modo ocioso, para que um app possa assumir a conversa. Caso contrário, a conversa do app será liberada automaticamente e entrará no modo ocioso depois de 24 horas. Faça a codificação desse cenário e do estado relacionado.
Se você perceber que a conversa está ociosa ao fazer uma chamada da API de Controle da Conversa, use Solicitar controle da conversa para assumir o controle a fim de enviar mensagens ao usuário de forma exclusiva sem interrupções e libere-a assim que terminar.

Saiba mais

Saiba mais sobre os componentes do protocolo de entrega.

Próximas etapas

Agora que você sabe como funciona o protocolo de entrega, faça o seguinte para implementá-lo: