https://github.com/nyaruka/goflow
Flow engine for RapidPro/TextIt.
https://github.com/nyaruka/goflow
flows flowspec messaging
Last synced: 29 days ago
JSON representation
Flow engine for RapidPro/TextIt.
- Host: GitHub
- URL: https://github.com/nyaruka/goflow
- Owner: nyaruka
- License: other
- Created: 2017-05-10T17:43:06.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2026-02-03T20:41:17.000Z (about 2 months ago)
- Last Synced: 2026-02-04T06:32:52.265Z (about 2 months ago)
- Topics: flows, flowspec, messaging
- Language: Go
- Homepage:
- Size: 23.7 MB
- Stars: 48
- Watchers: 8
- Forks: 23
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎢 Goflow
[](https://github.com/nyaruka/goflow/actions?query=workflow%3ACI)
[](https://codecov.io/gh/nyaruka/goflow)
[](https://goreportcard.com/report/github.com/nyaruka/goflow)
## Specification
See [here](https://textit.com/mr/docs/) for the complete specification docs.
## Basic Usage
```go
import (
"github.com/nyaruka/goflow/assets/static"
"github.com/nyaruka/goflow/flows"
"github.com/nyaruka/goflow/flows/engine"
"github.com/nyaruka/goflow/utils"
)
env := envs.NewBuilder().Build()
source, _ := static.LoadSource("myassets.json")
assets, _ := engine.NewSessionAssets(env, source, nil)
contact := flows.NewContact(assets, ...)
trigger := triggers.NewBuilder(env, flow.Reference()).Manual().Build()
eng := engine.NewBuilder().Build()
session, sprint, err := eng.NewSession(ctx, assets, contact, trigger, nil)
```
## Sessions
Sessions can be persisted between sprints by calling `json.Marshal` on the `Session` instance to marshal it as JSON. You can inspect this JSON at https://sessions.temba.io/.
## Utilities
### Flow Runner
Provides a command line interface for stepping through a given flow.
```
% go install github.com/nyaruka/goflow/cmd/flowrunner
% $GOPATH/bin/flowrunner test/testdata/runner/two_questions.json 615b8a0f-588c-4d20-a05f-363b0b4ce6f4
Starting flow 'U-Report Registration Flow'....
---------------------------------------
💬 "Hi Ben Haggerty! What is your favorite color? (red/blue) Your number is (206) 555-1212"
⏳ waiting for message....
```
By default it will use a manual trigger to create a session, but the `-msg` flag can be used
to start the session with a message trigger:
```
% $GOPATH/bin/flowrunner -msg "hi there" cmd/flowrunner/testdata/two_questions.json 615b8a0f-588c-4d20-a05f-363b0b4ce6f4
```
If the `-repro` flag is set, it will dump the triggers and resumes it used which can be used to reproduce the session in a test:
```
% $GOPATH/bin/flowrunner -repro cmd/flowrunner/testdata/two_questions.json 615b8a0f-588c-4d20-a05f-363b0b4ce6f4
```
### Flow Migrator
Takes a legacy flow definition as piped input and outputs the migrated definition:
```
% go install github.com/nyaruka/goflow/cmd/flowmigrate
% cat legacy_flow.json | $GOPATH/bin/flowmigrate
% cat legacy_export.json | jq '.flows[0]' | $GOPATH/bin/flowmigrate
```
## Development
You can run all the tests with:
```
% go test github.com/nyaruka/goflow/...
```
If you've made changes to the flow engine output, regenerate the test files with:
```
% go test github.com/nyaruka/goflow/test -update
```
If you need to rebuild the ANTLR grammar files:
```
go generate ./...
```