2-Way Messaging with WhatsApp

Receive inbound WhatsApp messages from your users and reply within a 24-hour conversation window using native WhatsApp quoted replies.

Prelude supports 2-way messaging over WhatsApp, so your application can receive inbound messages from users and send contextual replies. Replies are delivered as native WhatsApp quoted messages, preserving conversation threading.

2-way messaging requires a connected WhatsApp Business Account (WABA). See the WhatsApp BSP guide for onboarding instructions.

How it works

1. User sends a WhatsApp message

   A user sends a text message to your WhatsApp Business number.

2. Prelude receives and forwards the message

   Prelude ingests the inbound message and sends a webhook event (inbound.message.received) to your configured callback URL. The event includes the message content, sender phone number, and a message ID you can use to reply.

3. You send a reply

   Your application calls the Reply to an inbound message endpoint with the to, text, and reply_to fields to send a reply within the 24-hour conversation window.

4. User receives a reply

   The user sees your reply as a native WhatsApp message.

Conversation window

WhatsApp enforces a 24-hour conversation window. You can only reply to an inbound message within 24 hours of when the user last messaged you. After the window expires, the API returns a window_expired error.

Each new inbound message from the same user resets the 24-hour window.

Replies outside the conversation window will be rejected. If you need to message the user after the window has closed, use a template-based message instead via the Send a message endpoint.

Sending a reply

To reply to an inbound message, use the dedicated Reply to an inbound message endpoint:

{
  "to": "[phone]",
  "text": "Thanks for reaching out! We'll look into your request.",
  "reply_to": "im_01k8aq2zggeyssvt53zgvpx63a"
}

to · string · required

The recipient’s phone number in E.164 format. Must match the phone number that sent the original inbound message.

text · string · required

The reply message body, sent as a free-form WhatsApp text.

reply_to · string · required

The inbound message ID (prefixed with im_) to reply to. This ID is provided in the inbound.message.received webhook event.

The to field must match the phone number that sent the original inbound message. A phone_number_mismatch error is returned otherwise.

SDK examples

Node.js

const response = await client.notify.reply({
  to: "[phone]",
  text: "Thanks for reaching out! We'll look into your request.",
  reply_to: "im_01k8aq2zggeyssvt53zgvpx63a",
});

Receiving inbound messages

To receive inbound WhatsApp messages, configure a webhook callback URL with your Customer Success Manager. When a user sends a message to your WhatsApp Business number, Prelude forwards it as an inbound.message.received webhook event.

Webhook event

{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "inbound.message.received",
  "payload": {
    "message_id": "im_01k8aq2zggeyssvt53zgvpx63a",
    "channel": "whatsapp",
    "from": "[phone]",
    "to": "[phone]",
    "content": {
      "text": "Hi, I have a question about my order"
    },
    "conversation": {
      "window_expires_at": "2025-10-25T08:59:10.736909995Z"
    }
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}

payload.message_id · string

The unique inbound message identifier (prefixed with im_). Use this value in context.reply_to to send a reply.

payload.channel · string

The channel the message was received on. Currently whatsapp.

payload.from · string

The sender’s phone number in E.164 format.

payload.to · string

Your WhatsApp Business phone number that received the message.

payload.content.text · string

The text content of the inbound message.

payload.conversation.window_expires_at · RFC3339 date string

The timestamp when the 24-hour conversation window expires. Replies must be sent before this time.

Error handling

The following errors are specific to 2-way messaging:

Error Code	Description	Action
window_expired	The 24-hour conversation window has closed	Use a template-based message instead
invalid_reply_context	The inbound message ID was not found	Verify the reply_to message ID
phone_number_mismatch	The to number does not match the inbound message sender	Use the phone number from the inbound webhook event
missing_text	The text field is empty or missing	Provide a reply message body

Limitations

• Only text messages are supported for inbound messages. Media messages (images, videos, documents) are not forwarded.
• Replies are sent as free-form text, not as WhatsApp templates.
• 2-way messaging is only available through the WhatsApp channel via your connected WABA.
• The conversation window is 24 hours from the latest inbound message and cannot be extended.