# Oratrix API - Interativo Messenger

## Status

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

Este grupo contem endpoints interativos exclusivos para **Messenger**.

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
Messenger only
```

## Endpoints do grupo

Total documentado nesta parte: 9 endpoints.

---

## 1. Quick Reply via Messenger

```http
POST /sendInteractive/messenger/quickReply
```

Nome na documentacao Oratrix:

```text
MessengerQuickReply
```

Descricao:

Enviar Quick Reply via Messenger. Suporta texto e tipo `user_phone_number`.

URL completa:

```text
https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/sendInteractive/messenger/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"
    }
  ]
}
```

---

## 2. Button Template via Messenger

```http
POST /sendInteractive/messenger/buttonTemplate
```

Nome na documentacao Oratrix:

```text
MessengerButtonTemplate
```

Descricao:

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

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "message": "Selecione:",
  "buttons": [
    {
      "type": "postback",
      "title": "Opcao 1",
      "payload": "OPT_1"
    },
    {
      "type": "web_url",
      "title": "Visitar",
      "url": "https://exemplo.com"
    }
  ]
}
```

---

## 3. Generic Template via Messenger

```http
POST /sendInteractive/messenger/genericTemplate
```

Nome na documentacao Oratrix:

```text
MessengerGenericTemplate
```

Descricao:

Enviar Generic Template, como carrossel de cards, via Messenger.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "elements": [
    {
      "title": "Card 1",
      "subtitle": "Subtitulo",
      "image_url": "https://exemplo.com/img.jpg",
      "buttons": [
        {
          "type": "postback",
          "title": "Acao",
          "payload": "ACT"
        }
      ]
    }
  ]
}
```

---

## 4. Media Template via Messenger

```http
POST /sendInteractive/messenger/mediaTemplate
```

Nome na documentacao Oratrix:

```text
MessengerMediaTemplate
```

Descricao:

Enviar Media Template, imagem ou video, com botoes via Messenger. URL externa e convertida em `attachment_id` automaticamente.

URL completa:

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

Body JSON:

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

---

## 5. Receipt Template via Messenger

```http
POST /sendInteractive/messenger/receiptTemplate
```

Nome na documentacao Oratrix:

```text
MessengerReceiptTemplate
```

Descricao:

Enviar Receipt Template, recibo de compra, via Messenger.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "receipt": {
    "recipient_name": "Joao Silva",
    "order_number": "ORD-001",
    "currency": "BRL",
    "payment_method": "PIX",
    "summary": {
      "total_cost": 150
    },
    "elements": [
      {
        "title": "Produto A",
        "price": 100,
        "quantity": 1
      },
      {
        "title": "Produto B",
        "price": 50,
        "quantity": 1
      }
    ]
  }
}
```

---

## 6. Message Tag via Messenger

```http
POST /sendInteractive/messenger/messageTag
```

Nome na documentacao Oratrix:

```text
MessengerMessageTag
```

Descricao:

Enviar mensagem fora da janela de 24h com Message Tag.

Exemplos informados:

```text
POST_PURCHASE_UPDATE
ACCOUNT_UPDATE
CONFIRMED_EVENT_UPDATE
HUMAN_AGENT
```

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "message": "Seu pedido foi aprovado.",
  "tag": "POST_PURCHASE_UPDATE"
}
```

Observacao importante:

Message Tags normalmente possuem regras especificas da plataforma. O Wezapp deve validar a regra operacional antes de usar em producao.

---

## 7. Customer Feedback Template via Messenger

```http
POST /sendInteractive/messenger/customerFeedback
```

Nome na documentacao Oratrix:

```text
MessengerCustomerFeedback
```

Descricao:

Enviar Customer Feedback Template, como CSAT, NPS ou CES, via Messenger. Requer `business_privacy_url`.

URL completa:

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

Body JSON:

```json
{
  "ticketId": 1262,
  "title": "Avalie sua experiencia",
  "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?"
        }
      ]
    }
  ]
}
```

---

## 8. Gerenciar Greeting Text do Messenger

```http
POST /messenger/greeting
```

Nome na documentacao Oratrix:

```text
MessengerGreeting
```

Descricao:

Gerenciar Greeting Text da pagina do Messenger.

Acoes informadas:

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

URL completa:

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

Body JSON:

```json
{
  "action": "set",
  "greetings": [
    {
      "locale": "default",
      "text": "Ola! Como podemos ajudar?"
    }
  ]
}
```

---

## 9. Gerenciar Personas do Messenger

```http
POST /messenger/personas
```

Nome na documentacao Oratrix:

```text
MessengerPersonas
```

Descricao:

Gerenciar Personas da pagina do Messenger.

Acoes informadas:

```text
list | create | delete
```

URL completa:

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

Body JSON:

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

## Mapeamento sugerido com Wezapp Shots

| Wezapp Shots | Oratrix |
|---|---|
| Canal Messenger futuro | Endpoints `/sendInteractive/messenger/*` |
| Ticket externo | `ticketId` |
| Automacao futura de Messenger | Quick Reply, templates e message tags |
| Configuracao de canal Messenger | Greeting e Personas |

## Observacoes para arquitetura

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

Os endpoints `/messenger/greeting` e `/messenger/personas` configuram recursos da pagina/canal, nao uma campanha especifica do Shots.

## Pendencias tecnicas para validar

- Confirmar se `ticketId` e obrigatorio em todos os envios interativos.
- Confirmar limite de `quickReplies`.
- Confirmar limite real de 3 botoes em `buttonTemplate`.
- Confirmar limite de elementos em `genericTemplate`.
- Confirmar tipos aceitos em `mediaType`.
- Confirmar tamanho e formato aceito para `mediaUrl`.
- Confirmar regras e validacoes das Message Tags.
- Confirmar formato de eventos retornados em respostas de botoes.
- Confirmar efeitos das acoes `get`, `set` e `delete` em greeting.
- Confirmar efeitos das acoes `list`, `create` e `delete` em personas.

## Regras recomendadas para o Wezapp Shots

1. Nao usar endpoints Messenger na primeira versao focada em WhatsApp, salvo decisao explicita.
2. Separar claramente campanhas WhatsApp de futuras campanhas Messenger.
3. Registrar auditoria quando alterar Greeting ou Personas.
4. Nao misturar metricas de Messenger com shots WhatsApp sem regra comercial definida.
5. Tratar Message Tags com cuidado por dependerem de regras especificas da plataforma.