> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensagens Interativas no Instagram e Messenger

> Envie quick replies, templates de botões, cards, recibos e configure ice breakers, menu persistente, saudação e personas no Instagram e Messenger via API do PanÐá Zap.

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}`.

<Note>
  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](/api/authentication#colecao-do-postman). Nesta página usamos a notação padrão `{BaseUrl}` / `{ApiID}` por consistência com o restante da referência.
</Note>

Todos os endpoints de envio abaixo endereçam o destinatário por **`ticketId`** — obtenha-o via [Enviar por Ticket](/api/send-by-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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/quickReply
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/buttonTemplate
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/instagram/genericTemplate
```

```json theme={null}
{
  "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](#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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/instagram/iceBreakers
```

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

```json theme={null}
{
  "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.

### Persistent Menu (get / set / delete)

Gerencia o menu persistente exibido no composer de mensagens do Instagram.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/instagram/persistentMenu
```

**Definir o menu (`action: "set"`):**

```json theme={null}
{
  "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

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/quickReply
```

```json theme={null}
{
  "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](#quick-reply).

### Button Template

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/buttonTemplate
```

```json theme={null}
{
  "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](#button-template).

### Generic Template (Cards)

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/genericTemplate
```

```json theme={null}
{
  "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](#generic-template-cards).

### Media Template

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

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/mediaTemplate
```

```json theme={null}
{
  "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](#button-template-1). |

### Receipt Template (Recibo)

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

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/receiptTemplate
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/messageTag
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/messenger/customerFeedback
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/messenger/greeting
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/messenger/personas
```

**Criar uma persona (`action: "create"`):**

```json theme={null}
{
  "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:

```json theme={null}
{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 123
  }
}
```

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

```json theme={null}
{
  "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.