> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover failed messages

> Reconcile delivery without repeating agent side effects.

This guide uses the [Messaging relay](/docs/guides/channels/messaging) 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.

| State | What it establishes | Next action |
| --- | --- | --- |
| `queued` | Valid input was saved; no runtime work started. | Check the conversation pause and reply deadline. |
| `starting` / `launching` / `executing` at process loss | A remote runtime operation may have happened. | Startup converts it to `uncertain`; investigate before resetting. |
| `ready` | Traces were saved; a send has not started. | Fix any local validation problem without rerunning the turn. |
| `sending` at process loss or error | Some or all parts may have been accepted. | Compare accepted part IDs and the destination before acting. |
| `failed` / `uncertain` | The conversation is paused. | Resolve the evidence; automatic retries are deliberately stopped. |
| `done` | The send call was accepted and checkpointed. | Check later delivery receipts or the customer-visible conversation. |
| `suppressed` / `discarded` | No new delivery is intended for this event. | Retain the audit record through the provider’s retry horizon. |

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:

```sh
node --env-file=.env relay.mjs resolve EVENT_ID delivered
# Or, for obsolete/undeliverable work:
node --env-file=.env relay.mjs resolve EVENT_ID discard
```

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](/docs/examples/messaging/messaging-relay.zip) 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.
