Guides

Receive messages

Receive your customers' messages by webhook, reply within the 24-hour window and find them in the history.

Updated November 12, 2026View as Markdown

When a customer writes to one of your numbers, Bref Point Inbox stores the message and sends a message.received event to your webhook endpoints. Declare one first (see Webhooks).

The event#

message.received

{
  "id": "8dc9eca4-2eff-46de-80aa-0ac9674dd1ae",
  "type": "message.received",
  "createdAt": "2026-11-12T06:09:17.388Z",
  "data": {
    "messageId": "4f21edc3-047e-4f75-819a-1e69953f40a3",
    "waMessageId": "wamid.HBgM…",
    "phoneNumberId": "fb10613a-8a2c-4340-87ff-192082ffaf1f",
    "from": "237611111111",
    "type": "text",
    "content": { "text": { "body": "Hello, I'd like to reschedule my appointment" } },
    "contactName": "Awa",
    "occurredAt": "2026-11-12T06:09:17.402Z"
  }
}

`data` field	Description
`messageId`	The message's identifier at Bref Point Inbox.
`waMessageId`	The message's identifier at WhatsApp.
`phoneNumberId`	The number that received the message (the number's `id`, as when sending).
`from`	The sender's number, without the "+".
`type`	`text`, `image`, `document`, `audio`, `video`, `location`, `sticker`, `button`… as declared by Meta.
`content`	The content, under a key named after the type: `{ "text": { "body": … } }`, `{ "image": { "id": …, "caption": … } }`… The exact shape is Meta's.
`contactName`	The sender's WhatsApp profile name, if known.

Reply#

A received message opens the 24-hour window for this number and this sender: you can reply with a free-form message.

bash

curl -X POST "$INBOX_API/messages" \
  -H "Authorization: Bearer $INBOX_KEY" -H "Content-Type: application/json" \
  -d '{ "phoneNumberId": "<data.phoneNumberId>", "to": "+<data.from>", "type": "text",
        "text": { "body": "Of course, which time slot would suit you?" } }'

The window is calculated per sender and per number: a message from another customer doesn't open this one's window.

Avoid processing twice#

Events can arrive more than once (retry after a timeout, manual replay, resend by Meta). Bref Point Inbox deduplicates received messages when storing them, but your receiver must also be tolerant: the event id (and data.messageId) is stable, so ignore what you've already processed.

Find received messages#

bash

curl "$INBOX_API/messages" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/messages`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/messages",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "data": [
    {
      "id": "a9691d7a-ee51-4da9-87b2-24cce79a9313",
      "direction": "outbound",
      "status": "sent",
      "type": "location",
      "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
      "to": "237611111111",
      "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "content": {
        "type": "location",
        "location": {
          "name": "Cabinet Dentaire Zokem",
          "address": "Akwa, Douala",
          "latitude": 4.0511,
          "longitude": 9.7679
        }
      },
      "error": null,
      "createdAt": "2026-11-12T08:33:46.131Z",
      "sentAt": "2026-11-12T08:33:46.251Z",
      "deliveredAt": null,
      "readAt": null
    },
    {
      "id": "9e09a76b-537b-4d5f-8454-4305ba8748a6",
      "direction": "outbound",
      "status": "sent",
      "type": "document",
      "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
      "to": "237611111111",
      "waMessageId": "wamid.HBgMXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "content": {
        "type": "document",
        "media": {
          "link": "https://example.com/ordonnance.pdf",
          "caption": "Your prescription",
          "filename": "ordonnance.pdf"
        }
      },
      "error": null,
      "createdAt": "2026-11-12T08:33:46.098Z",
      "sentAt": "2026-11-12T08:33:46.221Z",
      "deliveredAt": null,
      "readAt": null
    }
  ],
  "nextCursor": "MjAyNi0xMS0xMlQwODozMzo0Ni4wOThafGMwYmU4NDdlLWQyNDQtNGUyOS04N2M1LTAyNTE3ODk1Yzg5OQ"
}

Add ?direction=inbound to see only received messages.

Test without a phone#

The sandbox makes a message "arrive" on demand and triggers your real webhook:

bash

curl -X POST "$INBOX_API/sandbox/simulate/inbound-message" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "from": "+237611111111",
    "text": "Hello, I'\''d like to reschedule my appointment"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/sandbox/simulate/inbound-message`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "from": "+237611111111",
    "text": "Hello, I'd like to reschedule my appointment"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/sandbox/simulate/inbound-message",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "phoneNumberId": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
        "from": "+237611111111",
        "text": "Hello, I'd like to reschedule my appointment",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/sandbox/simulate/inbound-message');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phoneNumberId' => '4d8e654e-d744-4bf3-8211-9ceffcccfe87',
        'from' => '+237611111111',
        'text' => 'Hello, I\'d like to reschedule my appointment',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "messageId": "3f3baf5a-f93e-42e8-8263-ce62dc4aadd6",
  "from": "237611111111",
  "status": "received",
  "simulated": true
}