> ## Documentation Index > Fetch the complete documentation index at: https://docs.blu.direct/llms.txt > Use this file to discover all available pages before exploring further. # Consultar uma mensagem ## OpenAPI ````yaml /api/openapi.yaml get /v1/chats/{chat}/messages/{message} openapi: 3.1.0 info: title: API do blü version: '2026-10-11' summary: >- Envie e receba mensagens no WhatsApp, faça campanhas e gerencie agentes de IA. description: > A API do blü segue o modelo REST. Ela usa URLs previsíveis e orientadas a recursos, recebe corpos de requisição em JSON, devolve respostas em JSON e usa códigos de status, autenticação e métodos HTTP padrão. ## Vocabulário A API usa os mesmos termos do WhatsApp. Um **número** é um número de WhatsApp conectado à sua conta. Um **contato** é uma pessoa, única por conta e por `wa_id`. Uma **conversa** liga um dos seus números a um `wa_id` e reúne as **mensagens** trocadas entre eles. Uma **campanha** envia uma mensagem para vários contatos. ## Tipos de plataforma Os números usam a API do WhatsApp Cloud, da Meta, e são conectados no painel do blü. O campo `capabilities` do número informa o que ele permite, e a API devolve um `whatsapp_error` com um `code` específico quando a requisição não segue uma regra. ## Convenções - **Ids** são opacos e começam com um prefixo do tipo de objeto, como `pn_`, `chat_` ou `msg_`. - Todo objeto tem `id`, `object` e `created` (em segundos Unix). - `POST` cria e atualiza; `DELETE` exclui. Ações são verbos no recurso, como `POST /v1/broadcasts/{id}/send`. - **Listas** são paginadas por cursor com `limit`, `starting_after` e `ending_before`, e devolvem um objeto de lista com `has_more`. - **Expansão**: campos que guardam um id podem ser trocados pelo objeto completo com `expand[]`, como `expand[]=contact` em uma conversa. - **Idempotência**: envie o cabeçalho `Idempotency-Key` em qualquer `POST` para repetir a requisição com segurança. As chaves ficam guardadas por 24 horas. - **Versionamento**: o cabeçalho `Blu-Version` escolhe a versão da API. Sem ele, vale a versão fixada na sua conta no primeiro uso. - **Metadados**: contatos, conversas, mensagens, campanhas e endpoints de webhook aceitam até 50 pares de chave e valor seus, em texto. contact: name: blü url: https://blu.direct/api servers: - url: https://api.blu.direct security: - secretKey: [] tags: - name: Conta description: A conta à qual sua chave de API pertence. - name: Números description: Números de WhatsApp conectados à sua conta e a conexão deles. - name: Contatos description: Pessoas com quem você conversa, únicas por conta e por `wa_id`. - name: Conversas description: Conversas entre um dos seus números e um `wa_id`. - name: Mensagens description: Mensagens enviadas e recebidas em uma conversa. - name: Mídia description: Arquivos usados em mensagens, campanhas e modelos. - name: Etiquetas description: Etiquetas que organizam contatos e definem o público de campanhas. - name: Modelos de mensagem description: >- Mensagens reutilizáveis. Obrigatórias em números `cloud_api` fora da janela de atendimento. - name: Campanhas description: Uma mensagem enviada para vários contatos, com intervalos entre os envios. - name: Agentes description: Agentes de IA que respondem às conversas. - name: Eventos description: Acontecimentos na sua conta, também enviados aos endpoints de webhook. - name: Endpoints de webhook description: URLs que recebem eventos. paths: /v1/chats/{chat}/messages/{message}: parameters: - $ref: '#/components/parameters/ChatPath' - $ref: '#/components/parameters/MessagePath' - $ref: '#/components/parameters/BluVersion' get: tags: - Mensagens summary: Consultar uma mensagem operationId: getMessage parameters: - $ref: '#/components/parameters/Expand' responses: '200': description: A mensagem. content: application/json: schema: $ref: '#/components/schemas/Message' 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' components: parameters: ChatPath: name: chat in: path required: true schema: type: string pattern: ^chat_ MessagePath: name: message in: path required: true schema: type: string pattern: ^msg_ BluVersion: name: Blu-Version in: header description: A versão da API a usar. Por padrão, é a versão fixada na sua conta. schema: type: string examples: - '2026-10-11' Expand: name: expand[] in: query description: >- Campos a expandir em objetos completos, como `contact`, ou `data.contact` em listas. style: form explode: true schema: type: array items: type: string schemas: Message: allOf: - $ref: '#/components/schemas/MessageContent' - type: object required: - id - object - chat - direction - status - errors - context - broadcast - pricing - whatsapp_message_id - created - metadata properties: id: type: string pattern: ^msg_ examples: - msg_Zt4b object: type: string const: message chat: description: Expansível. anyOf: - type: string pattern: ^chat_ - $ref: '#/components/schemas/Chat' direction: $ref: '#/components/schemas/MessageDirection' status: $ref: '#/components/schemas/MessageStatus' errors: description: Por que a mensagem ficou como `failed`. Vazio nos outros casos. type: array items: $ref: '#/components/schemas/MessageError' context: anyOf: - $ref: '#/components/schemas/MessageContext' - type: 'null' broadcast: description: A campanha que enviou esta mensagem, se houver. Expansível. anyOf: - type: string pattern: ^bcast_ - $ref: '#/components/schemas/Broadcast' - type: 'null' pricing: anyOf: - $ref: '#/components/schemas/MessagePricing' - type: 'null' whatsapp_message_id: description: O id da mensagem no próprio WhatsApp. type: - string - 'null' created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' MessageContent: description: >- O conteúdo da mensagem. `type` indica o objeto que guarda o conteúdo, como na API do WhatsApp Cloud. oneOf: - $ref: '#/components/schemas/TextMessage' - $ref: '#/components/schemas/ImageMessage' - $ref: '#/components/schemas/VideoMessage' - $ref: '#/components/schemas/AudioMessage' - $ref: '#/components/schemas/DocumentMessage' - $ref: '#/components/schemas/StickerMessage' - $ref: '#/components/schemas/LocationMessage' - $ref: '#/components/schemas/ContactsMessage' - $ref: '#/components/schemas/ReactionMessage' - $ref: '#/components/schemas/InteractiveMessage' - $ref: '#/components/schemas/TemplateMessage' - $ref: '#/components/schemas/PollMessage' discriminator: propertyName: type mapping: text: '#/components/schemas/TextMessage' image: '#/components/schemas/ImageMessage' video: '#/components/schemas/VideoMessage' audio: '#/components/schemas/AudioMessage' document: '#/components/schemas/DocumentMessage' sticker: '#/components/schemas/StickerMessage' location: '#/components/schemas/LocationMessage' contacts: '#/components/schemas/ContactsMessage' reaction: '#/components/schemas/ReactionMessage' interactive: '#/components/schemas/InteractiveMessage' template: '#/components/schemas/TemplateMessage' poll: '#/components/schemas/PollMessage' Chat: type: object required: - id - object - phone_number - wa_id - type - name - contact - last_message_at - service_window_expires_at - created - metadata properties: id: type: string pattern: ^chat_ examples: - chat_Q8x2 object: type: string const: chat phone_number: description: O seu número nesta conversa. Expansível. anyOf: - type: string pattern: ^pn_ - $ref: '#/components/schemas/PhoneNumber' wa_id: description: A outra parte. Ids de grupo terminam em `@g.us`. type: string examples: - '5511988887777' type: type: string enum: - individual - group name: description: >- O nome do contato, o nome de perfil no WhatsApp ou o assunto do grupo. type: - string - 'null' contact: description: O contato deste `wa_id`. Nulo em grupos. Expansível. anyOf: - type: string pattern: ^cont_ - $ref: '#/components/schemas/Contact' - type: 'null' last_message_at: type: - integer - 'null' service_window_expires_at: description: | Quando mensagens livres deixam de ser permitidas, 24 horas após a última mensagem do contato. Nulo quando a janela está fechada. type: - integer - 'null' created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' MessageDirection: type: string enum: - inbound - outbound MessageStatus: description: > Mensagens enviadas passam de `accepted` para `sent`, `delivered` e `read`, ou terminam como `failed`. Mensagens recebidas ficam como `received`. type: string enum: - accepted - sent - delivered - read - failed - received MessageError: type: object required: - code - message properties: code: type: string examples: - not_on_whatsapp message: type: string MessageContext: type: object additionalProperties: false required: - message_id properties: message_id: description: A mensagem que está sendo respondida. type: string pattern: ^msg_ Broadcast: type: object required: - id - object - phone_number - status - message - recipients - throttle - stats - estimated_cost - failure_reason - sent_at - completed_at - created - metadata properties: id: type: string pattern: ^bcast_ examples: - bcast_9c2M object: type: string const: broadcast phone_number: description: Expansível. anyOf: - type: string pattern: ^pn_ - $ref: '#/components/schemas/PhoneNumber' status: $ref: '#/components/schemas/BroadcastStatus' message: $ref: '#/components/schemas/BroadcastMessage' recipients: $ref: '#/components/schemas/BroadcastRecipients' throttle: $ref: '#/components/schemas/BroadcastThrottle' stats: $ref: '#/components/schemas/BroadcastStats' estimated_cost: description: >- O valor que a Meta vai cobrar. Nulo enquanto a estimativa não está disponível. anyOf: - $ref: '#/components/schemas/Money' - type: 'null' failure_reason: description: Por que uma campanha `failed` parou. type: - string - 'null' sent_at: type: - integer - 'null' completed_at: type: - integer - 'null' created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' MessagePricing: description: >- Como a Meta cobra a mensagem. Preenchido em mensagens enviadas; nulo nas recebidas. type: object required: - billable - category properties: billable: type: boolean category: type: string enum: - marketing - utility - authentication - service Timestamp: description: Horário Unix em segundos. type: integer examples: - 1760190012 Metadata: description: >- Até 50 pares de chave e valor seus. Chaves com até 40 caracteres e valores com até 500. type: object maxProperties: 50 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' TextMessage: type: object required: - type - text properties: type: type: string const: text text: type: object additionalProperties: false required: - body properties: body: type: string maxLength: 4096 preview_url: description: Mostra uma prévia do primeiro link em `body`. type: boolean default: false ImageMessage: type: object required: - type - image properties: type: type: string const: image image: allOf: - $ref: '#/components/schemas/MediaSource' - type: object properties: caption: type: string maxLength: 1024 view_once: description: Exige `capabilities.view_once`. type: boolean default: false VideoMessage: type: object required: - type - video properties: type: type: string const: video video: allOf: - $ref: '#/components/schemas/MediaSource' - type: object properties: caption: type: string maxLength: 1024 view_once: description: Exige `capabilities.view_once`. type: boolean default: false AudioMessage: type: object required: - type - audio properties: type: type: string const: audio audio: $ref: '#/components/schemas/MediaSource' DocumentMessage: type: object required: - type - document properties: type: type: string const: document document: allOf: - $ref: '#/components/schemas/MediaSource' - type: object properties: caption: type: string maxLength: 1024 filename: type: string StickerMessage: type: object required: - type - sticker properties: type: type: string const: sticker sticker: $ref: '#/components/schemas/MediaSource' LocationMessage: type: object required: - type - location properties: type: type: string const: location location: type: object additionalProperties: false required: - latitude - longitude properties: latitude: type: number longitude: type: number name: type: string address: type: string ContactsMessage: description: Compartilha cartões de contato. type: object required: - type - contacts properties: type: type: string const: contacts contacts: type: array minItems: 1 items: type: object required: - name properties: name: type: object required: - formatted_name properties: formatted_name: type: string first_name: type: string last_name: type: string phones: type: array items: type: object properties: phone: type: string wa_id: type: string type: type: string examples: - CELL ReactionMessage: type: object required: - type - reaction properties: type: type: string const: reaction reaction: type: object additionalProperties: false required: - message_id - emoji properties: message_id: description: A mensagem que recebe a reação. type: string pattern: ^msg_ emoji: description: Um texto vazio remove a reação. type: string InteractiveMessage: description: > Uma mensagem com botões ou lista. `button` mostra até 3 botões de resposta, `cta_url` mostra um botão de link e `list` mostra um menu de opções. type: object required: - type - interactive properties: type: type: string const: interactive interactive: type: object required: - type - body - action properties: type: type: string enum: - button - cta_url - list header: type: object properties: type: type: string enum: - text - image - video - document text: type: string maxLength: 60 image: $ref: '#/components/schemas/MediaSource' video: $ref: '#/components/schemas/MediaSource' document: $ref: '#/components/schemas/MediaSource' body: type: object required: - text properties: text: type: string maxLength: 1024 footer: type: object required: - text properties: text: type: string maxLength: 60 action: type: object properties: buttons: description: Para `button`. type: array maxItems: 3 items: type: object required: - id - title properties: id: description: Devolvido na resposta quando o contato toca no botão. type: string maxLength: 256 title: type: string maxLength: 20 url: description: Para `cta_url`. type: object required: - display_text - url properties: display_text: type: string maxLength: 20 url: type: string format: uri list: description: Para `list`. type: object required: - button - sections properties: button: description: O texto do botão que abre a lista. type: string maxLength: 20 sections: type: array minItems: 1 maxItems: 10 items: type: object required: - rows properties: title: type: string maxLength: 24 rows: type: array minItems: 1 items: type: object required: - id - title properties: id: type: string maxLength: 200 title: type: string maxLength: 24 description: type: string maxLength: 72 TemplateMessage: description: | Envia um modelo de mensagem. O modelo precisa estar `approved`; é a única forma de falar com um contato fora da janela de atendimento. type: object required: - type - template properties: type: type: string const: template template: type: object additionalProperties: false required: - id properties: id: type: string pattern: ^tmpl_ parameters: description: Valores para os parâmetros nomeados do modelo, como `{{name}}`. type: object additionalProperties: type: string PollMessage: description: Exige `capabilities.polls`. type: object required: - type - poll properties: type: type: string const: poll poll: type: object additionalProperties: false required: - name - options properties: name: description: A pergunta. type: string maxLength: 255 options: type: array minItems: 2 maxItems: 12 items: type: string maxLength: 100 PhoneNumber: type: object required: - id - object - name - display_phone_number - wa_id - verified_name - platform_type - status - quality_rating - capabilities - agent - created properties: id: type: string pattern: ^pn_ examples: - pn_8f3aK1 object: type: string const: phone_number name: description: O nome que você deu ao número. type: string display_phone_number: type: - string - 'null' examples: - +55 11 99999-8888 wa_id: description: Nulo até o número ser conectado pela primeira vez. type: - string - 'null' examples: - '5511999998888' verified_name: description: O nome comercial ou de perfil no WhatsApp. type: - string - 'null' platform_type: $ref: '#/components/schemas/PlatformType' status: $ref: '#/components/schemas/PhoneNumberStatus' quality_rating: description: >- A classificação de qualidade da Meta. Nula até a Meta classificar o número. type: - string - 'null' enum: - GREEN - YELLOW - RED - UNKNOWN - null capabilities: $ref: '#/components/schemas/PhoneNumberCapabilities' agent: description: O agente que responde às conversas deste número. Expansível. anyOf: - type: string pattern: ^agent_ - $ref: '#/components/schemas/Agent' - type: 'null' created: $ref: '#/components/schemas/Timestamp' Contact: type: object required: - id - object - wa_id - profile - labels - opted_out - opted_out_at - marketing_stopped - created - metadata properties: id: type: string pattern: ^cont_ examples: - cont_7Hk1 object: type: string const: contact wa_id: type: string examples: - '5511988887777' profile: $ref: '#/components/schemas/ContactProfile' labels: description: As etiquetas do contato. Expansível. type: array items: anyOf: - type: string pattern: ^lbl_ - $ref: '#/components/schemas/Label' opted_out: description: >- O contato pediu para não receber mensagens. As campanhas o pulam em todos os números. type: boolean opted_out_at: type: - integer - 'null' marketing_stopped: description: >- O contato bloqueou mensagens de marketing no WhatsApp. Campanhas de marketing o pulam. type: boolean created: $ref: '#/components/schemas/Timestamp' metadata: $ref: '#/components/schemas/Metadata' BroadcastStatus: type: string enum: - draft - sending - completed - failed BroadcastMessage: description: > A mensagem enviada a cada destinatário. Textos e legendas podem usar parâmetros nomeados, como `{{name}}`, preenchidos com os `parameters` de cada destinatário ou, no caso de contatos, com `profile.name` e `metadata`. Mensagens `reaction` não são permitidas em campanhas. allOf: - $ref: '#/components/schemas/MessageContent' BroadcastRecipients: description: Exatamente um entre `label`, `contacts` e `to`. type: object additionalProperties: false properties: label: description: Todos os contatos com esta etiqueta. type: string pattern: ^lbl_ contacts: type: array minItems: 1 items: type: string pattern: ^cont_ to: description: >- Números que não precisam ser contatos, cada um com os próprios parâmetros. type: array minItems: 1 items: type: object additionalProperties: false required: - phone properties: phone: description: Número no formato E.164 ou `wa_id`. type: string parameters: type: object additionalProperties: type: string oneOf: - required: - label - required: - contacts - required: - to BroadcastThrottle: description: Intervalos entre as mensagens, para proteger o número. type: object additionalProperties: false properties: delay_seconds: description: Espera entre duas mensagens. type: integer minimum: 1 batch_size: description: Mensagens enviadas antes de cada pausa. type: integer minimum: 1 pause_seconds: description: Duração da pausa depois de cada lote. type: integer minimum: 0 BroadcastStats: type: object required: - total - sent - delivered - read - failed - skipped properties: total: description: Destinatários que a campanha vai alcançar. type: integer sent: type: integer delivered: description: Só é informado quando `capabilities.delivery_receipts` é verdadeiro. type: integer read: description: Só é informado quando `capabilities.delivery_receipts` é verdadeiro. type: integer failed: type: integer skipped: description: >- Destinatários que não receberam a mensagem por não terem WhatsApp, terem pedido para não receber mensagens ou terem bloqueado marketing. type: integer Money: type: object required: - amount - currency properties: amount: description: Na menor unidade da moeda, como centavos. type: integer currency: description: Código ISO 4217, em minúsculas. type: string examples: - brl Error: type: object required: - type - message - request_id properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - whatsapp_error - rate_limit_error - api_error code: description: | Um texto curto que identifica o erro específico, quando houver. - `whatsapp_error`: `phone_number_disconnected`, `not_on_whatsapp`, `outside_service_window`, `template_not_approved`, `unsupported_for_platform_type`, `contact_opted_out`, `marketing_stopped`, `media_too_large`. - `invalid_request_error`: `parameter_missing`, `parameter_invalid`, `resource_missing`, `idempotency_key_reused`, `broadcast_not_draft`, `consent_required`, `plan_limit_reached`. type: string examples: - outside_service_window message: description: Uma mensagem legível para pessoas. type: string param: description: O parâmetro da requisição relacionado ao erro, se houver. type: string examples: - text.body doc_url: type: string format: uri request_id: type: string MediaSource: description: Um id de `media` vindo de `POST /v1/media` ou um `link` público. type: object properties: media: type: string pattern: ^media_ link: type: string format: uri oneOf: - required: - media - required: - link PlatformType: description: | A plataforma do número. Hoje, todos os números usam a API do WhatsApp Cloud, da Meta. type: string enum: - cloud_api PhoneNumberStatus: description: | `pending_link` nunca foi conectado. `connecting` está conectando ou reconectando. `connected` pode enviar e receber. `disconnected` foi desconectado e precisa ser conectado de novo. type: string enum: - pending_link - connecting - connected - disconnected PhoneNumberCapabilities: description: >- O que este número permite. Confira antes de usar recursos que mudam conforme o tipo de plataforma. type: object required: - chats - free_form_messages - polls - view_once - delivery_receipts properties: chats: description: Se as conversas e mensagens dele estão disponíveis pela API. type: boolean free_form_messages: description: >- `always` (sempre) ou `service_window` (só dentro da janela de atendimento de 24 horas após a última mensagem do contato). type: string enum: - always - service_window polls: type: boolean view_once: type: boolean delivery_receipts: description: Se as mensagens informam `delivered` e `read`. type: boolean Agent: type: object required: - id - object - name - instructions - faq - created properties: id: type: string pattern: ^agent_ examples: - agent_12Rf object: type: string const: agent name: type: string instructions: description: Como o agente deve se comportar e o que ele sabe. type: string faq: type: array items: $ref: '#/components/schemas/AgentFaqEntry' created: $ref: '#/components/schemas/Timestamp' ContactProfile: type: object additionalProperties: false properties: name: type: - string - 'null' maxLength: 200 Label: type: object required: - id - object - name - color - created properties: id: type: string pattern: ^lbl_ examples: - lbl_vip object: type: string const: label name: type: string color: $ref: '#/components/schemas/LabelColor' created: $ref: '#/components/schemas/Timestamp' AgentFaqEntry: type: object additionalProperties: false required: - question - answer properties: question: type: string answer: type: string LabelColor: description: Uma cor em hexadecimal. type: string pattern: ^#[0-9a-fA-F]{6}$ examples: - '#25D366' responses: Error: description: > A requisição falhou. Códigos de status: `400` requisição inválida, `401` chave de API inválida, `403` a chave não tem a permissão, `404` não encontrado, `409` conflito (como uma `Idempotency-Key` reutilizada com parâmetros diferentes), `422` uma regra do WhatsApp recusou a requisição, `429` limite de requisições atingido, `5xx` erro do lado do blü. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: RequestId: description: Identifica a requisição. Informe esse valor ao falar com o suporte. schema: type: string securitySchemes: secretKey: type: http scheme: bearer description: | Autentique com uma chave secreta (`sk_live_…`) ou uma chave restrita (`rk_live_…`) criada no painel. Chaves restritas só têm as permissões escolhidas na criação, como `messages:send`, `chats:read` ou `broadcasts:send`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.