> ## Documentation Index > Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Visão Geral de Mensagens > Como enviar mensagens pela API MessageFy - tipos suportados, estrutura do payload e exemplos práticos # Enviando Mensagens Todas as mensagens na MessageFy são enviadas através de um único endpoint: ``` POST /api/v1/message/SendMessage ``` O tipo de mensagem é determinado pelo campo `content.type` no corpo da requisição. Isso permite uma interface unificada para todos os tipos de conteúdo suportados. ## Estrutura do Package Toda mensagem enviada é encapsulada em um **Package** -- o envelope padrão da API. O Package contém o identificador do canal e o conteúdo polimórfico: ```json theme={null} { "channelId": "uuid-do-canal", "correlationId": "seu-id-de-rastreamento-opcional", "content": { "type": "TEXT", "to": { "type": "WHATSAPP", "number": "5511999999999" }, "text": "Ola, mundo!" } } ``` Identificador do canal pelo qual a mensagem será enviada. O canal deve estar ativo e vinculado a sua conta. ID de rastreamento definido pelo cliente. Útil para correlacionar a requisição com eventos recebidos via webhook. Conteúdo polimórfico da mensagem. O campo `type` determina qual tipo de mensagem será enviado. ## Resposta Ao enviar uma mensagem com sucesso, a API retorna um `packageId` que identifica unicamente aquele envio: ```json theme={null} { "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` Guarde o `packageId` retornado. Ele será referenciado nos eventos de webhook como `MESSAGE_SENT`, `MESSAGE_DELIVERED` e `MESSAGE_READ`, permitindo rastrear o ciclo de vida completo da mensagem.

Endereçamento (Address)

