Messages

These events are sent for every message received from or sent to a contact. Set them up in Webhooks.

Channel	Incoming event.type	Outgoing event.type
WhatsApp	incoming_whatsapp_message	outgoing_whatsapp_message
Instagram	incoming_instagram_message	outgoing_instagram_message
Messenger	incoming_messenger_message	outgoing_messenger_message
Telegram	incoming_telegram_message	outgoing_telegram_message
TikTok	incoming_tiktok_message	outgoing_tiktok_message
Website (live chat)	incoming_website_message	outgoing_website_message

Outgoing messages sent by broadcasts, and chat history imported from the WhatsApp Business app, do not send webhooks.

The examples show WhatsApp; other channels use the same format. Useful fields:

• message.location: the workspace the message belongs to (id, title).
• message.connectedChannel: the number, page or account the message went through. platform is always there; id and name identify the account (WhatsApp: phone number ID and display number, plus phoneNumber and businessId; Messenger: Facebook Page; Instagram: Instagram account; TikTok: business account; Website: live chat widget). Telegram only sends platform. It is filled in whenever your payload template uses connectedChannel, as the default template does.
• message.from (incoming) or message.sentBy (outgoing): who sent it.
• ctwaClid, adId, adSourceType, adSourceUrl (incoming WhatsApp only): present on the first message after someone taps a Click-to-WhatsApp ad, so you can send conversions back to Meta.

Fields you can use in a custom payload

The payloads below are the default templates. When you edit the payload of a webhook, you can use any of these values with {{ }}:

Variable	What it holds
message.id, message.type, message.text, message.caption, message.mediaUrl	The message itself
message.channel	whatsApp, instagram, messenger, telegram, tiktok or website
message.location.id, message.location.title	The workspace
message.connectedChannel.platform, .id, .name, .phoneNumber, .businessId	The connected number, page or account
message.contact.id, .channel, .phoneNumber, .username	The contact
message.contact.instagramId, .messengerId, .telegramChatId	The contact's ID on that channel
message.contact.customFields.<name>	A contact custom field, for example message.contact.customFields.ctwa_clid
message.from / message.sentBy	Sender name (incoming / outgoing)
message.status, message.errorMessage	Delivery status of an outgoing message
message.referral.ctwa_clid, .source_id, .source_type, .source_url	Click-to-WhatsApp ad details (incoming WhatsApp)

Incoming Messages

(i) Payload Format: This is an example of WhatsApp Incoming Messages Payload data format and content that Whautomate will transmit to the configured endpoint. All other channels follow similar payload format.

{
  "event": {
    "id": "{{event.id}}",
    "type": "{{event.type}}",
    "timeStamp": "{{event.timeStamp}}",
    "key": "{{event.key}}"
  },
  "message": {
    "id": "{{message.id}}",
    "contact": {
      "id": "{{message.contact.id}}",
      "channel": "{{message.contact.channel}}",
      "phoneNumber": "{{message.contact.phoneNumber}}"
    },
    "channel": "{{message.channel}}",
    "location": {
      "id": "{{message.location.id}}",
      "title": "{{message.location.title}}"
    },
    "connectedChannel": {
      "platform": "{{message.connectedChannel.platform}}",
      "id": "{{message.connectedChannel.id}}",
      "name": "{{message.connectedChannel.name}}",
      "phoneNumber": "{{message.connectedChannel.phoneNumber}}"
    },
    "isIncoming": "{{message.isIncoming}}",
    "type": "{{message.type}}",
    "replyToMessage": {
      "id": "{{message.replyToMessage.id}}"
    },
    "from": "{{message.from}}",
    "sentBy": "{{message.sentBy}}",
    "timestamp": "{{message.timestamp}}",
    "status": "{{message.status}}",
    "errorMessage": "{{message.errorMessage}}",
    "headerText": "{{message.headerText}}",
    "mediaUrl": "{{message.mediaUrl}}",
    "caption": "{{message.caption}}",
    "text": "{{message.text}}",
    "footerText": "{{message.footerText}}",
    "options": "{{message.options}}",
    "ctwaClid": "{{message.referral.ctwa_clid}}",
    "adId": "{{message.referral.source_id}}",
    "adSourceType": "{{message.referral.source_type}}",
    "adSourceUrl": "{{message.referral.source_url}}",
    "createdAt": "{{message.createdAt}}",
    "updatedAt": "{{message.updatedAt}}"
  }
}

