Skip to main content
Prelude supports 2-way messaging over WhatsApp, enabling your application to 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 Send a message endpoint with the text and context.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 standard Send a message endpoint.

​
Sending a reply

To reply to an inbound message, use the Send a message endpoint with the text and context fields: 
{
  "to": "+33612345678",
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "text": "Thanks for reaching out! We'll look into your request.",
  "context": {
    "reply_to": "im_01k8aq2zggeyssvt53zgvpx63a"
  }
}
​
text
string
required
The reply message body. Required when context.reply_to is provided.
​
context
object
​
context.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

const response = await client.notify.send({
  to: "+33612345678",
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  text: "Thanks for reaching out! We'll look into your request.",
  context: {
    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": "+33612345678",
    "to": "+14155551234",
    "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 CodeDescriptionAction
window_expiredThe 24-hour conversation window has closedUse a template-based message instead
invalid_reply_contextThe inbound message ID was not foundVerify the reply_to message ID
phone_number_mismatchThe to number does not match the inbound message senderUse the phone number from the inbound webhook event
missing_textThe text field is empty or missingProvide 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.