Criar resposta rápida

POST /replies

Guarda uma mensagem pronta (texto, imagem, vídeo, áudio, voz, documento, localização, contato, botões, lista, enquete ou a chave PIX) para o atendimento (e a IA) usar depois. Figurinha, vídeo redondo, carrossel, pedido de localização, evento, modelo e cobrança com valor respondem 400. Arquivo em base64 é guardado pela api (imagem 5 MB, áudio e vídeo 16 MB, documento 20 MB; até 50 MB por inbox); link externo fica como veio. Com on_whatsapp: true, a inbox precisa estar conectada.

Autenticação

[
  {
    "token": []
  }
]

{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}

Corpo da requisição

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReplyCreate"
      },
      "example": {
        "shortcut": "horario",
        "on_whatsapp": true,
        "message": {
          "type": "text",
          "text": "Atendemos de segunda a sexta, das 9h às 18h."
        }
      }
    }
  }
}

Respostas

{
  "201": {
    "description": "Criada.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Reply"
        },
        "example": {
          "id": "rq1a2b3c4d5e6f7",
          "shortcut": "horario",
          "on_whatsapp": true,
          "message": {
            "type": "text",
            "text": "Atendemos de segunda a sexta, das 9h às 18h."
          },
          "created_at": "2026-10-01T12:00:00.000Z",
          "updated_at": "2026-10-01T12:00:00.000Z"
        }
      }
    }
  },
  "400": {
    "description": "Pedido inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "on_whatsapp só vale para texto."
        }
      }
    }
  },
  "401": {
    "description": "Token inválido ou ausente.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "409": {
    "description": "`inbox_not_paired`: conecte a inbox ao WhatsApp antes. `inbox_not_connected`: com `on_whatsapp: true`, a inbox precisa estar conectada.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "inbox_not_connected",
          "message": "Conecte a inbox para sincronizar com o WhatsApp."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/InternalError"
  },
  "502": {
    "description": "`whatsapp_sync_failed`: o WhatsApp não aceitou a mudança na resposta rápida do WhatsApp Business; tente de novo.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "whatsapp_sync_failed",
          "message": "Não deu para sincronizar com o WhatsApp; tente de novo."
        }
      }
    }
  }
}

Estado: Disponível

Compatibilidade de canais

Canal	Compatível	Observação
WhatsApp (Web)	Sim
WhatsApp (API oficial)	Sim
Instagram	Sim
Messenger	Sim
Telegram	Sim

Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em GET /events): o resultado vem só na resposta.

Antes e depois (uazapi → Orkesio)

Na uazapi: POST /quick-replies.

