# Oratrix API - Mensagens ## Status Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots. Este grupo e central para o **Wezapp Shots**, pois contem endpoints de envio direto por numero, com texto, arquivo, URL, voz, base64 e consulta por identificador de mensagem. ## Base URL ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID} ``` ## Autenticacao ```http Authorization: Bearer {token} ``` ## Endpoints do grupo Total documentado nesta parte: 7 endpoints. --- ## 1. Enviar mensagem via query params ```http GET /params/ ``` Nome na documentacao Oratrix: ```text SendMessageParams ``` Descricao: Enviar mensagem via query params. Util para integracoes simples sem body. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/params/ ``` Query params: | Parametro | Obrigatorio | Descricao | Exemplo | |---|---:|---|---| | body | Sim | Texto da mensagem | Ola! | | number | Sim | Numero do destinatario | 5511999999999 | | externalKey | Sim | Chave unica de controle | chave-001 | | bearertoken | Nao | Token de autenticacao, substitui header | token | | isClosed | Nao | Fechar ticket apos envio | false | Observacao para Wezapp Shots: Apesar de existir, o uso via GET nao e recomendado como padrao do Shots, porque pode expor conteudo em logs de servidor, historico e ferramentas intermediarias. Preferir POST com body. --- ## 2. Enviar mensagem de texto ```http POST / ``` Nome na documentacao Oratrix: ```text SendMessageAPIText ``` Descricao: Enviar mensagem de texto. Abre ou reutiliza ticket existente. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/ ``` Body JSON: ```json { "body": "A mensagem desejada", "number": "5511999999999", "externalKey": "chave-001", "isClosed": false } ``` Observacao para Wezapp Shots: Este endpoint e candidato forte para o envio unitario controlado pelo Wezapp, item a item ou em pequenos blocos via worker/fila. --- ## 3. Enviar arquivo via multipart/form-data ```http POST / ``` Nome na documentacao Oratrix: ```text SendMessageAPIFile ``` Descricao: Enviar arquivo via `multipart/form-data`, como imagem, documento ou video. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/ ``` Body: ```text Form Data ``` Campos: | Campo | Tipo | Obrigatorio | Descricao | |---|---|---:|---| | media | file | Sim | Arquivo enviado | | body | Texto | Nao | Texto da mensagem | | number | Texto | Sim | Numero do destinatario | | externalKey | Texto | Sim | Chave unica de controle | | isClosed | Boolean | Nao | Fechar ticket apos envio | --- ## 4. Enviar midia por URL publica ```http POST /url ``` Nome na documentacao Oratrix: ```text SendMessageAPIFileURL ``` Descricao: Enviar midia a partir de URL publica, como imagem ou documento. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/url ``` Body JSON: ```json { "mediaUrl": "https://exemplo.com/imagem.png", "body": "A mensagem desejada", "number": "5511999999999", "externalKey": "chave-001", "isClosed": false } ``` --- ## 5. Enviar audio/mensagem de voz ```http POST /voice ``` Nome na documentacao Oratrix: ```text SendMessageAPIVoice ``` Descricao: Enviar audio ou mensagem de voz via URL publica, como `.ogg` ou `.mp3`. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/voice ``` Body JSON: ```json { "audio": "https://exemplo.com/audio.ogg", "number": "5511999999999", "externalKey": "chave-001", "isClosed": false } ``` --- ## 6. Enviar arquivo em Base64 ```http POST /base64 ``` Nome na documentacao Oratrix: ```text SendMessageAPITextBase64 ``` Descricao: Enviar arquivo codificado em Base64 junto com mensagem. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/base64 ``` Body JSON: ```json { "body": "A mensagem desejada", "number": "5511999999999", "base64Data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...", "mimeType": "image/png", "fileName": "exemplo", "isClosed": false } ``` Observacao: O exemplo informado nao inclui `externalKey`. Validar se e aceito/obrigatorio neste endpoint. --- ## 7. Buscar mensagem por ID da Meta ```http GET /getMessageByMessageId ``` Nome na documentacao Oratrix: ```text GetMessageByMessageId ``` Descricao: Buscar mensagem pelo ID retornado pela Meta, como `wamid`. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/getMessageByMessageId ``` Query params: | Parametro | Obrigatorio | Descricao | Exemplo | |---|---:|---|---| | messageId | Sim | ID da mensagem | wamid.xxxxx | ## Mapeamento sugerido com Wezapp Shots | Wezapp Shots | Oratrix | |---|---| | `wezapp_dispatch_items.id` | `externalKey` sugerida | | `wezapp_contacts.phone` | `number` | | `wezapp_dispatch_logs.request_payload_json` | Payload enviado | | `wezapp_dispatch_logs.response_payload_json` | Resposta da API | | `wezapp_dispatch_items.external_message_id` | `wamid` ou ID retornado | | Consulta de status/mensagem | `/getMessageByMessageId` | ## ExternalKey recomendada Para rastreabilidade, o Wezapp deve gerar `externalKey` unica por item de disparo. Formato sugerido: ```text wezapp:{dispatch_job_id}:{dispatch_item_id} ``` Exemplo: ```text wezapp:1001:98231 ``` ## Decisao inicial recomendada para o Shots Para envio controlado e seguro, o endpoint `POST /` com body JSON deve ser avaliado como base do envio unitario por worker. O endpoint `GET /params/` deve ser evitado como padrao por expor mensagem, numero e chave em query string. ## Pendencias tecnicas para validar - Confirmar formato de resposta do `POST /`. - Confirmar se retorna `ticketId`, `messageId`, `wamid` ou outro identificador. - Confirmar comportamento de `externalKey` repetida. - Confirmar se `externalKey` e realmente unica no Oratrix. - Confirmar se `isClosed=false` abre/reutiliza ticket e se `true` fecha apos envio. - Confirmar limites de tamanho de texto. - Confirmar tipos e limites de arquivo no envio multipart. - Confirmar formatos aceitos em `/voice`. - Confirmar se `/base64` aceita `externalKey`. - Confirmar se `/getMessageByMessageId` funciona para todos os provedores ou apenas Meta/WABA. ## Regras recomendadas para o Wezapp Shots 1. Todo envio deve ter `externalKey` unica. 2. Todo envio deve registrar request e response. 3. Nao consumir shot apenas porque a requisicao foi montada; consumir conforme regra definida apos retorno. 4. Salvar identificador externo retornado quando existir. 5. Evitar GET com mensagem em query string como padrao. 6. Preferir fila interna do Wezapp para controle por contato. 7. Usar `getMessageByMessageId` para conciliacao quando houver `wamid`.