Inbound Messages & Replies

This guide explains how InstaMessage handles inbound messages, customer replies, auto-replies, and opt-outs across all supported channels.

Inbound messages are delivered to your application via webhooks, allowing you to react in real time.

An inbound message is any message sent from a customer to your business, for example:

• An SMS message
• A WhatsApp message
• A Messenger message
• An RCS message, including a tap on a suggested reply

Inbound messages are channel-agnostic and follow the same webhook structure regardless of channel.

All inbound messages are delivered to your configured webhook endpoint as a message.inbound event.

You must configure your webhook URL in the InstaMessage dashboard.

message.inbound

Example payload:

{
  "event_type": "message.inbound",
  "event_id": "evt_12345",
  "message_id": "msg_in_12345",
  "channel": "sms",
  "from": "+447111222333",
  "to": "+447444555666",
  "message_type": "text",
  "text": "Hi, I need help with my order",
  "received_at": "2025-06-01T14:22:10Z"
}

{
  "event_type": "message.inbound",
  "event_id": "evt_67890",
  "message_id": "msg_in_67890",
  "channel": "whatsapp",
  "from": "+447111222333",
  "to": "+447444555666",
  "message_type": "text",
  "text": "Hi, can you confirm my booking?",
  "received_at": "2025-06-01T14:25:42Z"
}

Inbound messages may include media (where supported by the channel).

Example — inbound WhatsApp image

{
  "event_type": "message.inbound",
  "event_id": "evt_99999",
  "message_id": "msg_in_99999",
  "channel": "whatsapp",
  "from": "+447111222333",
  "to": "+447444555666",
  "message_type": "image",
  "image": {
    "url": "https://media.instamessage.co.uk/media/abc123.jpg"
  },
  "received_at": "2025-06-01T14:30:01Z"
}

Media URLs are time-limited and should be downloaded promptly.

To reply to an inbound message, use the Send a Message API.

Replies are standard outbound messages and must follow channel rules.

{
  "channel": "sms",
  "tel": "+447111222333",
  "message_type": "text",
  "text": "Thanks for your message. We’ll be in touch shortly."
}

When a customer sends you a WhatsApp message, a 24-hour customer service window opens.

Inside this window, you may send (These messages do not require a WhatsApp Template.):

• Free-form text messages

• Media messages

• Personalised messages using injected_fields

{
  "channel": "whatsapp",
  "to": "+447111222333",
  "message_type": "text",
  "text": "Thanks for getting in touch — your booking is confirmed."
}

Outside the 24-hour window, you must use a WhatsApp Template message.

RCS has no messaging window. You can reply at any time with text, media or rich content. Replies are sent from your approved RCS agent.

{
  "channel": "rcs",
  "to": "+447111222333",
  "message_type": "text",
  "text": "Thanks — your delivery has been rescheduled."
}

If your agent is registered as conversational, a reply from the recipient opens a 24-hour conversation window that affects billing. See RCS billing.

InstaMessage currently supports web opt-out only.

• We do not currently process SMS STOP/END keywords automatically.
• If you need opt-out compliance, you should provide a web opt-out mechanism and add recipients to the opt-out list via the Opt-outs API.

You can retrieve or manage opt-outs using the Opt-outs API.

InstaMessage supports simple auto-replies configured in the dashboard (not AI-driven and not Flow-based).

Auto-replies are triggered when an inbound message is received:

• Outside your configured opening hours, or
• On holiday dates both defined in Admin

Auto-replies are configured in InstaMessage in Admin → Inbox.

Inbound messages are delivered via webhooks on a best-effort basis.

• Webhooks are not retried if your endpoint fails
• If your webhook endpoint is unavailable, inbound events may be missed

For reliability:

• Always respond 200 OK quickly
• Store inbound events idempotently using event_id
• Use the Opt-outs API and Message Status API as sources of truth

Inbound messaging enables:

• Two-way customer support
• Conversational WhatsApp flows
• AI or bot-driven responses
• Human agent handoff via inbox tools

• Send replies → Send a Message
• Track delivery → Delivery Receipts & Message Status
• Manage compliance → Opt-outs
• Set up inbound webhooks → Webhook Quick-Start

Inbound messaging completes the two-way messaging loop and allows InstaMessage to act as a full conversational platform.