shortCut → shortcut, aiDescription → ai_description, onWhatsApp → on_whatsapp.
message no formato do corpo do POST /messages, sem to (antes kind mais o corpo da /send/* correspondente).

#/components/schemas/ReplyCreate

{
  "type": "object",
  "additionalProperties": false,
  "description": "Atalho e mensagem são obrigatórios.",
  "properties": {
    "shortcut": {
      "type": "string",
      "minLength": 1,
      "description": "Atalho para achar a resposta (ex.: `endereco`)."
    },
    "ai_description": {
      "type": "string",
      "description": "Quando a IA deve enviar esta resposta ao contato. Vazio, a IA não a oferece."
    },
    "on_whatsapp": {
      "type": "boolean",
      "description": "`true` cria também nas respostas rápidas do WhatsApp Business. Só mensagem de texto, e a inbox precisa estar conectada."
    },
    "message": {
      "$ref": "#/components/schemas/ReplyMessage"
    }
  },
  "required": [
    "shortcut",
    "message"
  ]
}

#/components/schemas/ReplyMessage

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "text",
        "image",
        "video",
        "audio",
        "voice",
        "document",
        "location",
        "contacts",
        "poll",
        "buttons",
        "list",
        "payment"
      ],
      "description": "Tipo da mensagem. Os campos dele vão soltos, ao lado de `type`, no formato do envio."
    }
  },
  "required": [
    "type"
  ],
  "description": "Mensagem da resposta rápida, no formato do [envio](/docs/enviar) (`type` e os campos do tipo), sem `to`. Tipos aceitos: `text`, `image`, `video`, `audio`, `voice`, `document`, `location`, `contacts`, `buttons`, `list`, `poll` e `payment`. `payment` só com a chave PIX (`pix`, sem `amount`), que sai como o botão de copiar a chave; `contacts` leva um contato. Arquivo em `base64` é guardado pela api (imagem 5 MB, áudio e vídeo 16 MB, documento 20 MB; 50 MB por inbox); por `url`, fica como foi enviado. Guarda só o texto (ou a legenda), o arquivo e o nome do arquivo: `view_once`, `animated`, `mime_type`, `thumbnail` e `link_preview` diferente do padrão respondem 400. Não aceita `mentions`, `mention_all` nem `forwarded`. Figurinha, vídeo redondo, carrossel, pedido de localização, evento, modelo e cobrança com valor respondem 400.",
  "oneOf": [
    {
      "properties": {
        "type": {
          "const": "text"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentText"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "image"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentImage"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "video"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentVideo"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "audio"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentAudio"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "voice"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentVoice"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "document"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentDocument"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "location"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentLocation"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "contacts"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentContacts"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "poll"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentPoll"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "buttons"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentButtons"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "list"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentList"
        }
      ]
    },
    {
      "properties": {
        "type": {
          "const": "payment"
        }
      },
      "allOf": [
        {
          "$ref": "#/components/schemas/SendContentPayment"
        }
      ]
    }
  ],
  "unevaluatedProperties": false
}

#/components/schemas/SendContentText

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto da mensagem (com a formatação do WhatsApp). Vai como está: um `>1` respondendo a uma enquete é texto (o voto é `type: poll_vote`; a resposta a botões, `interactive_reply`)."
    },
    "link_preview": {
      "oneOf": [
        {
          "type": "boolean",
          "description": "`true`: prévia automática do primeiro link (o mesmo que omitir). `false`: sem prévia."
        },
        {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Título da prévia."
            },
            "description": {
              "type": "string",
              "description": "Texto de descrição da prévia."
            },
            "image_url": {
              "type": "string",
              "description": "Link da imagem da prévia."
            },
            "large": {
              "type": "boolean",
              "description": "Mostra a imagem grande, em vez da miniatura."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Prévia do link. Sem o campo, a api monta a prévia do primeiro link do texto; `false` desliga; um objeto define os dados da prévia."
    }
  },
  "required": [
    "text"
  ],
  "title": "texto"
}

#/components/schemas/SendContentImage

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "imagem"
}

#/components/schemas/SendContentVideo

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    },
    "animated": {
      "type": "boolean",
      "description": "Envia como GIF: o vídeo toca em loop e sem som, como os GIFs do WhatsApp (mande um MP4). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`. Só vale em `type: video`."
    }
  },
  "title": "vídeo"
}

#/components/schemas/SendContentAudio

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "áudio"
}

#/components/schemas/SendContentVoice

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "voz"
}

#/components/schemas/SendContentDocument

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Link público do arquivo. Use `url` ou `base64`."
    },
    "base64": {
      "type": "string",
      "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "text": {
      "type": "string",
      "description": "A legenda."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo (documentos)."
    },
    "thumbnail": {
      "type": "string",
      "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
    },
    "view_once": {
      "type": "boolean",
      "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
    }
  },
  "title": "documento"
}

#/components/schemas/SendContentLocation

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "Latitude."
    },
    "longitude": {
      "type": "number",
      "description": "Longitude."
    },
    "name": {
      "type": "string",
      "description": "O nome do lugar."
    },
    "address": {
      "type": "string",
      "description": "Endereço."
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "title": "localização"
}

#/components/schemas/SendContentContacts

{
  "type": "object",
  "required": [
    "contacts"
  ],
  "properties": {
    "contacts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome exibido."
          },
          "phones": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "description": "Número com DDI."
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "number"
                  ],
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "Número com DDI."
                    },
                    "wa_id": {
                      "type": "string",
                      "description": "Ignorado no envio (vem na mensagem recebida)."
                    }
                  }
                }
              ]
            },
            "description": "Telefones: o número com DDI, ou o objeto da mensagem recebida (`{\"number\": \"...\"}`), para reenviar como veio."
          },
          "email": {
            "type": "string",
            "description": "E-mail."
          },
          "organization": {
            "type": "string",
            "description": "Empresa."
          },
          "url": {
            "type": "string",
            "description": "Site."
          }
        },
        "required": [
          "name",
          "phones"
        ],
        "additionalProperties": false
      },
      "description": "Contato a compartilhar. Por enquanto vai um por mensagem: a lista precisa ter exatamente um item (com mais, responde 400).",
      "minItems": 1,
      "maxItems": 1
    }
  },
  "title": "contatos"
}

#/components/schemas/SendContentPoll

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "A pergunta."
    },
    "choices": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Opção."
      },
      "description": "Opções."
    },
    "selectable_count": {
      "type": "integer",
      "description": "Quantas opções o contato pode escolher: de `0` (várias) até o número de opções."
    }
  },
  "required": [
    "text",
    "choices"
  ],
  "title": "enquete"
}

#/components/schemas/SendContentButtons

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto, acima das opções. Quando há texto depois da primeira linha, ela é o cabeçalho (em negrito) e o resto é o corpo. Com uma linha só, ela vai como cabeçalho, sem corpo, também junto da mídia do cabeçalho. Na API oficial, o texto vai inteiro no corpo."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "url": {
      "type": "string",
      "description": "Mídia do cabeçalho (imagem, vídeo ou documento): link público do arquivo. Use `url` ou `base64`. O tipo sai do arquivo; na API oficial, da extensão do link (imagem quando não há)."
    },
    "base64": {
      "type": "string",
      "description": "Mídia do cabeçalho em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
    },
    "mime_type": {
      "type": "string",
      "description": "Tipo do arquivo do cabeçalho. Sem ele, a api descobre pelo conteúdo."
    },
    "filename": {
      "type": "string",
      "description": "Nome do arquivo do cabeçalho (documentos)."
    },
    "button_text": {
      "type": "string",
      "description": "Texto do botão que abre a lista (só `list`)."
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrkesioOption"
      },
      "description": "Botões (`buttons`) ou itens (`list`, agrupados por `section`). Sem `id`, a api usa o `title`. `title`, `id` e `value` não aceitam `|` nem quebra de linha; em `list`, `section` e `description` também não aceitam `[` e `]`. Na API oficial, `call` e `copy` respondem `unsupported_for_channel`."
    },
    "legacy": {
      "type": "boolean",
      "description": "Só `buttons`, só WhatsApp Web: envia no formato antigo de botões (`ButtonsMessage`), para quem ainda usa. Só botões de resposta (sem `url`, `call` e `copy`) e sem mídia no cabeçalho; o `text` vai inteiro no corpo, sem cabeçalho. O WhatsApp pode deixar de mostrar esse formato a qualquer momento. Nos outros canais responde `unsupported_for_channel`."
    }
  },
  "required": [],
  "title": "botões"
}

#/components/schemas/OrkesioOption

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id."
    },
    "title": {
      "type": "string",
      "description": "Título."
    },
    "description": {
      "type": "string",
      "description": "Descrição."
    },
    "action": {
      "type": "string",
      "enum": [
        "reply",
        "url",
        "call",
        "copy"
      ],
      "description": "O que o botão faz."
    },
    "value": {
      "type": "string",
      "description": "Link, telefone ou código, conforme `action`."
    },
    "section": {
      "type": "string",
      "description": "Seção (listas)."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false,
  "description": "Opção de menu ou botão."
}

#/components/schemas/SendContentList

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "O texto, acima das opções. Quando há texto depois da primeira linha, ela é o cabeçalho (em negrito) e o resto é o corpo. Com uma linha só, ela vai como cabeçalho, sem corpo. Na API oficial, o texto vai inteiro no corpo. A lista não aceita mídia no cabeçalho."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "button_text": {
      "type": "string",
      "description": "Texto do botão que abre a lista (só `list`)."
    },
    "choices": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OrkesioOption"
      },
      "description": "Botões (`buttons`) ou itens (`list`, agrupados por `section`). Sem `id`, a api usa o `title`. `title`, `id` e `value` não aceitam `|` nem quebra de linha; em `list`, `section` e `description` também não aceitam `[` e `]`. Na API oficial, `call` e `copy` respondem `unsupported_for_channel`."
    }
  },
  "required": [],
  "title": "lista"
}

#/components/schemas/SendContentPayment

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Valor. Sem `amount` e só com `pix`, sai o botão de copiar a chave; nesse caso `title`, `note`, `footer`, `currency` e `reference_id` respondem 400."
    },
    "currency": {
      "type": "string",
      "description": "Moeda (padrão `BRL`)."
    },
    "reference_id": {
      "type": "string",
      "description": "Número do pedido ou da fatura."
    },
    "order_id": {
      "type": "string",
      "description": "Mensagem de pedido (`order`) recebida do contato que esta cobrança atende: o `id` dela."
    },
    "title": {
      "type": "string",
      "description": "Título."
    },
    "text": {
      "type": "string",
      "description": "A nota da cobrança."
    },
    "footer": {
      "type": "string",
      "description": "Rodapé."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Item."
          },
          "quantity": {
            "type": "number",
            "description": "Quantidade, inteiro a partir de 1."
          },
          "amount": {
            "type": "number",
            "description": "Valor do item. Ainda não é aceito (400): use `payment.amount`."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "description": "Itens da cobrança. Por enquanto, um item por cobrança.",
      "maxItems": 1
    },
    "pix": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Chave PIX."
        },
        "key_type": {
          "type": "string",
          "enum": [
            "cpf",
            "cnpj",
            "phone",
            "email",
            "evp"
          ],
          "description": "Tipo da chave (padrão `evp`)."
        },
        "merchant_name": {
          "type": "string",
          "description": "Recebedor."
        }
      },
      "required": [
        "key"
      ],
      "additionalProperties": false
    },
    "boleto": {
      "type": "string",
      "description": "Linha digitável do boleto."
    },
    "link": {
      "type": "string",
      "description": "Link de pagamento (só domínios homologados pelo WhatsApp)."
    },
    "invoice": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "Link público do arquivo. Use `url` ou `base64`."
        },
        "base64": {
          "type": "string",
          "description": "Arquivo em base64 (com ou sem o prefixo `data:`). Use `url` ou `base64`."
        },
        "mime_type": {
          "type": "string",
          "description": "Tipo do arquivo. Sem ele, a api descobre pelo conteúdo."
        },
        "filename": {
          "type": "string",
          "description": "Nome do arquivo (documentos)."
        },
        "thumbnail": {
          "type": "string",
          "description": "Miniatura JPEG em base64 (vídeo e documento). Sem ela, a api gera quando consegue."
        },
        "view_once": {
          "type": "boolean",
          "description": "Visualização única (foto, vídeo e voz). Só no WhatsApp Web: nos outros canais, `unsupported_for_channel`."
        }
      },
      "additionalProperties": false,
      "description": "Fatura (PDF): o arquivo, sem legenda."
    }
  },
  "title": "cobrança"
}

#/components/schemas/Reply

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "shortcut",
    "message",
    "created_at",
    "updated_at"
  ],
  "description": "Resposta rápida: uma mensagem pronta para o atendimento.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da resposta."
    },
    "shortcut": {
      "type": "string",
      "description": "Atalho para encontrar a resposta (e o que a IA usa para escolher)."
    },
    "ai_description": {
      "type": "string",
      "description": "Quando a IA deve enviar esta resposta ao contato. Vazio, a IA não a oferece."
    },
    "on_whatsapp": {
      "type": "boolean",
      "description": "Também está nas respostas rápidas do WhatsApp Business (só texto). Editar ou apagar aqui muda lá também."
    },
    "message": {
      "$ref": "#/components/schemas/ReplyMessage"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Criação. ISO 8601 em UTC com milissegundos."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Última alteração. ISO 8601 em UTC com milissegundos."
    }
  }
}

#/components/schemas/OrkesioError

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}

#/components/responses/RateLimited

{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}

#/components/responses/InternalError

{
  "description": "`internal_error`: falha inesperada na api (no banco, por exemplo); tente de novo.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "internal_error",
        "message": "Falha inesperada."
      }
    }
  }
}

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi