Mensagens Interativas no Instagram e Messenger

Canais de Instagram e Messenger usam os recursos de mensageria interativa da própria Meta (Send API do Messenger Platform). Estes endpoints espelham o formato oficial da Meta para cada tipo de template, além de endpoints de configuração de canal (ice breakers, menu persistente, saudação e personas). Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

A coleção oficial do Postman usa nomes de variável diferentes para as pastas de Instagram e Messenger ({{BASE_URL}}, {{API_TOKEN}}, {{apiId}}) em vez dos nomes padrão ({{BaseUrl}}, {{BearerToken}}, {{ApiID}}). Os valores e o comportamento são idênticos — veja Autenticação → Coleção do Postman. Nesta página usamos a notação padrão {BaseUrl} / {ApiID} por consistência com o restante da referência.

Todos os endpoints de envio abaixo endereçam o destinatário por ticketId — obtenha-o via Enviar por Ticket ou de um webhook recebido daquela conversa.

Instagram

Quick Reply

Envia uma mensagem com botões de resposta rápida (quick replies), incluindo o tipo especial de solicitação de telefone.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/quickReply

{
  "ticketId": 123,
  "message": "Escolha uma opção:",
  "quickReplies": [
    { "content_type": "text", "title": "Sim", "payload": "YES" },
    { "content_type": "text", "title": "Não", "payload": "NO" },
    { "content_type": "user_phone_number" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket (conversa) de destino.
`message`	string	Sim	Texto principal exibido acima dos botões.
`quickReplies`	array	Sim	Lista de opções de resposta rápida.
`quickReplies[].content_type`	string	Sim	`text` para um botão de texto, ou `user_phone_number` para solicitar o telefone do contato (sem `title`/`payload`).
`quickReplies[].title`	string	Sim*	Texto do botão. Obrigatório quando `content_type` é `text`.
`quickReplies[].payload`	string	Sim*	Valor retornado via webhook quando o botão for tocado. Obrigatório quando `content_type` é `text`.

Button Template

Envia até 3 botões de ação (postback ou web_url) abaixo de uma mensagem.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/buttonTemplate

{
  "ticketId": 123,
  "message": "Clique em uma opção:",
  "buttons": [
    { "type": "postback", "title": "Comprar", "payload": "BUY" },
    { "type": "postback", "title": "Falar com atendente", "payload": "HUMAN" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`message`	string	Sim	Texto principal da mensagem.
`buttons`	array	Sim	Até 3 botões.
`buttons[].type`	string	Sim	`postback` (dispara evento via webhook) ou `web_url` (abre um link).
`buttons[].title`	string	Sim	Texto do botão.
`buttons[].payload`	string	Sim*	Identificador retornado via webhook. Obrigatório quando `type` é `postback`.
`buttons[].url`	string	Sim*	URL a abrir. Obrigatório quando `type` é `web_url`.

Generic Template (Cards)

Envia um carrossel de cards horizontais, cada um com imagem, título, subtítulo e botões próprios.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/genericTemplate

{
  "ticketId": 123,
  "elements": [
    {
      "title": "Produto 1",
      "subtitle": "Descrição",
      "image_url": "https://exemplo.com/produto1.jpg",
      "buttons": [{ "type": "postback", "title": "Ver", "payload": "PROD_1" }]
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`elements`	array	Sim	Cards do carrossel (a Meta permite até 10).
`elements[].title`	string	Sim	Título do card.
`elements[].subtitle`	string	Não	Subtítulo exibido abaixo do título.
`elements[].image_url`	string	Não	Imagem de capa do card.
`elements[].buttons`	array	Não	Botões do card, no mesmo formato de Button Template.

Ice Breakers (get / set / delete)

Gerencia as perguntas de atalho (“ice breakers”) exibidas antes da primeira interação do contato com o perfil no Instagram.

POST https://{BaseUrl}/v2/api/external/{ApiID}/instagram/iceBreakers

Definir os ice breakers (action: "set"):

{
  "action": "set",
  "iceBreakers": [
    { "question": "Qual o horário?", "payload": "HOURS" },
    { "question": "Vocês fazem entrega?", "payload": "DELIVERY" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`action`	string	Sim	`get` para consultar a configuração atual, `set` para substituí-la, ou `delete` para removê-la.
`iceBreakers`	array	Sim*	Lista de perguntas. Obrigatório quando `action` é `set`. Máximo de 4 perguntas (limite da Meta).
`iceBreakers[].question`	string	Sim*	Texto da pergunta exibida ao contato.
`iceBreakers[].payload`	string	Sim*	Identificador retornado via webhook quando o contato tocar na pergunta.

Para action: "get" ou action: "delete", envie apenas o campo action — os demais campos não se aplicam. Gerencia o menu persistente exibido no composer de mensagens do Instagram.

POST https://{BaseUrl}/v2/api/external/{ApiID}/instagram/persistentMenu

Definir o menu (action: "set"):

{
  "action": "set",
  "composerInputDisabled": false,
  "menuItems": [
    { "type": "postback", "title": "Menu", "payload": "MAIN_MENU" },
    { "type": "web_url", "title": "Site", "url": "https://exemplo.com" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`action`	string	Sim	`get`, `set` ou `delete`.
`composerInputDisabled`	boolean	Não	Quando `true`, desabilita a caixa de texto livre, deixando apenas o menu como opção.
`menuItems`	array	Sim*	Itens do menu. Obrigatório quando `action` é `set`.
`menuItems[].type`	string	Sim*	`postback` ou `web_url`.
`menuItems[].title`	string	Sim*	Texto exibido no item do menu.
`menuItems[].payload`	string	Sim*	Identificador via webhook. Obrigatório quando `type` é `postback`.
`menuItems[].url`	string	Sim*	URL a abrir. Obrigatório quando `type` é `web_url`.

Messenger

Quick Reply

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/quickReply

{
  "ticketId": 123,
  "message": "Escolha:",
  "quickReplies": [
    { "content_type": "text", "title": "Sim", "payload": "YES" },
    { "content_type": "text", "title": "Não", "payload": "NO" }
  ]
}

Mesmos campos do Quick Reply do Instagram.

Button Template

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/buttonTemplate

{
  "ticketId": 123,
  "message": "Opções:",
  "buttons": [
    { "type": "postback", "title": "Opção 1", "payload": "OPT_1" },
    { "type": "web_url", "title": "Visitar", "url": "https://exemplo.com" }
  ]
}

Mesmos campos do Button Template do Instagram.

Generic Template (Cards)

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/genericTemplate

{
  "ticketId": 123,
  "elements": [
    {
      "title": "Card 1",
      "subtitle": "Subtítulo",
      "image_url": "https://exemplo.com/card1.jpg",
      "buttons": [{ "type": "postback", "title": "Ação", "payload": "ACT" }]
    }
  ]
}

Mesmos campos do Generic Template do Instagram.

Media Template

Envia uma imagem ou vídeo acompanhado de botões de ação.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/mediaTemplate

{
  "ticketId": 123,
  "mediaType": "image",
  "mediaUrl": "https://exemplo.com/imagem.jpg",
  "buttons": [{ "type": "postback", "title": "Comprar", "payload": "BUY" }]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`mediaType`	string	Sim	`image` ou `video`.
`mediaUrl`	string	Sim	URL pública do arquivo de mídia.
`buttons`	array	Não	Botões de ação, no mesmo formato de Button Template.

Receipt Template (Recibo)

Envia um recibo de pedido formatado — itens, quantidades, preços e total.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/receiptTemplate

{
  "ticketId": 123,
  "receipt": {
    "recipient_name": "João Silva",
    "order_number": "ORD-001",
    "currency": "BRL",
    "payment_method": "PIX",
    "summary": { "total_cost": 150.0 },
    "elements": [
      { "title": "Produto A", "price": 100.0, "quantity": 1 },
      { "title": "Produto B", "price": 50.0, "quantity": 1 }
    ]
  }
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`receipt.recipient_name`	string	Sim	Nome do cliente no recibo.
`receipt.order_number`	string	Sim	Número do pedido — deve ser único.
`receipt.currency`	string	Sim	Código da moeda — por exemplo, `BRL`.
`receipt.payment_method`	string	Sim	Forma de pagamento exibida no recibo.
`receipt.summary.total_cost`	number	Sim	Valor total do pedido.
`receipt.elements`	array	Sim	Itens do pedido, cada um com `title`, `price` e `quantity`.

Message Tag (Marketing / Utility)

Envia uma mensagem fora da janela padrão de 24 horas usando uma tag de mensagem da Meta, permitida apenas para determinadas categorias de conteúdo.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/messageTag

{
  "ticketId": 123,
  "message": "Seu pedido foi aprovado.",
  "tag": "POST_PURCHASE_UPDATE"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`message`	string	Sim	Texto da mensagem.
`tag`	string	Sim	Tag de mensagem aprovada pela Meta — por exemplo, `POST_PURCHASE_UPDATE`, `CONFIRMED_EVENT_UPDATE` ou `ACCOUNT_UPDATE`. Consulte a documentação da Meta para a lista completa e as regras de uso de cada tag.

Customer Feedback Template (NPS / CSAT)

Envia uma pesquisa de satisfação nativa do Messenger.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/customerFeedback

{
  "ticketId": 123,
  "title": "Avalie sua experiência",
  "subtitle": "Opcional",
  "business_privacy_url": "https://exemplo.com/privacidade",
  "expires_in_days": 7,
  "feedback_screens": [
    {
      "questions": [
        { "id": "CSAT", "type": "csat", "title": "Como foi nosso atendimento?" }
      ]
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`title`	string	Sim	Título da pesquisa.
`subtitle`	string	Não	Subtítulo exibido abaixo do título.
`business_privacy_url`	string	Sim	URL da política de privacidade — exigida pela Meta.
`expires_in_days`	integer	Não	Dias até a pesquisa expirar.
`feedback_screens`	array	Sim	Telas de perguntas da pesquisa.
`feedback_screens[].questions[].id`	string	Sim	Identificador da pergunta.
`feedback_screens[].questions[].type`	string	Sim	Tipo da pergunta — por exemplo, `csat` (satisfação) ou `nps`.
`feedback_screens[].questions[].title`	string	Sim	Texto da pergunta.

Greeting Text (get / set / delete)

Gerencia o texto de saudação exibido na tela inicial da conversa, antes do primeiro contato.

POST https://{BaseUrl}/v2/api/external/{ApiID}/messenger/greeting

{
  "action": "set",
  "greetings": [
    { "locale": "default", "text": "Olá! Como podemos ajudar?" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`action`	string	Sim	`get`, `set` ou `delete`.
`greetings`	array	Sim*	Lista de textos por localidade. Obrigatório quando `action` é `set`.
`greetings[].locale`	string	Sim*	Código de localidade, ou `"default"` para o texto padrão.
`greetings[].text`	string	Sim*	Texto de saudação exibido.

Personas (list / create / delete)

Gerencia personas — identidades de exibição (nome e foto) que podem ser atribuídas a mensagens enviadas por diferentes agentes ou bots, para que o contato veja de quem está recebendo a resposta.

POST https://{BaseUrl}/v2/api/external/{ApiID}/messenger/personas

Criar uma persona (action: "create"):

{
  "action": "create",
  "name": "Atendente Ana",
  "profilePictureUrl": "https://exemplo.com/ana.jpg"
}

Campo	Tipo	Obrigatório	Descrição
`action`	string	Sim	`list` para listar as personas existentes, `create` para criar uma nova, ou `delete` para remover uma existente.
`name`	string	Sim*	Nome de exibição da persona. Obrigatório quando `action` é `create`.
`profilePictureUrl`	string	Sim*	URL da foto de perfil da persona. Obrigatório quando `action` é `create`.
`personaId`	string	Sim*	ID da persona a remover. Obrigatório quando `action` é `delete`.

Resposta de Sucesso

Os endpoints de envio (sendInteractive/instagram/* e sendInteractive/messenger/*) retornam o formato padrão:

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 123
  }
}

Os endpoints de configuração de canal (iceBreakers, persistentMenu, greeting, personas) retornam:

{
  "success": true,
  "data": { ... }
}

Em action: "get", data traz a configuração atual; em action: "set" ou "create", traz a configuração aplicada; em action: "delete", traz apenas a confirmação da remoção.

Primeiros Passos

Mensagens