O campo `to` em todas as mensagens define o destinatário. O formato depende do tipo de canal. ### WhatsApp Para canais WhatsApp, você pode endereçar usando **número** ou **JID**: ```json Usando numero theme={null} { "type": "WHATSAPP", "number": "5511999999999" } ``` ```json Usando JID theme={null} { "type": "WHATSAPP", "jid": "5511999999999@s.whatsapp.net" } ``` ```json Grupo WhatsApp theme={null} { "type": "WHATSAPP", "jid": "120363402110764959@g.us" } ``` Tipo do endereço. Valores: `WHATSAPP`, `EMAIL`, `SMS`. Número de telefone no formato internacional (código do país + DDD + número), sem `+` ou espaços. Exemplo: `5511999999999`. JID (Jabber ID) do WhatsApp. Para contatos individuais: `número@s.whatsapp.net`. Para grupos: `id@g.us`. LID (LinkedID) do WhatsApp. Identificador alternativo que o WhatsApp pode usar no lugar do JID em endereços recebidos. Presente principalmente em mensagens recebidas. Nome do contato (opcional, usado para exibição). **Prefira sempre o `jid`.** Em canais `whatsapp-web` (provider whatsmeow), o envio usa exclusivamente o campo `jid` -- o `number` sozinho **não** é suficiente. O `number` como alternativa ao `jid` funciona apenas em canais do WhatsApp oficial (WABA). Para mensagens em **grupos**, use sempre o `jid` com sufixo `@g.us`. ### Outros tipos de endereço Além de `WHATSAPP`, o campo `type` do endereço aceita: ```json EMAIL theme={null} { "type": "EMAIL", "email": "cliente@exemplo.com", "name": "Cliente" } ``` ```json SMS theme={null} { "type": "SMS", "number": "5511999999999" } ``` ## Campos Comuns Todos os tipos de mensagem herdam estes campos opcionais: Estratégia de entrega, enviada como **número**: `0` = DEFAULT, `10` = TRANSACIONAL, `20` = MARKETING. Afeta a priorização e roteamento interno. Enviar o nome como string (ex.: `"TRANSACIONAL"`) causa erro `400` de desserialização. Prioridade da mensagem, de 1 (mais alta) a 5 (mais baixa). Valor 0 indica prioridade padrão. Data/hora limite para entrega da mensagem. Mensagens não entregues até o prazo serão descartadas. Marca a mensagem como encaminhada. Também é preenchido nas mensagens recebidas para indicar conteúdo repassado. Mensagem citada (resposta). Permite enviar a mensagem como resposta a uma mensagem anterior. Marca a mensagem como vinda de um canal/newsletter do WhatsApp (JID @newsletter). Marca a mensagem como vinda de uma lista de transmissão (JID @broadcast). Inclui status/stories. Marca a mensagem como vinda de um grupo em modo somente-admin (announce). Marca a mensagem como vinda do grupo "Avisos" de uma comunidade do WhatsApp. ### Responder a uma mensagem (quotedMessage) Para enviar uma mensagem como resposta a outra: ```json theme={null} { "channelId": "uuid-do-canal", "content": { "type": "TEXT", "to": { "type": "WHATSAPP", "number": "5511999999999" }, "text": "Sim, confirmo o recebimento!", "quotedMessage": { "messageId": "20CFBA298FAB68AA75D3B369EDB5C805", "participant": "5511999999999@s.whatsapp.net", "body": "Voce recebeu o documento?", "type": "TEXT" } } } ``` Em **grupos**, o `participant` deve ser o **LID** do autor da mensagem citada: ```json theme={null} { "channelId": "uuid-do-canal", "content": { "type": "TEXT", "to": { "type": "WHATSAPP", "jid": "120363402110764959@g.us" }, "text": "Confirmado!", "quotedMessage": { "messageId": "3EB0BC78317D829D0289C0", "participant": "252780317044848@lid" } } } ``` A API **não valida** o `participant`. Se o valor estiver errado (por exemplo, JID em vez de LID em um grupo), a requisição retorna `200 OK` e a mensagem é **entregue sem a citação**, sem nenhum erro ou aviso. Guarde o `content.from.lid` recebido nos webhooks para usá-lo como `participant` ao responder mensagens de grupo. ID da mensagem original que está sendo citada. Autor da mensagem original que está sendo citada. **Em grupos, use o LID do autor (ex.: `252780317044848@lid`) -- não use o JID**, ou a mensagem será entregue sem a citação. Em conversas individuais, use o JID do autor (ex.: `5511999999999@s.whatsapp.net`). O LID do autor chega nos webhooks de mensagem recebida em `content.from.lid`. Texto ou descrição do conteúdo da mensagem original. Tipo da mensagem original (`TEXT`, `IMAGE`, etc.). Miniatura (base64) da mensagem original, quando disponível. `true` quando a citação é uma resposta a um status (story). ## Tipos de Mensagem A tabela abaixo lista todos os tipos de mensagem suportados: | Tipo | Discriminador | Descrição | | ----------------------------------------------------- | ------------------ | -------------------------------------------------- | | [Texto](/mensagens/texto) | `TEXT` | Mensagem de texto simples | | [Template](/mensagens/template) | `TEMPLATE` | Template WhatsApp pré-aprovado referenciado por id | | [Imagem](/mensagens/imagem) | `IMAGE` | Imagem com legenda opcional | | [Documento](/mensagens/documento) | `DOCUMENT` | Arquivo/documento | | [Áudio](/mensagens/audio) | `AUDIO` | Mensagem de áudio | | [Vídeo](/mensagens/video) | `VIDEO` | Vídeo com legenda opcional | | [Sticker](/mensagens/sticker) | `STICKER` | Figurinha/adesivo | | [Localização](/mensagens/localizacao) | `LOCATION` | Localização no mapa | | [Localização ao Vivo](/mensagens/localizacao-ao-vivo) | `LIVE_LOCATION` | Compartilhamento de localização em tempo real | | [Contato](/mensagens/contato) | `CONTACT_MESSAGE` | Cartão de contato | | [Lista de Contatos](/mensagens/lista-contatos) | `CONTACTS_MESSAGE` | Múltiplos cartões de contato | | [Reação](/mensagens/reacao) | `REACTION` | Emoji de reação a uma mensagem | | [Pedido](/mensagens/pedido) | `ORDER` | Mensagem de pedido/compra | | [Interativo](/mensagens/interativo) | `INTERACTIVE` | Mensagem com botões ou listas | | [Endereço](/mensagens/endereco) | `ADDRESS_MESSAGE` | Solicitação/coleta de endereço | ## Operações sobre Mensagens Além do envio, a API permite operar sobre mensagens já enviadas: | Operação | Endpoint | Descrição | | ----------------------------- | -------------------------------------- | ------------------------------ | | [Deletar](/mensagens/deletar) | `DELETE /api/v1/message/DeleteMessage` | Remove uma mensagem para todos | | [Editar](/mensagens/editar) | `PUT /api/v1/message/EditMessage` | Edita o texto de uma mensagem | | [Buscar](/mensagens/buscar) | `GET /api/v1/message/SearchMessage` | Busca mensagens no event store | ## Exemplo Completo ```bash cURL theme={null} curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \ -H "Content-Type: application/json" \ -H "X-API-KEY: sua-api-key-aqui" \ -d '{ "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "correlationId": "pedido-12345", "content": { "type": "TEXT", "to": { "type": "WHATSAPP", "number": "5511999999999" }, "text": "Seu pedido #12345 foi confirmado!", "deliveryStrategy": 10, "priority": 1 } }' ``` ```python Python theme={null} import requests response = requests.post( "https://api-dev.messagefy.io/api/v1/message/SendMessage", headers={ "Content-Type": "application/json", "X-API-KEY": "sua-api-key-aqui" }, json={ "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "correlationId": "pedido-12345", "content": { "type": "TEXT", "to": { "type": "WHATSAPP", "number": "5511999999999" }, "text": "Seu pedido #12345 foi confirmado!", "deliveryStrategy": 10, "priority": 1 } } ) print(response.json()) ``` ```javascript Node.js theme={null} const response = await fetch( "https://api-dev.messagefy.io/api/v1/message/SendMessage", { method: "POST", headers: { "Content-Type": "application/json", "X-API-KEY": "sua-api-key-aqui", }, body: JSON.stringify({ channelId: "3fa85f64-5717-4562-b3fc-2c963f66afa6", correlationId: "pedido-12345", content: { type: "TEXT", to: { type: "WHATSAPP", number: "5511999999999", }, text: "Seu pedido #12345 foi confirmado!", deliveryStrategy: 10, priority: 1, }, }), } ); const data = await response.json(); console.log(data); ``` Resposta: ```json theme={null} { "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` *** ## Ciclo de Vida da Mensagem Após o envio, cada mensagem passa por uma sequência de status que você pode acompanhar via [webhooks](/recebendo-eventos). O diagrama abaixo mostra o fluxo completo: ``` SendMessage (sua aplicacao) | v MESSAGE_SENT (aceita pelo WhatsApp) | v MESSAGE_DELIVERED (entregue no dispositivo) | v MESSAGE_READ (lida pelo destinatario) | +--> MESSAGE_PLAYED (audio/video reproduzido) | +--> MESSAGE_EDITED (mensagem editada) | +--> MESSAGE_DELETED (mensagem apagada) ``` Implemente um sistema de rastreamento de status usando o `messageId` como chave. Atualize o status da mensagem a cada webhook recebido para ter visibilidade completa do ciclo de vida de cada mensagem enviada. ### MESSAGE\_SENT Enviado quando a mensagem é aceita pelo servidor do WhatsApp. Confirma que a mensagem saiu do MessageFy e está a caminho do destinatário. ```json theme={null} { "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": "pedido-12345", "content": { "type": "MESSAGE_SENT", "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "messageId": "3EB0A1B2C3D4E5F6", "chatId": "5511999887766@s.whatsapp.net", "jid": "5511999887766@s.whatsapp.net", "lid": "271283019378755@lid" } } ``` | Campo | Tipo | Descrição | | ----------- | -------- | -------------------------------------- | | `packageId` | `string` | ID do pacote enviado originalmente | | `messageId` | `string` | ID da mensagem atribuído pelo WhatsApp | | `chatId` | `string` | JID da conversa | | `jid` | `string` | JID do destino (quando conhecido) | | `lid` | `string` | LID do destino (quando conhecido) | O `messageId` retornado neste webhook é o identificador definitivo da mensagem no WhatsApp. Use-o para rastrear os status subsequentes (entrega, leitura, etc.). ### MESSAGE\_DELIVERED Enviado quando a mensagem é entregue no dispositivo do destinatário (ticks cinzas duplos). ```json theme={null} { "packageId": "0192f4b1-9c2a-7d3e-8f01-2c963f66afa6", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "MESSAGE_DELIVERED", "messageIds": [ "3EB0A1B2C3D4E5F6", "3EB0F6E5D4C3B2A1" ], "chatId": "5511999887766@s.whatsapp.net", "jid": "5511999887766@s.whatsapp.net", "lid": "271283019378755@lid", "isHistoryEvent": false } } ``` | Campo | Tipo | Descrição | | ---------------- | ---------- | --------------------------------------------------------- | | `messageIds` | `string[]` | Lista de IDs das mensagens entregues | | `chatId` | `string` | JID da conversa (quando conhecido) | | `jid` | `string` | JID de quem emitiu o recibo (quando conhecido) | | `lid` | `string` | LID de quem emitiu o recibo (quando conhecido) | | `isHistoryEvent` | `boolean` | `true` quando o recibo veio de sincronização de histórico | Múltiplas mensagens podem ser confirmadas como entregues em um único webhook. Isso acontece quando o destinatário fica online e recebe várias mensagens de uma vez. ### MESSAGE\_READ Enviado quando o destinatário lê a mensagem (ticks azuis). ```json theme={null} { "packageId": "0192f4b2-1a3c-7e4d-9012-3d074f77bfb7", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "MESSAGE_READ", "messageIds": [ "3EB0A1B2C3D4E5F6", "3EB0F6E5D4C3B2A1" ], "chatId": "5511999887766@s.whatsapp.net", "jid": "5511999887766@s.whatsapp.net", "lid": "271283019378755@lid", "isHistoryEvent": false } } ``` | Campo | Tipo | Descrição | | ---------------- | ---------- | --------------------------------------------------------- | | `messageIds` | `string[]` | Lista de IDs das mensagens lidas | | `chatId` | `string` | JID da conversa (quando conhecido) | | `jid` | `string` | JID de quem emitiu o recibo (quando conhecido) | | `lid` | `string` | LID de quem emitiu o recibo (quando conhecido) | | `isHistoryEvent` | `boolean` | `true` quando o recibo veio de sincronização de histórico | Se o destinatário desativou a confirmação de leitura nas configurações de privacidade do WhatsApp, este webhook **não** será enviado. ### MESSAGE\_PLAYED Enviado quando o destinatário reproduz uma mensagem de áudio ou vídeo. ```json theme={null} { "packageId": "0192f4b3-2b4d-7f5e-a123-4e185088c0c8", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "MESSAGE_PLAYED", "messageIds": [ "3EB0A1B2C3D4E5F6" ], "chatId": "5511999887766@s.whatsapp.net", "jid": "5511999887766@s.whatsapp.net", "lid": "271283019378755@lid", "isHistoryEvent": false } } ``` | Campo | Tipo | Descrição | | ---------------- | ---------- | --------------------------------------------------------- | | `messageIds` | `string[]` | Lista de IDs das mensagens reproduzidas | | `chatId` | `string` | JID da conversa (quando conhecido) | | `jid` | `string` | JID de quem emitiu o recibo (quando conhecido) | | `lid` | `string` | LID de quem emitiu o recibo (quando conhecido) | | `isHistoryEvent` | `boolean` | `true` quando o recibo veio de sincronização de histórico | *** ## Recebendo Mensagens Quando uma mensagem chega no WhatsApp conectado ao seu canal, o MessageFy envia um webhook para a URL configurada. O campo `content.type` indica o tipo da mensagem recebida. ### Estrutura geral Toda mensagem recebida chega dentro do mesmo envelope **Package**. O envelope carrega os identificadores de rastreamento e o `content` polimórfico, cujo `type` indica o tipo da mensagem. Os endereços em `from`/`to` seguem o mesmo formato polimórfico do envio (`type` + campos do canal): ```json theme={null} { "packageId": "0192f4a0-8b12-7c34-9d56-2c963f66afa6", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "TEXT", "text": "Ola! Gostaria de saber mais sobre o produto.", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Meu Canal" }, "messageId": "3EB0A1B2C3D4E5F6", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "isStatusMessage": false, "isHistoryMessage": false, "timestamp": "2025-04-14T10:30:00Z" }, "timestamp": "2025-04-14T10:30:00.100Z", "providerMetadata": null } ``` #### Campos do envelope | Campo | Tipo | Descrição | | ------------------ | ------------------- | ----------------------------------------------------------------------------------- | | `packageId` | `string` (UUID) | Identificador do pacote/webhook | | `channelId` | `string` (UUID) | Canal que recebeu a mensagem | | `correlationId` | `string` \| `null` | ID de rastreamento definido pelo cliente; `null` em mensagens recebidas espontâneas | | `timestamp` | `string` (ISO 8601) | Momento em que o webhook foi gerado (raiz, distinto de `content.timestamp`) | | `providerMetadata` | `object` \| `null` | Metadados adicionais do provedor | | `echoMessage` | `boolean` \| `null` | `true` quando é uma mensagem ecoada de volta ao remetente | | `content` | `object` | Conteúdo polimórfico da mensagem | #### Campos comuns do `content` | Campo | Tipo | Descrição | | -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | `type` | `string` | Tipo da mensagem (ver tabela abaixo) | | `from` | `object` | Endereço do remetente (`type` + `jid`/`lid`/`number`/`name`) | | `to` | `object` | Endereço do destinatário/conversa (`type` + `jid`/`lid`/`number`/`name`) | | `messageId` | `string` | Identificador único da mensagem | | `isFromMe` | `boolean` | `true` se a mensagem foi enviada pelo próprio canal | | `isGroupMessage` | `boolean` | `true` se a mensagem é de um grupo | | `isForwarded` | `boolean` | `true` se a mensagem foi encaminhada | | `isStatusMessage` | `boolean` | `true` se a mensagem é um status (story) | | `isHistoryMessage` | `boolean` | `true` se a mensagem veio de sincronização de histórico | | `isNewsletter` | `boolean` | `true` se a mensagem veio de um canal/newsletter do WhatsApp (JID `@newsletter`) | | `isBroadcast` | `boolean` | `true` se a mensagem veio de uma lista de transmissão (JID `@broadcast`). Inclui status/stories (`status@broadcast`) | | `isAnnounceGroup` | `boolean` | `true` se a mensagem veio de um grupo em modo somente-admin (announce) | | `isCommunityNotices` | `boolean` | `true` se a mensagem veio do grupo "Avisos" de uma comunidade do WhatsApp | | `quotedMessage` | `object` | Mensagem citada, quando é uma resposta (ver campos acima) | | `metaReferralAds` | `object` | Dados de anúncio Click-to-WhatsApp, quando a conversa iniciou por um anúncio | | `timestamp` | `string` (ISO 8601) | Data e hora da mensagem | O campo `isFromMe` é `true` quando a mensagem foi enviada pelo próprio dispositivo (por exemplo, se o usuário enviou uma mensagem pelo celular enquanto o canal está conectado). Isso permite sincronizar mensagens enviadas de outros dispositivos vinculados. Os endereços recebidos podem vir identificados por `jid` (Jabber ID) e/ou `lid` (LinkedID). Use `number` para o telefone e `name` para o nome de exibição, quando presentes. #### Anúncios Click-to-WhatsApp (metaReferralAds) Quando o usuário inicia a conversa clicando em um anúncio do Facebook/Instagram (Click-to-WhatsApp Ads), a primeira mensagem recebida traz o objeto `metaReferralAds` com o contexto do anúncio: | Campo | Tipo | Descrição | | -------------- | -------- | ---------------------------------- | | `sourceUrl` | `string` | URL de origem do anúncio | | `sourceType` | `string` | Tipo de origem (ex.: `ad`, `post`) | | `sourceId` | `string` | Identificador do anúncio | | `headline` | `string` | Título do anúncio | | `body` | `string` | Texto do anúncio | | `mediaType` | `string` | Tipo de mídia do anúncio | | `imageUrl` | `string` | URL da imagem do anúncio | | `videoUrl` | `string` | URL do vídeo do anúncio | | `thumbnailUrl` | `string` | URL da miniatura do anúncio | | `ctwaClid` | `string` | Click ID do Click-to-WhatsApp Ads | ### Tipos de mensagem recebida | Tipo | Descrição | | ----------------- | --------------------------------------- | | `TEXT` | Mensagem de texto | | `IMAGE` | Imagem | | `VIDEO` | Vídeo | | `AUDIO` | Áudio ou mensagem de voz | | `DOCUMENT` | Documento (PDF, Word, etc.) | | `STICKER` | Figurinha | | `LOCATION` | Localização | | `CONTACT_MESSAGE` | Cartão de contato | | `ORDER` | Pedido do catálogo do WhatsApp Business | | `REACTION` | Reação com emoji a uma mensagem | ### Exemplos por tipo ```json theme={null} { "packageId": "0192f4a0-8b12-7c34-9d56-2c963f66afa6", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "TEXT", "text": "Ola! Gostaria de saber mais sobre o produto.", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Loja Virtual" }, "messageId": "3EB0A1B2C3D4E5F6", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:30:00Z" } } ``` ```json theme={null} { "packageId": "0192f4a1-9c23-7d45-ae67-3d074f77bfb7", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "IMAGE", "mediaId": "media-abc123", "caption": "Foto do produto com defeito", "filename": "foto_produto.jpg", "mimetype": "image/jpeg", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" }, "messageId": "3EB0B2C3D4E5F6A1", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:32:00Z" } } ``` Imagens, vídeos, áudios, documentos e stickers não incluem o arquivo binário diretamente no webhook. Quando o download fica pronto, você recebe um evento separado `DOWNLOAD_AVAILABLE` com a URL em `externalDownloadUrl`. ```json theme={null} { "packageId": "0192f4a2-ad34-7e56-bf78-4e185088c0c8", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "VIDEO", "mediaId": "media-def456", "caption": "Video do problema relatado", "filename": "video_problema.mp4", "mimetype": "video/mp4", "isGIF": false, "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" }, "messageId": "3EB0B3C4D5E6F7A2", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:33:00Z" } } ``` Assim como imagens, o arquivo de vídeo não é incluído diretamente no webhook. Você receberá um evento `DOWNLOAD_AVAILABLE` com a URL para download. ```json theme={null} { "packageId": "0192f4a3-be45-7f67-c089-5f2961990d19", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "AUDIO", "mediaId": "media-ghi789", "filename": "audio.ogg", "mimetype": "audio/ogg; codecs=opus", "isPTT": true, "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" }, "messageId": "3EB0C3D4E5F6A1B2", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:35:00Z" } } ``` `isPTT` indica que o áudio é uma nota de voz push-to-talk (gravada no microfone), e não um arquivo de áudio enviado da galeria. ```json theme={null} { "packageId": "0192f4a4-cf56-7078-d19a-6039620a0e2a", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "DOCUMENT", "mediaId": "media-jkl012", "filename": "contrato-servico.pdf", "mimetype": "application/pdf", "caption": "Segue o contrato assinado", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Juridico" }, "messageId": "3EB0D4E5F6A1B2C3", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:40:00Z" } } ``` ```json theme={null} { "packageId": "0192f4a5-d067-7189-e2ab-7140631b1f3b", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "STICKER", "mediaId": "media-mno345", "filename": "sticker.webp", "mimetype": "image/webp", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" }, "messageId": "3EB0A1B2C3D4E5F7", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:55:00Z" } } ``` ```json theme={null} { "packageId": "0192f4a6-e178-729a-f3bc-8251742c204c", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "LOCATION", "latitude": -23.5505, "longitude": -46.6333, "name": "Avenida Paulista, 1000", "address": "Av. Paulista, 1000 - Bela Vista, Sao Paulo - SP", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Entregas" }, "messageId": "3EB0E5F6A1B2C3D4", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:45:00Z" } } ``` ```json theme={null} { "packageId": "0192f4a7-f289-73ab-04cd-9362853d315d", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "CONTACT_MESSAGE", "displayName": "Maria Santos", "vCard": "BEGIN:VCARD\nVERSION:3.0\nFN:Maria Santos\nTEL:+5521977665544\nEND:VCARD", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Vendas" }, "messageId": "3EB0F6A1B2C3D4E5", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T10:50:00Z" } } ``` ```json theme={null} { "packageId": "0192f4a8-039a-74bc-15de-a473964e426e", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "ORDER", "orderId": "1234567890", "itemCount": 2, "totalAmount1000": 13500, "totalCurrencyCode": "BRL", "text": "Gostaria de comprar estes itens", "items": [ { "name": "Camiseta Basica", "quantity": 1, "price": 8500, "currency": "BRL", "imageUrl": "https://storage.messagefy.io/media/item-abc" }, { "name": "Bone", "quantity": 1, "price": 5000, "currency": "BRL", "imageUrl": "https://storage.messagefy.io/media/item-def" } ], "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Loja Virtual" }, "messageId": "3EB0A7B8C9D0E1F2", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T11:00:00Z" } } ``` Os valores `totalAmount1000` e `items[].price` estão em **milésimos** da moeda: divida por 1000 para obter o valor real (ex.: `13500` = R\$ 13,50). As imagens dos itens (`imageUrl`) são URLs presigned do StorageFy que podem chegar via evento `DOWNLOAD_AVAILABLE`. ```json theme={null} { "packageId": "0192f4a9-14ab-75cd-26ef-b584075f537f", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "REACTION", "emoji": "👍", "targetMessageId": "3EB0A1B2C3D4E5F6", "targetFromMe": true, "targetParticipant": "5511999887766@s.whatsapp.net", "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" }, "messageId": "3EB0B8C9D0E1F2A3", "isFromMe": false, "isGroupMessage": false, "isForwarded": false, "timestamp": "2025-04-14T11:05:00Z" } } ``` ### Download de mídia (DOWNLOAD\_AVAILABLE) Para mensagens de mídia (imagem, vídeo, áudio, documento, sticker), o arquivo binário não é incluído diretamente no webhook. Quando o upload para o StorageFy é concluído, um evento separado `DOWNLOAD_AVAILABLE` é enviado com a URL de download em `externalDownloadUrl`: ```json theme={null} { "packageId": "0192f4aa-25bc-76de-37f0-c69518606480", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "correlationId": null, "content": { "type": "DOWNLOAD_AVAILABLE", "success": true, "messageId": "3EB0B2C3D4E5F6A1", "externalDownloadUrl": "https://storage.messagefy.io/media/abc123def456", "errorMessage": null, "isStatusMessage": false, "isHistoryDownload": false, "from": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net", "number": "5511999887766", "name": "Joao Silva" }, "to": { "type": "WHATSAPP", "jid": "5521988776655@s.whatsapp.net", "number": "5521988776655", "name": "Suporte" } } } ``` | Campo | Tipo | Descrição | | --------------------- | ------------------ | ------------------------------------------------------------------- | | `success` | `boolean` | `true` quando o download ficou disponível; `false` em caso de falha | | `messageId` | `string` | ID da mensagem original (mesmo ID do webhook de mensagem) | | `externalDownloadUrl` | `string` | URL para download do arquivo | | `errorMessage` | `string` \| `null` | Mensagem de erro quando `success` é `false` | | `isStatusMessage` | `boolean` | `true` se a mídia pertence a um status (story) | | `isHistoryDownload` | `boolean` | `true` se o download veio de sincronização de histórico | | `from` | `object` | Endereço do remetente da mídia original (quando conhecido) | | `to` | `object` | Endereço do destinatário da mídia original (quando conhecido) | A URL de download é temporária. Faça o download do arquivo assim que receber o webhook e armazene-o no seu próprio sistema de arquivos. Use o `messageId` para correlacionar o evento `DOWNLOAD_AVAILABLE` com a mensagem original recebida. Processe a mensagem primeiro e baixe a mídia em segundo plano.