(ii) WhatsApp Incoming Message test Payload data

{
  "event": {
    "id": "cIH32l5nW8",
    "type": "incoming_whatsapp_message",
    "timeStamp": "2024-03-17T03:31:24.572Z",
    "key": "2xoE5Rb6yT"
  },
  "message": {
    "id": "2xoE5Rb6yT",
    "contact": {
      "id": "mA7FeZiPlb",
      "channel": "whatsapp",
      "phoneNumber": "6598765432"
    },
    "channel": "whatsApp",
    "location": {
      "id": "Kq3LmZp8Tx",
      "title": "Serene Wellness Studio"
    },
    "connectedChannel": {
      "platform": "whatsapp",
      "id": "106540352242922",
      "name": "+65 6123 4567",
      "phoneNumber": "+65 6123 4567"
    },
    "isIncoming": "true",
    "type": "text",
    "replyToMessage": {},
    "from": "John",
    "timestamp": "2024-03-17T03:31:24.572Z",
    "text": "This is a sample message.",
    "ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
    "adId": "120208012345670123",
    "adSourceType": "ad",
    "adSourceUrl": "https://fb.me/2ZulEu42P",
    "createdAt": "2022-01-01T12:00:00Z",
    "updatedAt": "2024-03-17T10:30:00Z"
  }
}

---

Outgoing Messages

(i) Payload Format: This is an example of WhatsApp Outgoing Messages Payload data format and content that Whautomate will transmit to the configured endpoint. All other channels follow similar payload format.

{
  "event": {
    "id": "{{event.id}}",
    "type": "{{event.type}}",
    "timeStamp": "{{event.timeStamp}}",
    "key": "{{event.key}}"
  },
  "message": {
    "id": "{{message.id}}",
    "contact": {
      "id": "{{message.contact.id}}",
      "channel": "{{message.contact.channel}}",
      "phoneNumber": "{{message.contact.phoneNumber}}"
    },
    "channel": "{{message.channel}}",
    "location": {
      "id": "{{message.location.id}}",
      "title": "{{message.location.title}}"
    },
    "connectedChannel": {
      "platform": "{{message.connectedChannel.platform}}",
      "id": "{{message.connectedChannel.id}}",
      "name": "{{message.connectedChannel.name}}",
      "phoneNumber": "{{message.connectedChannel.phoneNumber}}"
    },
    "isIncoming": "{{message.isIncoming}}",
    "type": "{{message.type}}",
    "replyToMessage": {
      "id": "{{message.replyToMessage.id}}"
    },
    "from": "{{message.from}}",
    "sentBy": "{{message.sentBy}}",
    "timestamp": "{{message.timestamp}}",
    "status": "{{message.status}}",
    "errorMessage": "{{message.errorMessage}}",
    "headerText": "{{message.headerText}}",
    "mediaUrl": "{{message.mediaUrl}}",
    "caption": "{{message.caption}}",
    "text": "{{message.text}}",
    "footerText": "{{message.footerText}}",
    "options": "{{message.options}}",
    "createdAt": "{{message.createdAt}}",
    "updatedAt": "{{message.updatedAt}}"
  }
}

(ii) WhatsApp Outgoing Message test Payload data

{
  "event": {
    "id": "z6nbgjHupV",
    "type": "outgoing_whatsapp_message",
    "timeStamp": "2024-03-17T03:34:50.949Z",
    "key": "bhe3VsVdv4"
  },
  "message": {
    "id": "bhe3VsVdv4",
    "contact": {
      "id": "YA0FvPocZs",
      "channel": "whatsapp",
      "phoneNumber": "6581513780"
    },
    "channel": "whatsApp",
    "location": {
      "id": "Kq3LmZp8Tx",
      "title": "Serene Wellness Studio"
    },
    "connectedChannel": {
      "platform": "whatsapp",
      "id": "106540352242922",
      "name": "+65 6123 4567",
      "phoneNumber": "+65 6123 4567"
    },
    "isIncoming": "false",
    "type": "text",
    "replyToMessage": {},
    "sentBy": "John Doe",
    "text": "This is a test message.",
    "createdAt": "2022-01-01T12:00:00Z",
    "updatedAt": "2024-03-17T10:30:00Z"
  }
}

Related

• Webhooks
• Messages REST API