Plataforma do Messenger

Referência da API de Envio

A API de Envio é a principal API usada para enviar mensagens a usuários, inclusive textos, anexos, modelos, ações do remetente e muito mais.

Criação

Crie e envie mensagens para seus clientes ou pessoas interessadas da sua Página do Facebook.

Antes de começar

Você precisará de:

  • Um token de acesso à Página solicitada por uma pessoa que possa executar a tarefa MESSAGE na Página
  • Permissão pages_messaging
  • Que o destinatário da mensagem tenha enviado uma mensagem a sua Página nas últimas 24 horas ou concordado em receber mensagens na sua Página fora da janela de mensagens padrão de 24 horas

Limitações

  • As tags de mensagens não podem ser usadas para enviar conteúdo promocional

A API de Envio não inclui o recipient_id na resposta a mensagens enviadas usando recipient.user_ref ou recipient.phone_number para identificar o destinatário.

Exemplo de solicitação

Para enviar uma mensagem a uma pessoa, envie uma solicitação POST ao ponto de extremidade /PAGE-ID/messsages com o conjunto de parâmetros messaging_type e recipient o conteúdo da mensagem.

Formatado para leitura.

O exemplo abaixo é uma resposta à mensagem de uma pessoa na qual a mensagem enviada pela sua Página consiste apenas em texto.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

Se tudo der certo, seu app receberá a seguinte resposta JSON:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

Parâmetros

ParâmetroDescrição

message

objeto

Tipo de mensagem enviada pela sua Página. Ao usar esse parâmetro, deve ser definido text ou attachement.

  • Objeto attachment – exibe uma prévia da URL. É usado para enviar mensagens com mídia ou Mensagens estruturadas. text ou attachment deve ser definido.

  • metadata – uma string de dados adicionais que você deseja passar no webhook message_echo. Deve ter menos de 1000 caracteres.

  • quick_replies – uma matriz de respostas rápidas enviadas em uma mensagem.
  • text – uma mensagem com somente texto. Deve ser UTF-8 e ter menos de 2000 caracteres.

messaging_type

enum

Obrigatório

Tipo de mensagem a ser enviada

  • RESPONSE – a mensagem é uma resposta a uma mensagem recebida. Isso inclui mensagens promocionais e não promocionais enviadas dentro da janela de mensagens padrão de 24 horas. Por exemplo, use essa tag para responder se uma pessoa solicitar a confirmação de reserva ou atualização de status.
  • UPDATE – a mensagem está sendo enviada proativamente e não é uma resposta a uma mensagem recebida. Isso inclui mensagens promocionais e não promocionais enviadas dentro da janela de mensagens padrão de 24 horas.
  • MESSAGE_TAG – a mensagem não é promocional e está sendo enviada fora da janela de mensagens padrão de 24 horas com uma tag de mensagem. A mensagem deve corresponder ao uso permitido para a tag.

notification_type

enum

Tipo de notificação push recebida por uma pessoa.

  • NO_PUSH – sem notificações.
  • REGULAR (padrão) – som ou vibração de quando uma mensagem é recebida por uma pessoa.
  • SILENT_PUSH – notificação somente na tela.

recipient

objeto

Obrigatório

A pessoa que receberá a mensagem enviada pela sua Página.

  • id – o ID do escopo da Página para a pessoa que costuma enviar uma mensagem em resposta àquela recebida por sua Página nas últimas 24 horas ou para uma pessoa que concordou em receber mensagens de sua Página fora da janela de mensagens padrão de 24 horas.
  • user_ref – referência para a pessoa que costuma enviar uma mensagem em resposta a uma caixa de seleção ou plug-in de bate-papo com o cliente.
  • comment_id – o ID do comentário que é usado para enviar uma mensagem como uma Resposta Privada a um Comentário de um visitante na Publicação da sua Página.
  • post_id – o ID da Publicação da Página que é usada para enviar uma mensagem como uma Resposta Privada a uma Publicação de um visitante na sua Página.

sender_action

enum

O ícone de ação mostrado na janela de mensagens que representa a ação executada pela Página em uma mensagem recebida na Página de uma pessoa.

  • typing_on – mostra o balão de digitação quando a Página estiver preparando uma resposta.
  • typing_off – não mostra o balão de digitação.
  • mark_seen – mostra o ícone de visualização para mensagens que foram vistas na Página.

Somente pode ser enviada com o parâmetro recipient. Não pode ser enviada com o parâmetro message, mas como uma solicitação separada.

tag

enum

