How to assess a RapidPro upgrade

Start with an exact change, not “latest”

Record the application repository and commit or tag currently deployed, the proposed target, local patches and the versions of supporting services. Include integration code and configuration references, without placing credentials in the review document. A moving branch name is not a reproducible deployment record.

When checked on 3 October 2026, the Temba GitHub Releases page had no published release entries. That page therefore cannot substantiate a year-by-year feature list. Use the relevant upstream code history, maintainer documentation and your own acceptance tests to verify the particular change you are considering.

Write down the reason: a verified fix, a required capability, a dependency maintenance need or a problem observed in your programme. Link the evidence to the target revision. If the benefit is uncertain, keep investigating rather than presenting the upgrade as an automatic improvement.

Check the licence before changing upstream

Moving between the AGPL RapidPro code and BSL Temba code can change the terms governing your deployment. BSL is source-available, not open source. Check the target version’s licence and any separate agreement against your hosting model before testing a production transition. A permission attached to one release or arrangement should not be assumed to cover another.

This guide does not specify an approved BotFlow Host release or a universal upgrade command. Those depend on the starting system, target code and agreed licence. Read the RapidPro introduction for the wider hosting decision.

Inventory the dependencies that matter

The official hosting overview shows why the application is only part of the service. Treat that overview as background and inventory the actual transport, flow-processing, worker, database and storage components in your installation. Check the target’s dependency requirements and migration steps rather than copying an older architecture’s versions or sizing.

• Programme behaviour: active flows, scheduled work, languages, contact fields and triggers.
• Provider boundaries: connected channels, credentials, inbound callbacks and delivery-status handling.
• Integrations: API consumers, webhook payloads, authentication and any AI request/fallback paths.
• Operational state: queued work, stored media, archives, database migrations and local configuration.

For each item, name an owner and a test. A team that knows its workflows can detect a changed branch or missing result that a generic server health check will miss.

Rehearse without contacting participants

Prepare an isolated environment with representative, minimised test data. Prevent it from sending through live channels, firing production webhooks or triggering real campaigns. Replacing a database connection is not sufficient isolation if copied credentials still reach production providers.

Rehearse the upgrade from the actual starting revision. Record migrations, elapsed time, errors and any manual intervention. Then run a small set of representative journeys: enrolment, a scheduled reminder, an unexpected reply, an integration failure and an opt-out. Use controlled test accounts for channel checks and verify both replies and stored results.

For example, a fictional learning programme might require a registration to preserve language and consent, a reminder to trigger once, and an unavailable external service to select the approved fallback. Compare those outcomes before and after the rehearsal. Adapt this hypothetical acceptance test to your own programme.

Prove recovery separately from backup creation

Define the recovery set for this deployment: database, media and archives where applicable, configuration, securely stored secrets and compatible application/component versions. Test restoration in isolation and record what can actually be recovered. A successful backup job does not prove that you can restore a working messaging service.

Do not assume reverting application code reverses a database migration. Decide whether recovery requires a database restore, a forward fix or another tested procedure. Document the treatment of messages and contact changes that arrive after the recovery point, including any risk of loss or duplicate processing. Agree how much data loss and recovery time the programme can tolerate, then establish those targets in the service agreement.

Make the go/no-go decision explicit

1. The target revision and licensing route are recorded and approved for the deployment.
2. Required migrations and component combinations have been rehearsed from the current state.
3. Representative flow, channel and integration checks pass, including failure paths.
4. Recovery has been tested and the team understands its data and messaging consequences.
5. A named operator and programme reviewer are available for the change window and follow-up.

A failed criterion is a reason to pause and fix the gap. For an urgent maintenance change, record any incomplete evidence and the decision owner explicitly rather than silently lowering the bar.

Watch the conversation after the change

Compare queue age, processing errors, integration failures and provider acknowledgements with the pre-change baseline. Review representative flow results with the programme team. Low traffic can hide a broken path, so keep controlled checks available and agree how long the observation period lasts.

Finish with a change record: deployed revisions, test results, recovery evidence, unresolved issues and the person responsible for each follow-up. That becomes the starting point for the next upgrade. For deeper troubleshooting, see how source access helps trace an AI-assisted conversation.

Bring the evidence to an upgrade review

BotFlow Host provides managed RapidPro infrastructure, including upgrades as part of its operational scope. Bring your current revision, channels, integrations and proposed change to a technical conversation. We can discuss the work required for your system without promising that every legacy deployment has a simple migration path.