# Oratrix API - Interativo Instagram

## Status

Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots.

Este grupo contem endpoints interativos exclusivos para **Instagram DM**.

Para o Wezapp Shots, estes endpoints sao recursos auxiliares/futuros. O foco inicial do Shots continua sendo disparo WhatsApp, campanhas, bases, shots e chipeira digital.

## Base URL

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}
```

## Autenticacao

```http
Authorization: Bearer {token}
```

## Restricao do provedor

```text
Instagram only
```

## Endpoints do grupo

Total documentado nesta parte: 5 endpoints.

---

## 1. Quick Reply via Instagram DM

```http
POST /sendInteractive/instagram/quickReply
```

Nome na documentacao Oratrix:

```text
InstagramQuickReply
```

Descricao:

Enviar Quick Reply via Instagram DM. Suporta texto e tipo `user_phone_number`.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendInteractive/instagram/quickReply
```

Body JSON:

```json
{
  "ticketId": 1262,
  "message": "Escolha uma opcao:",
  "quickReplies": [
    {
      "content_type": "text",
      "title": "Sim",
      "payload": "YES"
    },
    {
      "content_type": "text",
      "title": "Nao",
      "payload": "NO"
    },
    {
      "content_type": "user_phone_number"
    }
  ]
}
```

---

## 2. Button Template via Instagram DM

```http
POST /sendInteractive/instagram/buttonTemplate
```

Nome na documentacao Oratrix:

```text
InstagramButtonTemplate
```

Descricao:

Enviar Button Template via Instagram DM com ate 3 botoes `postback` ou `web_url`.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendInteractive/instagram/buttonTemplate
```

Body JSON:

```json
{
  "ticketId": 1262,
  "message": "Selecione uma acao:",
  "buttons": [
    {
      "type": "postback",
      "title": "Comprar",
      "payload": "BUY"
    },
    {
      "type": "web_url",
      "title": "Visitar site",
      "url": "https://exemplo.com"
    }
  ]
}
```

---

## 3. Generic Template via Instagram DM

```http
POST /sendInteractive/instagram/genericTemplate
```

Nome na documentacao Oratrix:

```text
InstagramGenericTemplate
```

Descricao:

Enviar Generic Template, como carrossel de cards com imagem, titulo e botoes, via Instagram DM.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendInteractive/instagram/genericTemplate
```

Body JSON:

```json
{
  "ticketId": 1262,
  "elements": [
    {
      "title": "Produto 1",
      "subtitle": "Descricao",
      "image_url": "https://exemplo.com/img.jpg",
      "buttons": [
        {
          "type": "postback",
          "title": "Ver",
          "payload": "PROD_1"
        }
      ]
    }
  ]
}
```

---

## 4. Gerenciar Ice Breakers do Instagram

```http
POST /instagram/iceBreakers
```

Nome na documentacao Oratrix:

```text
InstagramIceBreakers
```

Descricao:

Gerenciar perguntas iniciais do Instagram.

Acoes informadas:

```text
get | set | delete
```

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/instagram/iceBreakers
```

Body JSON:

```json
{
  "action": "set",
  "iceBreakers": [
    {
      "question": "Qual o horario?",
      "payload": "HOURS"
    },
    {
      "question": "Voces fazem entrega?",
      "payload": "DELIVERY"
    }
  ]
}
```

---

## 5. Gerenciar Persistent Menu do Instagram

```http
POST /instagram/persistentMenu
```

Nome na documentacao Oratrix:

```text
InstagramPersistentMenu
```

Descricao:

Gerenciar Persistent Menu do Instagram.

Acoes informadas:

```text
get | set | delete
```

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/instagram/persistentMenu
```

Body JSON:

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

## Mapeamento sugerido com Wezapp Shots

| Wezapp Shots | Oratrix |
|---|---|
| Canal Instagram futuro | Endpoints `/sendInteractive/instagram/*` |
| Ticket externo | `ticketId` |
| Automacao futura de DM | Quick Reply, Button Template e Generic Template |
| Configuracao de canal Instagram | Ice Breakers e Persistent Menu |

## Observacoes para arquitetura

Os endpoints de envio interativo usam `ticketId`, indicando dependencia de uma conversa/ticket existente no Oratrix.

Os endpoints `/instagram/iceBreakers` e `/instagram/persistentMenu` configuram recursos do canal, nao uma campanha especifica do Shots.

## Pendencias tecnicas para validar

- Confirmar se `ticketId` e obrigatorio em todos os envios interativos.
- Confirmar limites de `quickReplies`.
- Confirmar limite real de 3 botoes em `buttonTemplate`.
- Confirmar limite de elementos em `genericTemplate`.
- Confirmar formato de eventos retornados em respostas de botoes.
- Confirmar efeitos das acoes `get`, `set` e `delete` em ice breakers.
- Confirmar efeitos das acoes `get`, `set` e `delete` em persistent menu.
- Confirmar permissao necessaria no canal Instagram para alterar configuracoes.

## Regras recomendadas para o Wezapp Shots

1. Nao usar endpoints Instagram na primeira versao focada em WhatsApp, salvo decisao explicita.
2. Separar claramente campanhas WhatsApp de futuras campanhas Instagram.
3. Registrar auditoria quando alterar Ice Breakers ou Persistent Menu.
4. Nao misturar metricas de Instagram com shots WhatsApp sem regra comercial definida.
5. Tratar estes endpoints como expansao multicanal futura.