Meta API response check

[sebabratakundu]

Currently, is there any way to verify the response we receive from Meta?

For example, let’s say I send a message. How can I verify whether the message was actually sent successfully or not?

In the current implementation, whenever an error occurs, we emit a notification notice, but the information isn’t very structured or clear. I’m wondering how you guys are handling this.

Are you tracking the status of each message to determine whether it was successfully sent, failed, or is still being processed?

Any information on how you’re validating and tracking the message status would be really helpful.

[yudin-s]

I would track this in two layers, because the Meta provider gives you an immediate API result, while final delivery state comes later from webhooks.

In the current BuilderBot Meta provider, outbound sends go through sendMessageMeta() -> sendMessageToApi(), which is an axios.post() to:

https://graph.facebook.com/{version}/{numberId}/messages

If that request fails, the provider throws the HTTP error. If it succeeds, it returns response.data. For WhatsApp Cloud API, that success response is the "Meta accepted this message" signal and should contain the Meta message id, usually under messages[0].id. I would store that id immediately with a local state like accepted or queued, not delivered.

The important catch is that this is not the same as "the user received it". Meta reports message lifecycle states asynchronously through webhook statuses entries: sent, delivered, read, and failed.

From the current BuilderBot source, packages/provider/src/meta/server.js only handles:

const messages = body?.entry?.[0]?.changes?.[0]?.value?.messages

if (!messages) {
  res.statusCode = 200
  res.end('empty endpoint')
  return
}

So status callbacks under value.statuses are currently ignored by the Meta provider webhook server. That explains why a notice/error event alone feels too unstructured: it is not a durable delivery-state model.

The pattern I would use is:

1. Wrap every outbound send.
2. On successful sendtext() / sendMessageMeta() result, save messages[0].id as your correlation key.
3. Save initial state as accepted_by_meta or sent_to_meta.
4. Extend/fork the Meta webhook handler to also read body.entry[0].changes[0].value.statuses.
5. When a status webhook arrives, update your row by status.id:
   • sent
   • delivered
   • read
   • failed, storing status.errors if present.

So: yes, you can know whether Meta accepted the send from the immediate response. To know whether it was actually sent/delivered/read/failed, you need to persist the returned WhatsApp message id and handle Meta status webhooks. In current BuilderBot, that status-webhook part appears to be something you need to add around the provider, because the built-in Meta webhook server currently emits incoming message events but not outbound statuses.

If that matches what you are seeing, please mark this as answered so the next person does not treat the initial Meta response as final delivery confirmation.

[sebabratakundu]

I think I wasn’t clear enough. What I meant is that we are able to get the status from the notice events, but the events fired by BuilderBot don’t contain enough details. They are simply structured in the following format:

{ title: '', instructions: [] }

Also, as you can see, this is the reason format. We are not including the recipient property, an error code. etc. from this we have to match the text.

[yudin-s]

Yes, that clarification makes sense, and you are right to avoid matching only the text.

Looking at the current provider-meta code, the limitation is exactly in the provider layer:

• MetaCoreVendor.extractStatus() walks value.statuses[], but reduces each status to only { status, reason }.
• reason is built as Number(${recipientId}): ${errorDetails}.
• incomingMsg() emits notice only for the first failed status, with instructions: [findError.reason].
• MetaProvider.busEvents() forwards that as the generic notice shape, so consumers only see { title, instructions }.

So the notice event is currently a lossy alert, not a structured delivery-status event. It preserves enough for a human console warning, but not enough for reliable correlation. The robust correlation key should be the Meta status id / wamid, not the message text. The recipient and error details are useful fields, but they should be separate properties, not embedded inside instructions[0].

For a fix or PR, I would not try to parse the current notice string. I would change the status path to keep the raw status fields and expose a structured event, for example:

this.emit('message_status', {
  id: status.id,
  recipientId: status.recipient_id ?? status.recipient_user_id,
  status: status.status,
  timestamp: status.timestamp,
  errors: status.errors ?? [],
})

or, if the project wants to avoid a new event, extend the notice payload with an extra meta / payload object while keeping title and instructions for backward compatibility.

The current MessageStatus type also only declares recipient_id, recipient_user_id, errors, and status, so the PR should update that type to include the fields Meta actually sends for status callbacks, especially id and probably timestamp.

One more important detail: the current webhook handler only acts when a status is failed. Successful sent, delivered, and read statuses are extracted but then effectively ignored because there is no messages[] payload and the handler returns empty endpoint. So a complete delivery-state fix should emit structured events for all statuses, not just failed ones.

Short version: yes, your diagnosis is valid. Today the provider turns a structured Meta status callback into a human notice string. The clean fix is to preserve and emit the original status metadata, especially the WhatsApp message id, rather than matching on text.

[sebabratakundu]

Thanks, will raise a PR

[sebabratakundu]

issue - #1262