This guide uses the Messaging relay to recover failed messages.

Before you begin

Start with the installed relay, the failed event’s provider ID, its private state directory and access to provider diagnostics and Voiceflow Transcripts. Keep the service stopped while running operator commands. A timed-out request may already have executed.

Reconcile the failed event

1

Find the stage that failed

Run node --env-file=.env relay.mjs inspect. Record the event ID, conversation key, phase and accepted parts. Read state.json only in a private environment to compare the saved traces with provider-side messages. Back up the file before maintenance.

The sent array records accepted chunks, not proof that a customer read them.

2

Check remote effects before resolving

If runtime execution timed out, look for its Transcript and any business-system tool result. Do not send the text action again merely to recover a missing answer. If delivery timed out, check the platform’s message IDs, delivery/failure callbacks and actual conversation. A provider can accept a message before the HTTP connection fails.

For expired LINE tokens, Discord tokens or Meta/WeChat reply windows, do not force the old reply through a different route. For 429, fix throughput and respect the provider’s retry guidance in any further send implementation. This example pauses rather than running an unbounded retry loop.

3

Resolve and resume explicitly

After you establish what happened, mark a confirmed accepted/delivered event complete, or discard work that should not run:

Use one of those outcomes, not both. The command updates local state; it does not send, revoke or verify a message. It has no automatic “retry the whole turn” option. If an answer still needs delivery, have an authorized operator use the platform’s permitted support route after checking its window and accepted chunks, then resolve the event accordingly.

If the runtime session is no longer usable, run reset KEY after reconciliation. Then resume KEY and restart the service. Keep the original event ID so a provider retry cannot repeat it. Do not delete the state file as a recovery shortcut.

Verify recovery

1

Replay and restart in a test installation

Extract the relay archive and run node --test fixtures.test.mjs in its directory. The bundled runner creates signed synthetic callbacks, delivers duplicates and reopens the persisted store; all provider/runtime responses are mocked. It should produce one runtime text turn and one intended reply. Simulate a send timeout after provider acceptance; expect an uncertain paused job rather than an automatic second send.

2

Check the customer’s next message

After resolving and resuming, send a fresh question from the test customer. Expect one reply and no obsolete backlog. Check that other customers were not blocked by the failed customer’s pause.

A replay executes the agent again

Restore event retention and one-writer persistence.

Keep stable provider event IDs, including Viber’s full 64-bit message token and RCS’s message ID. Retain deduplication records at least as long as provider retry and operational replay horizons. Back up state privately; apply a deliberate retention job rather than deleting it at each deploy. Multiple processes need a transactional shared store before they are safe.

A done job still has a delivery failure

Separate API acceptance from downstream delivery.

Inspect receipts in the private state and provider logs. Meta statuses, Viber failures, Sinch delivery reports, Sunshine failure events and RCS events can arrive after acceptance. This sample stores available receipts but does not automatically reconcile every provider’s later receipt into the job phase; monitor them and pause the affected conversation if follow-up must stop. Telegram and Slack do not provide an end-customer read guarantee through the send response.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.