Correlating Webhook Events with API Records (guid vs. message_handle)

If you're building automation on the API and matching up IDs across webhooks and endpoints, start here — this covers why the IDs look different and how to line them up.

Why the IDs don't match

POST /send-api-message does not return a message ID at send time — only success and messageType. The identifiers show up later, in two different places, under two different names:

Webhook events (inbound and outbound) include guid and messageId.
GET /get-messages-api returns the same message under message_handle.

These are not the same ID space, so you can't generate one from the other. Treat them as two separate identifiers for the same message.

How to correlate a send

Until send responses include a handle directly, the reliable way to match a send you triggered to its later webhook event or API record is:

Destination number (the number you sent to)
Message body (exact text sent)
Timestamp (the time you made the send call)

Match on all three, then poll /get-messages-api if you need the message_handle for that record.

Repeat sends and the dedupe window

Sending an identical message body to the same recipient within roughly an hour of a prior send will be silently deduplicated — no handle is issued for the dropped send, and no error is returned.

If your automation might legitimately send the same wording twice in a short window (for example, a repeat reminder), add a small unique variation to the body — such as a timestamp or reference number — so it isn't treated as a duplicate.

For everything else on the API — keys, webhooks, and MCP setup — see Project Blue API, Webhooks & MCP.