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:

{
  "channelId": "uuid-do-canal",
  "correlationId": "seu-id-de-rastreamento-opcional",
  "content": {
    "type": "TEXT",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "text": "Ola, mundo!"
  }
}

uuid

required

Identificador do canal pelo qual a mensagem será enviada. O canal deve estar ativo e vinculado a sua conta.

string

ID de rastreamento definido pelo cliente. Útil para correlacionar a requisição com eventos recebidos via webhook.

object

required

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:

{
  "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.

Para canais WhatsApp, você pode endereçar usando número ou JID:

{
  "type": "WHATSAPP",
  "number": "5511999999999"
}

{
  "type": "WHATSAPP",
  "jid": "5511999999999@s.whatsapp.net"
}

{
  "type": "WHATSAPP",
  "jid": "120363402110764959@g.us"
}

string

required

Tipo do endereço. Valores: WHATSAPP, EMAIL, SMS.

string

Número de telefone no formato internacional (código do país + DDD + número), sem + ou espaços. Exemplo: 5511999999999.

string

JID (Jabber ID) do WhatsApp. Para contatos individuais: número@s.whatsapp.net. Para grupos: id@g.us.

string

LID (LinkedID) do WhatsApp. Identificador alternativo que o WhatsApp pode usar no lugar do JID em endereços recebidos. Presente principalmente em mensagens recebidas.

string

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:

{
  "type": "EMAIL",
  "email": "cliente@exemplo.com",
  "name": "Cliente"
}

{
  "type": "SMS",
  "number": "5511999999999"
}

Campos Comuns

Todos os tipos de mensagem herdam estes campos opcionais:

integer

default:"0"

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.

byte

default:"0"

Prioridade da mensagem, de 1 (mais alta) a 5 (mais baixa). Valor 0 indica prioridade padrão.

datetime

Data/hora limite para entrega da mensagem. Mensagens não entregues até o prazo serão descartadas.

boolean

default:"false"

Marca a mensagem como encaminhada. Também é preenchido nas mensagens recebidas para indicar conteúdo repassado.

object

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).

boolean

default:"false"

Marca a mensagem como vinda de uma lista de transmissão (JID @broadcast). Inclui status/stories.

boolean

default:"false"

Marca a mensagem como vinda de um grupo em modo somente-admin (announce).

boolean

default:"false"

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:

{
  "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:

{
  "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.

string

ID da mensagem original que está sendo citada.

string

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.

string

Texto ou descrição do conteúdo da mensagem original.

string

Tipo da mensagem original (TEXT, IMAGE, etc.).

string

Miniatura (base64) da mensagem original, quando disponível.

boolean

default:"false"

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	`TEXT`	Mensagem de texto simples
Template	`TEMPLATE`	Template WhatsApp pré-aprovado referenciado por id
Imagem	`IMAGE`	Imagem com legenda opcional
Documento	`DOCUMENT`	Arquivo/documento
Áudio	`AUDIO`	Mensagem de áudio
Vídeo	`VIDEO`	Vídeo com legenda opcional
Sticker	`STICKER`	Figurinha/adesivo
Localização	`LOCATION`	Localização no mapa
Localização ao Vivo	`LIVE_LOCATION`	Compartilhamento de localização em tempo real
Contato	`CONTACT_MESSAGE`	Cartão de contato
Lista de Contatos	`CONTACTS_MESSAGE`	Múltiplos cartões de contato
Reação	`REACTION`	Emoji de reação a uma mensagem
Pedido	`ORDER`	Mensagem de pedido/compra
Interativo	`INTERACTIVE`	Mensagem com botões ou listas
Endereço	`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	`DELETE /api/v1/message/DeleteMessage`	Remove uma mensagem para todos
Editar	`PUT /api/v1/message/EditMessage`	Edita o texto de uma mensagem
Buscar	`GET /api/v1/message/SearchMessage`	Busca mensagens no event store

Exemplo Completo

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
    }
  }'

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())

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:

{
  "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. 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.

{
  "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).

{
  "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).

{
  "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.

{
  "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):

{
  "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

TEXT - Mensagem de texto

{
  "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"
  }
}

IMAGE - Imagem

{
  "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.

VIDEO - Vídeo

{
  "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.

AUDIO - Áudio

{
  "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.

DOCUMENT - Documento

{
  "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"
  }
}

STICKER - Figurinha

{
  "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"
  }
}

LOCATION - Localização

{
  "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"
  }
}

CONTACT_MESSAGE - Cartão de contato

{
  "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"
  }
}

ORDER - Pedido do catálogo

{
  "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.

REACTION - Reação

{
  "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:

{
  "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.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Visão Geral de Mensagens

Enviando Mensagens

Estrutura do Package

Resposta

Endereçamento (Address)

WhatsApp

Outros tipos de endereço

Campos Comuns

Responder a uma mensagem (quotedMessage)

Tipos de Mensagem

Operações sobre Mensagens

Exemplo Completo

Ciclo de Vida da Mensagem

MESSAGE_SENT

MESSAGE_DELIVERED

MESSAGE_READ

MESSAGE_PLAYED

Recebendo Mensagens

Estrutura geral

Campos do envelope

Campos comuns do `content`

Anúncios Click-to-WhatsApp (metaReferralAds)

Tipos de mensagem recebida

Exemplos por tipo

Download de mídia (DOWNLOAD_AVAILABLE)

​Enviando Mensagens

​Estrutura do Package

​Resposta

​Endereçamento (Address)

​WhatsApp

​Outros tipos de endereço

​Campos Comuns

​Responder a uma mensagem (quotedMessage)

​Tipos de Mensagem

​Operações sobre Mensagens

​Exemplo Completo

​Ciclo de Vida da Mensagem

​MESSAGE_SENT

​MESSAGE_DELIVERED

​MESSAGE_READ

​MESSAGE_PLAYED

​Recebendo Mensagens

​Estrutura geral

​Campos do envelope

​Campos comuns do content

​Anúncios Click-to-WhatsApp (metaReferralAds)

​Tipos de mensagem recebida

​Exemplos por tipo

​Download de mídia (DOWNLOAD_AVAILABLE)

Enviando Mensagens

Estrutura do Package

Resposta

Endereçamento (Address)

WhatsApp

Outros tipos de endereço

Campos Comuns

Responder a uma mensagem (quotedMessage)

Tipos de Mensagem

Operações sobre Mensagens

Exemplo Completo

Ciclo de Vida da Mensagem

MESSAGE_SENT

MESSAGE_DELIVERED

MESSAGE_READ

MESSAGE_PLAYED

Recebendo Mensagens

Estrutura geral

Campos do envelope

Campos comuns do `content`

Anúncios Click-to-WhatsApp (metaReferralAds)

Tipos de mensagem recebida

Exemplos por tipo

Download de mídia (DOWNLOAD_AVAILABLE)