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",
  "idempotency": {
    "key": "pedido-12345",
    "ttl": "30m"
  },
  "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

Controle de idempotência. Quando informado, a API rejeita requisições duplicadas com o mesmo key dentro do ttl.

object

required

Conteúdo polimórfico da mensagem. O campo type determina qual tipo de mensagem será enviado.

Idempotência

Use o campo idempotency para evitar envios duplicados quando houver falha de rede ou timeout. A API rejeita requisições com o mesmo key dentro do ttl com status 409 Conflict.

{
  "channelId": "uuid-do-canal",
  "idempotency": {
    "key": "pedido-12345",
    "ttl": "30m"
  },
  "content": {
    "type": "TEXT",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "text": "Seu pedido foi confirmado!"
  }
}

string

Chave única que identifica a requisição. Use um valor determinístico (por exemplo, ID do pedido ou combinação de usuário + timestamp). Requisições subsequentes com o mesmo key dentro do ttl retornam 409 Conflict.

string

required

Tempo de vida da chave em formato compacto: s (segundos), m (minutos), h (horas), d (dias), w (semanas). Exemplos: "30m", "1h30m", "4h". Máximo: 4h.

Combine idempotency com correlationId para rastreamento completo: o correlationId aparece nos webhooks de resposta, enquanto o idempotency.key protege contra duplicação no lado do envio.

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, GOOGLE_CHAT.

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

{
  "type": "GOOGLE_CHAT",
  "spaceId": "spaces/AAAA1234567"
}

{
  "type": "GOOGLE_CHAT",
  "userId": "users/123456789012345678901"
}

string

Identificador do espaço do Google Chat (formato spaces/{id}). Use para enviar mensagens em espaços já assinados pelo router.

string

Identificador do usuário do Google Chat (formato users/{id}). Use para envio avulso em DM 1:1 — o router localiza ou cria o DM antes de postar.

Para endereços GOOGLE_CHAT, use exatamente UM dos campos: spaceId ou userId. Enviar ambos causa erro de validação. O spaceId é o caminho comum (Fase 5); userId é usado quando você precisa enviar uma mensagem avulsa a uma pessoa específica sem espaço pré-existente (Fase 7).

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
Enquete	`POLL`	Enquete com múltiplas opções
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 "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",
        "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",
      "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
`greetingMessageBody`	`string`	Texto da saudação (boas-vindas) do anúncio
`automatedGreetingMessageShown`	`boolean`	`true` quando a saudação automática foi exibida ao lead
`automatedGreetingMessageCtaType`	`string`	Tipo de CTA da saudação automática

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
`POLL`	Enquete recebida
`POLL_VOTE`	Voto em uma enquete (apenas via webhook, veja Voto em enquete)
`FLOW_RECEIVED`	Resposta de um WhatsApp Flow (formulário interativo)
`TEMPLATE_RECEIVED`	Template recebido (mensagem baseada em template pré-aprovado)

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

FLOW_RECEIVED - Resposta de Flow

{
  "packageId": "0192f4ab-25bc-76de-37f0-c69518606481",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlationId": null,
  "content": {
    "type": "FLOW_RECEIVED",
    "flowToken": "flow-execution-token-12345",
    "flowName": "cadastro_cliente",
    "response": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "phone": "5511999887766"
    },
    "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": "3EB0C9D0E1F2A3B4",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "timestamp": "2025-04-14T11:10:00Z"
  }
}

O flowToken é o mesmo token usado no botão flow da mensagem de template que disparou o Flow. Use-o para correlacionar a resposta com a mensagem original. O campo response contém os dados do formulário preenchido pelo usuário, como JSON opaco.

TEMPLATE_RECEIVED - Template recebido

{
  "packageId": "0192f4ab-25bc-76de-37f0-c69518606481",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "correlationId": null,
  "content": {
    "type": "TEMPLATE_RECEIVED",
    "text": "Olá, João! Seu pedido #10245 foi confirmado.",
    "template": {
      "id": "1523498712340987",
      "name": "boas_vindas_cliente",
      "language": "pt_BR",
      "category": "UTILITY"
    },
    "header": {
      "format": "IMAGE",
      "mediaId": "media_abc123",
      "downloadUrl": "https://storage.messagefy.io/media/template_header.jpg"
    },
    "footer": "Loja do João",
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "index": 0,
        "text": "Confirmar"
      },
      {
        "type": "URL",
        "index": 1,
        "text": "Acompanhar",
        "url": "https://loja.com.br/pedidos/10245"
      }
    ],
    "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": "3EB0C9D0E1F2A3B5",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "timestamp": "2025-04-14T11:15:00Z"
  }
}

O TEMPLATE_RECEIVED chega quando o número recebe uma mensagem de template (por exemplo, de uma empresa que usa a API oficial). Tudo vem já renderizado: text é o corpo com as variáveis resolvidas, sem header nem footer. Se você só precisa do conteúdo, leia text e ignore o resto. O template identifica o template na origem e pode vir incompleto ou ausente (no WhatsApp Web normalmente só o id). O header traz texto, mídia ou localização conforme o format; quando é mídia, segue o mesmo fluxo de download das mensagens de mídia. buttons lista os botões na ordem de exibição (QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, FLOW, ORDER_DETAILS, entre outros).

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

Cobranças

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

Idempotência

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

​Idempotência

​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

Idempotência

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)