# Modelo (API oficial)

Modelo aprovado na Meta: é o jeito de iniciar conversa ou de falar depois de 24 h sem resposta na API oficial.

- `name`: o nome do modelo, como aprovado na Meta.
- `language`: o idioma do modelo (`pt_BR`).
- `components`: os parâmetros do modelo, no formato da Meta.

Só na API oficial (`whatsapp_cloud`). O envio é na hora (a API oficial não tem fila): a resposta volta depois que a Meta aceita, com o `wamid` como `id` e `status: pending`, ou com o erro. A mensagem traz em `text` o modelo montado com os parâmetros, como o contato vê; se a api não conseguir ler o modelo na Meta, vai o nome dele.

## Canais

| Canal | Funciona | Observação |
|---|---|---|
| WhatsApp (Web) | Não |  |
| WhatsApp (API oficial) | Sim |  |
| Instagram | Não |  |
| Messenger | Não |  |
| Telegram | Não |  |

## Pedido

`POST /messages` com `"type": "template"`. [Testar](/endpoint/post/messages)

```json
{
  "to": "5511999999999",
  "type": "template",
  "name": "pedido_enviado",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "42"
        }
      ]
    }
  ]
}
```

## Resposta

A própria mensagem (`OrkesioMessage`), no formato do `message.sent` e da busca. Volta depois que a Meta aceita, com `status: pending` e o `wamid` como `id`. O resultado chega em `message.status` (a falha também em `message.failed`).

```json
{
  "id": "wamid.HBgNNTUxMTk5OTk5OTk5OVUCABEYEjQ4QjE2RjJBMEE5QjE2RjJBAA==",
  "chat_id": "5511999999999@s.whatsapp.net",
  "author": {
    "id": "5511888888888@s.whatsapp.net",
    "phone": "5511888888888"
  },
  "direction": "out",
  "sent_at": "2026-10-17T12:00:00.000Z",
  "category": "conversation",
  "type": "template",
  "text": "Seu pedido 42 foi enviado.",
  "sent_by": "api",
  "status": "pending"
}
```

## No webhook

O que chega no seu webhook (ou em `GET /events`) depois do envio.

### message.sent

Quando a mensagem sai. [O evento `message.sent`](/webhook/message.sent)

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "message.sent",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_cloud"
  },
  "data": {
    "message": {
      "id": "wamid.HBgNNTUxMTk5OTk5OTk5OVUCABEYEjQ4QjE2RjJBMEE5QjE2RjJBAA==",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511888888888@s.whatsapp.net",
        "phone": "5511888888888"
      },
      "direction": "out",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "conversation",
      "type": "template",
      "text": "Seu pedido 42 foi enviado.",
      "sent_by": "api"
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "type": "direct"
    }
  }
}
```

### message.status

`sent`, `delivered` e `read`, um evento por mudança. [O evento `message.status`](/webhook/message.status)

```json
{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD6J",
  "type": "message.status",
  "created_at": "2026-10-17T12:00:05.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_cloud"
  },
  "data": {
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "type": "direct"
    },
    "status": "delivered",
    "at": "2026-10-17T12:00:05.000Z",
    "messages": [
      {
        "id": "wamid.HBgNNTUxMTk5OTk5OTk5OVUCABEYEjQ4QjE2RjJBMEE5QjE2RjJBAA=="
      }
    ]
  }
}
```