> ## Documentation Index > Fetch the complete documentation index at: https://docs.escrybe.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar ou consultar mensagens de WhatsApp ## OpenAPI ````yaml /openapi/escrybe.pt.yaml get /api/whatsapp/v1/get openapi: 3.1.0 info: title: API Escrybe version: 1.0.0 description: >- REST API da plataforma Escrybe — envie cartas físicas, cartas registradas, telegramas e e-Carta pelos Correios, dispare e-mails registrados juridicamente e envie mensagens de WhatsApp com carimbo de tempo certificado. ## Autenticação Toda conta possui um **`securityToken`** pessoal (disponível no painel em *Minhas configurações → Acesso a API*). Três produtos o utilizam de formas diferentes: | Produto | Esquema | Como | |---------|---------|------| | Cartas / Telegrama / e-Carta, E-mail Registrado, Recibos | Token de API | Envie `userSecurityToken` como parâmetro (query/body) ou `securityToken` como header | | WhatsApp | HTTP Basic | `Authorization: Basic base64(email:securityToken)` | > As rotas de **consulta** de carta e e-mail (`get`, `balance`, `download`, > `delete`) recebem o token como o primeiro segmento de **caminho** da URL — > ex.: `/api/v2/get/{securityToken}/{job_id}`. ## Envelopes de resposta A maioria dos endpoints responde com o envelope padrão `{"status": , "status_message": "...", "data": ...}` — isso cobre Cartas/Telegrama, E-mail Registrado e os endpoints de mensagens e remetentes de WhatsApp. Os endpoints de **modelos** de WhatsApp (e a sincronização de modelos) usam `{"code": , "status": "success|error", "message": "...", "data": ..., "request_id": "..."}`; o endpoint de logo usa o mesmo formato sem `request_id`. Consulte o schema de cada endpoint. Uma requisição aceita retorna HTTP `200` com o payload de sucesso; problemas de validação retornam `400`, credenciais inválidas `401` e acesso negado `403`. Métodos HTTP não suportados retornam `405`, tentativas repetidas de autenticação falhas retornam `429` e os endpoints de carta e e-mail retornam `503` durante janelas de manutenção. contact: name: Suporte Escrybe url: https://escrybe.com.br servers: - url: https://app.escrybe.com.br description: Produção - url: https://homolog.escrybe.com.br description: Homologação security: - securityTokenQuery: [] tags: - name: Letters & Telegram description: Crie e gerencie pedidos de carta, telegrama e e-Carta (Correios). - name: Account & Favorites description: Saldo da conta, contatos salvos e logo do remetente. - name: Registered E-mail description: Envie e acompanhe e-mails registrados juridicamente. - name: WhatsApp Messages description: Envie mensagens de WhatsApp e baixe atestações com carimbo de tempo. - name: WhatsApp Senders description: Gerencie números do WhatsApp Business (remetentes). - name: WhatsApp Templates description: Crie, sincronize e gerencie modelos de mensagem do WhatsApp. - name: Receipts description: Baixe recibos legais de qualquer pedido. paths: /api/whatsapp/v1/get: get: tags: - WhatsApp Messages summary: Listar ou consultar mensagens de WhatsApp operationId: listWhatsappMessages parameters: - name: message_id in: query schema: type: integer description: >- Quando informado, retorna uma única mensagem detalhada em vez da lista. - name: status in: query schema: type: string description: 'Filtra a fila pelo status (ex.: pending, sent).' - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: offset in: query schema: type: integer default: 0 responses: '200': description: Mensagens content: application/json: schema: allOf: - $ref: '#/components/schemas/WaMessagesEnvelope' - properties: data: oneOf: - type: object title: Modo lista properties: messages: type: array items: $ref: '#/components/schemas/WhatsappMessage' pagination: type: object properties: total: type: integer limit: type: integer offset: type: integer has_more: type: boolean - type: object title: Modo de mensagem única (message_id informado) properties: success: type: boolean message: $ref: '#/components/schemas/WhatsappMessage' '400': $ref: '#/components/responses/WaMsgBadRequest' '401': $ref: '#/components/responses/WaMsgUnauthorized' '403': $ref: '#/components/responses/WaMsgForbidden' '404': $ref: '#/components/responses/WaMsgNotFound' security: - basicAuth: [] components: schemas: WaMessagesEnvelope: type: object description: > Envelope padrão usado pelos endpoints de mensagens e remetentes de WhatsApp (mesmo formato dos envelopes de cartas e e-mail). properties: status: type: integer example: 200 status_message: type: string data: oneOf: - type: object - type: string - type: 'null' WhatsappMessage: type: object description: > Registro de mensagem retornado pelo endpoint get. `message_status` é o status do pedido (0 Processando pagamento · 1 Aguardando envio · 2 Créditos insuficientes · 5 Falhou/Cancelado); `status` é o status da fila de envio (outbox). properties: id: type: string visual_id: type: string message_sender_name: type: string description: Nome do remetente impresso na mensagem. sender_document: type: string recipient_name: type: string recipient_phone: type: string recipient_document: type: string body: type: string media_url: type: string nullable: true media_url_presigned: type: string nullable: true description: URL pré-assinada de 60 minutos. Apenas no modo de mensagem única. media_filename: type: string nullable: true is_template: type: string template_id: type: string nullable: true template_name: type: string nullable: true template_lang: type: string nullable: true template_variables: type: string nullable: true description: Mapa codificado em JSON. paymentMethod: type: string value: type: string message_status: type: string description: >- 0 Processando pagamento · 1 Aguardando envio · 2 Créditos insuficientes · 5 Falhou/Cancelado created_at: type: string team_member_id: type: string nullable: true team_name: type: string nullable: true outbox_id: type: string nullable: true status: type: string nullable: true description: >- Status da fila de envio (ex.: pending, processing, sent, cancelled, failed). attempt_count: type: string nullable: true last_error: type: string nullable: true sent_at: type: string nullable: true description: Quando o WhatsApp aceitou a mensagem para entrega. delivered_at: type: string nullable: true description: >- Quando a mensagem chegou ao aparelho do destinatário. Nulo até ser entregue. read_at: type: string nullable: true description: >- Quando o destinatário abriu a mensagem. Nulo se ele não tiver confirmação de leitura ativada. updated_at: type: string nullable: true sender_id: type: string nullable: true sender_name: type: string nullable: true description: Remetente do WhatsApp Business usado no envio. sender_phone: type: string nullable: true header_text: type: string nullable: true body_text: type: string nullable: true footer_text: type: string nullable: true header_format: type: string nullable: true variables_count: type: string nullable: true events: type: array description: >- Eventos de status (accepted, sent, delivered, read) em ordem cronológica. items: type: object properties: event_type: type: string created_at: type: string raw_payload: type: string responses: WaMsgBadRequest: description: Requisição inválida content: application/json: schema: $ref: '#/components/schemas/WaMessagesEnvelope' example: status: 400 status_message: Campos obrigatórios não preenchidos data: null WaMsgUnauthorized: description: Não autorizado — credenciais inválidas content: application/json: schema: $ref: '#/components/schemas/WaMessagesEnvelope' example: status: 401 status_message: Unauthorized - invalid credentials data: null WaMsgForbidden: description: Acesso negado content: application/json: schema: $ref: '#/components/schemas/WaMessagesEnvelope' WaMsgNotFound: description: Não encontrado content: application/json: schema: $ref: '#/components/schemas/WaMessagesEnvelope' securitySchemes: securityTokenQuery: type: apiKey in: query name: userSecurityToken description: >- Seu token de segurança, enviado como parâmetro `userSecurityToken` (query ou form). basicAuth: type: http scheme: basic description: >- HTTP Basic onde o usuário é o e-mail da conta e a senha é o token de segurança. ````