Messages

Message created

message.created

Fires when a new message is created — inbound from a contact or outbound from a user or the system. For ad-originated messages (e.g. WhatsApp Click-to-Message ads) the payload includes a referral object with ad details. WhatsApp quick-reply and interactive button taps are normalized into a regular text message: the button label goes to content.text and the button payload to content.interactive_reply_payload.

HTTP request

AISAR sends a signed POST request to your webhook_url:

http

POST {webhook_url}
Content-Type: application/json
X-AISAR-Signature: sha256=...

{
  "event": "message.created",
  "event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "2026-03-22T12:00:00.000000Z",
  "company_id": 1,
  "data": {
    "message": {
      "id": 123,
      "external_id": "3EB0ABC123456789",
      "conversation_id": 45,
      "thread_id": 67,
      "channel_id": 2,
      "direction": "inbound",
      "type": "text",
      "content": {
        "text": "Hello, I need help"
      },
      "display_content": "Hello, I need help",
      "media": null,
      "reply_to_message_id": null,
      "is_deleted": false,
      "system_notification": false,
      "created_at": "2026-03-22T12:00:00.000000Z"
    },
    "sender": {
      "type": "contact",
      "contact_id": 10,
      "contact_account_id": 15,
      "name": "John Doe",
      "phone": "+77001234567",
      "email": "john@example.com",
      "external_id": "77001234567@s.whatsapp.net"
    },
    "recipient": null,
    "conversation": {
      "id": 45,
      "status": "active",
      "contact_id": 10,
      "deal_id": null,
      "subject": null,
      "is_archived": false,
      "is_group": false
    },
    "channel": {
      "id": 2,
      "type": "whatsapp",
      "name": "Main WhatsApp"
    },
    "is_dialog_assigned": false,
    "referral": null
  }
}

The X-AISAR-Signature header carries an HMAC-SHA256 signature of the request body — use it to verify the request came from AISAR.

Example payload

json

{
  "event": "message.created",
  "event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "2026-03-22T12:00:00.000000Z",
  "company_id": 1,
  "data": {
    "message": {
      "id": 123,
      "external_id": "3EB0ABC123456789",
      "conversation_id": 45,
      "thread_id": 67,
      "channel_id": 2,
      "direction": "inbound",
      "type": "text",
      "content": {
        "text": "Hello, I need help"
      },
      "display_content": "Hello, I need help",
      "media": null,
      "reply_to_message_id": null,
      "is_deleted": false,
      "system_notification": false,
      "created_at": "2026-03-22T12:00:00.000000Z"
    },
    "sender": {
      "type": "contact",
      "contact_id": 10,
      "contact_account_id": 15,
      "name": "John Doe",
      "phone": "+77001234567",
      "email": "john@example.com",
      "external_id": "77001234567@s.whatsapp.net"
    },
    "recipient": null,
    "conversation": {
      "id": 45,
      "status": "active",
      "contact_id": 10,
      "deal_id": null,
      "subject": null,
      "is_archived": false,
      "is_group": false
    },
    "channel": {
      "id": 2,
      "type": "whatsapp",
      "name": "Main WhatsApp"
    },
    "is_dialog_assigned": false,
    "referral": null
  }
}

Payload fields

Field	Type	Description
`message.id`	`integer`	Internal message ID
`message.external_id`	`string`	External message ID (platform-specific, e.g. WhatsApp message ID)
`message.conversation_id`	`integer`	Conversation ID
`message.thread_id`	`integer`	Thread ID
`message.channel_id`	`integer`	Channel ID
`message.direction`	`string`	inbound (from contact) or outbound (from user/system)
`message.type`	`string`	Message type: text, image, video, audio, voice, document, sticker, location, contact, reaction, poll. voice is a voice note (recorded audio, OGG/Opus); plain audio is an audio file. WhatsApp quick-reply / interactive button taps are normalized to text
`message.content`	`object\|string`	Message content. For text: {"text": "..."}. For media it includes caption, mime_type, etc. For button taps it also carries interactive_reply_payload — the button payload / list option id (null when the template button has no payload)
`message.display_content`	`string\|null`	Plain text representation of the message content
`message.media`	`array\|null`	Attachments array; null if the message has no media
`message.media[].type`	`string`	Attachment type: image, video, audio, voice, document, sticker
`message.media[].url`	`string`	Download URL
`message.media[].filename`	`string\|null`	Original filename
`message.media[].mime_type`	`string\|null`	MIME type (e.g. image/jpeg; voice notes are audio/ogg)
`message.media[].size`	`integer\|null`	File size in bytes
`message.media[].duration`	`integer\|null`	Duration in seconds (audio / voice / video)
`message.reply_to_message_id`	`integer\|null`	ID of the quoted message, if this is a reply
`message.is_deleted`	`boolean`	Whether the message has been deleted
`message.system_notification`	`boolean`	Whether this is a system notification
`message.created_at`	`string`	ISO 8601 timestamp
`sender.type`	`string`	contact for inbound messages, user for outbound
`sender.contact_id`	`integer`	Contact ID (inbound messages)
`sender.contact_account_id`	`integer`	Contact account ID (inbound messages)
`sender.user_id`	`integer`	User ID (outbound messages)
`sender.name`	`string`	Sender display name
`sender.phone`	`string\|null`	Contact phone number (inbound messages)
`sender.email`	`string\|null`	Sender email
`sender.external_id`	`string`	Platform-specific contact ID, e.g. 77001234567@s.whatsapp.net (inbound messages)
`recipient`	`object\|null`	Present only for outbound messages: the recipient contact, same structure as sender with type=contact
`conversation.id`	`integer`	Conversation ID
`conversation.status`	`string`	active or closed
`conversation.contact_id`	`integer`	Contact ID
`conversation.deal_id`	`integer\|null`	Associated deal ID
`conversation.subject`	`string\|null`	Conversation subject
`conversation.is_archived`	`boolean`	Whether the conversation is archived
`conversation.is_group`	`boolean`	true if this conversation is a group chat (e.g. a WhatsApp group), false for direct messages
`channel.id`	`integer`	Channel ID
`channel.type`	`string`	Channel type: whatsapp, whatsapp_business, instagram, telegram
`channel.name`	`string`	Channel name
`is_dialog_assigned`	`boolean`	true if a user is assigned to this conversation, false otherwise
`referral`	`object\|null`	Referral data for ad-originated messages (e.g. WhatsApp Click-to-Message ads from Facebook/Instagram); null for regular messages
`referral.source_url`	`string`	URL of the ad or post
`referral.source_type`	`string`	Source type: ad or post
`referral.source_id`	`string`	Ad or post ID; can be used with the Meta API to get campaign details
`referral.headline`	`string`	Ad headline text
`referral.body`	`string`	Ad body text
`referral.ctwa_clid`	`string`	Click tracking ID for precise attribution
`referral.media_type`	`string`	Media type in the ad: image or video
`referral.image_url`	`string`	URL of the ad image (if applicable)
`referral.video_url`	`string`	URL of the ad video (if applicable)