Uma tag que permite que sua Página envie uma mensagem para uma pessoa fora da janela de mensagens padrão de 24 horas.

  • ACCOUNT_UPDATE – marca a mensagem que você está enviando para seu cliente como uma atualização não recorrente no app ou conta dele. Mostrar usos permitidos.

    Não disponível nas mensagens da API do Instagram.

  • CONFIRMED_EVENT_UPDATE – marca a mensagem enviada ao seu cliente como um lembrete para um próximo evento ou uma atualização para um evento em andamento para o qual ele está registrado. Mostrar usos permitidos.

    Não disponível nas mensagens da API do Instagram.

  • CUSTOMER_FEEDBACK – marca a mensagem enviada ao seu cliente como uma Pesquisa de Satisfação do Cliente . As mensagens de feedback do cliente devem ser enviadas até 7 dias após a última mensagem dele. Mostrar usos permitidos.

    Não disponível nas mensagens da API do Instagram.

  • HUMAN_AGENT - Obrigatório nas mensagens da API do Instagram. Quando essa tag é adicionada a uma mensagem enviada a uma pessoa, ela permite que um agente humano responda à mensagem. As mensagens podem ser enviadas até 7 dias após o recebimento da mensagem. O suporte de agente humano ajuda a solucionar problemas que não podem ser resolvidos na janela de mensagens padrão. Mostrar usos permitidos.
    • Os apps precisam solicitar a permissão Human Agent pelo painel App do Desenvolvedor. Navegue no painel App -> avaliação do App -> Permissões e Recursos -> Agente Humano. Os apps aprovados para acesso beta antes da permissão de agente humano não precisam ser cadastrados novamente para acesso.

    A permissão Human Agent não está disponível no modo de acesso padrão ou em desenvolvimento. Você precisa concluir o processo de avaliação do app antes de usar a tag de agente humano. Durante o envio da avaliação do app, forneça instruções claras e uma demonstração de como você pretende usar a tag de agente humano em suas experiências.

  • POST_PURCHASE_UPDATE – marca a mensagem enviada ao seu cliente como uma atualização de uma compra recente feita por ele. Mostrar usos permitidos.

    Não disponível nas mensagens da API do Instagram.

Usos de tag em mensagens

A tabela abaixo mostra os tipos de mensagens para cada tag de mensagem.

Tag de mensagensUtilização

ACCOUNT_UPDATE

Usos permitidos

  • Uma notificação de alteração no status de um app, como cartão de crédito ou candidatura de emprego.
  • Uma notificação de atividades suspeitas, como alertas de fraude.

Usos não permitidos (lista não exaustiva).

  • Conteúdo promocional, incluindo, entre outros, ofertas, promoções, cupons e descontos para conteúdo recorrente (por exemplo, extrato pronto, fatura vencida, novas ofertas de empregos).
  • Comando interativo para qualquer pesquisa, enquete ou avaliações não relacionadas a uma interação anterior no Messenger

Não disponível nas mensagens da API do Instagram.

CONFIRMED_EVENT_UPDATE

Usos permitidos

  • Um lembrete para uma próxima aula, um compromisso ou um evento agendado por um usuário
  • Uma confirmação da reserva ou participação de um usuário em um evento ou compromisso aceito
  • Uma notificação para o transporte ou a viagem programada de um usuário, como chegada, cancelamento, atraso de bagagem ou outras alterações no status da viagem

Usos não permitidos (lista não exaustiva).

  • Conteúdo promocional, inclusive, entre outros, promoções, ofertas, cupons e descontos
  • Conteúdo relacionado a um evento no qual o usuário não se inscreveu (por exemplo, lembretes para comprar ingressos de eventos, venda cruzada de outros eventos, programações de passeios etc.)
  • Mensagens relacionadas a eventos passados
  • Comando interativo para qualquer pesquisa, enquete ou avaliações não relacionadas a uma interação anterior no Messenger

Não disponível nas mensagens da API do Instagram.

CUSTOMER_FEEDBACK

Usos permitidos

  • Pesquisa sobre suporte de compras
  • Pesquisa sobre feedback de evento
  • Avaliações de produtos

Usos não permitidos (lista não exaustiva).

  • A tag somente pode ser usada com o Modelo de Feedback de Clientes. O uso com qualquer outro propósito é proibido e não funcionará.

Não disponível nas mensagens da API do Instagram.

HUMAN_AGENT

Usos permitidos

  • Suporte de agente humano para problemas que não podem ser solucionados dentro da janela de mensagens padrão de 24 horas, como resolver problemas fora do horário comercial normal ou problemas que exigem mais de 24 horas para resolução

Usos não permitidos (lista não exaustiva).

  • Mensagens automáticas
  • Conteúdo não relacionado à solicitação de usuário

Obrigatório nas mensagens da API do Instagram.

POST_PURCHASE_UPDATE

Usos permitidos

  • Confirmação de uma transação, como faturas ou recibos
  • Atualização de status para uma remessa, como produto em trânsito, enviado, entregue ou atrasado
  • Atualização de status que exige que um usuário execute uma ação para uma solicitação feita pelo usuário, como cartão de crédito recusado, itens de pedidos pendentes ou outras atualizações de pedidos que exigem ação do usuário

Usos não permitidos (lista não exaustiva).

  • Conteúdo promocional, inclusive, entre outros, promoções, ofertas, cupons e descontos
  • Mensagens que fazem venda cruzada ou upsell de produtos ou serviços
  • Comando interativo para qualquer pesquisa, enquete ou avaliações não relacionadas a uma interação anterior no Messenger

Não disponível nas mensagens da API do Instagram.

Leitura

Não é possível realizar essa operação neste ponto de extremidade.

Para informações sobre as conversas das quais sua Página faz parte, acesse Referência de Conversas da Página.

Atualização

Não é possível realizar essa operação neste ponto de extremidade.

Exclusão

Não é possível realizar essa operação neste ponto de extremidade.

Veja também

Suporte ao desenvolvedor