Building workflows

A workflow sends the right message at the right moment without you pressing anything: a welcome SMS when someone joins a group, a rent reminder three days before the due date, a thank-you after an order. You build it on a canvas in the dashboard, with no code.

Developers can build the same workflows over the API. See the Workflows API.

The idea

A workflow is a chain of steps. It always begins with one trigger (what starts it) and continues through actions (send an SMS, add to a group) and logic (wait two days, check a condition). Each time the trigger fires for someone, that person goes through the chain once. That pass is called a run.

Create a workflow

1. Open Workflows in the sidebar and click New workflow.
2. Give it a Name (for example "Welcome new customers") and, if you like, a Description (optional), then click Create.
3. You land on the workflow's page. Its Editor tab shows the canvas with a single trigger step.

Your changes save by themselves. The canvas shows Draft saved in the top right; nothing you do in the editor affects live messages until you publish.

Choose a trigger

Click the trigger step on the canvas. In the right-hand panel, Starts when lets you choose what starts the workflow:

Trigger	Use it when
Started manually or by API	You want to start it yourself with Run now, or from your own software. Good for testing.
When an event is received	Your own system tells MsGine something happened, such as "order paid". Give it the event name; developers send it over the API.
When something happens in MsGine	MsGine itself notices something: a contact is added to a group, a message is delivered, a bot gets a new conversation, an opt-out. Pick the Event. This is the usual way to start a journey when someone joins a group.
Send to an audience	You want to send to everyone in one or more groups at once, like a campaign. Nothing is sent when you publish; you launch it (see Launches).
On a schedule	You want the same message to go to a group every day, week or month at a set time, such as fees every Monday.
On a contact's date	The message depends on a date stored on each contact, such as "3 days before the rent is due" or "on their birthday".
When a form or app posts to a URL	A website form, a shop or another service should start the workflow. See Workflow URLs.

Many triggers have an Only when box. It narrows when the workflow starts. See Writing conditions.

Add steps

The left panel lists the steps you can add, in two groups.

Actions

• Send SMS, Send WhatsApp, Send email, Send push notification
• Update contact: set the contact's name or email
• Add to group and Remove from group
• HTTP request: call another system

Logic

• Condition: take one path if something is true and another if not
• Wait: pause for a number of minutes, hours or days
• Wait until a time: continue at a set time of day, optionally only on certain weekdays
• Wait for event: wait for the contact to do something, or give up after a time limit
• Split (A/B): send different contacts down different paths by percentage
• End: finish the run

Hover over a step in the list to read what it does. Click one to add it to the canvas; it appears next to the step you had selected. Then fill in its settings in the right-hand panel. Fields marked with a red asterisk are required.

Adding a step does not connect it

A new step sits on the canvas on its own, and a step that is not connected to the trigger never runs. Connect every step as described next.

Connect the steps

The lines between steps are what make a workflow work.

• To connect two steps: every step has a dot on its right edge. Drag from that dot to the left edge (or onto the card) of the step that should come next. A line appears. The trigger has only a right-hand dot, since nothing can lead into a trigger.
• Steps with more than one way out show a dot per path, each labelled. A Condition has yes and no; Wait for event has received and timeout; HTTP request has success and failed; Split (A/B) has one per branch you name. Connect each path to what should happen on it.
• One line per path. If you draw from the same dot again, the new line replaces the old one.
• To remove a connection: click the line to select it and press Delete or Backspace.
• To remove a step: select it and click Remove step in the right-hand panel (or press Delete). Its connections go with it. The trigger cannot be removed.
• If a path has no line, the run simply ends there.

A workflow cannot loop back on itself.

Writing conditions and templates

You will type text into two kinds of boxes, and they differ in one way.

Message and text fields use {{ }}. Fields like To, Message, Subject and Title are templates: plain text with placeholders in double curly braces that MsGine fills in for each person.

Hi {{ contact.name }}, your order {{ trigger.orderId }} is ready.

Trigger and condition fields take a bare expression, with no braces. The boxes labelled Only when, Condition, Contact's phone and Contact's name hold one expression that is true, false or a value:

trigger.amount > 50000

Writing {{ trigger.amount > 50000 }} in one of those boxes will not work.

What you can refer to:

Name	What it is
trigger	Information about what started the run: the fields of a form post, an event's details, and so on. Selecting a When something happens in MsGine trigger lists the fields that event provides.
contact	The person going through the workflow: contact.name, contact.phone, contact.email, and your own fields as contact.fields.due_date.
steps	What earlier steps produced, such as steps.send_sms_1.status. Each step's panel shows its own Results name.

More examples:

contact.fields.balance > 100000
trigger.groupName == 'Welcome list'
trigger.form == "signup"

If a message refers to something that does not exist, for example {{ trigger.code }} when the event has no code, that step fails rather than sending a half-filled message. The run's timeline then shows why.

See Expressions for everything these can do.

Workflow settings

Click an empty part of the canvas so no step is selected, and the right panel shows Workflow settings. They apply to runs that are about a contact.

Setting	What it does
Message type	Marketing (the default) follows your messaging policy: quiet hours and a daily limit. Transactional messages, like receipts, codes and alerts, never wait or get skipped.
Can a contact go through again?	Only once (the default), Again after some days (you set the number), or Every time. A contact is never in the same workflow twice at once, whichever you pick. Workflows that start On a schedule or On a contact's date are set to allow re-entry unless you change it.
Never enter if in	Tick groups whose members should never enter, for example people who have already paid.
Goals	Click Add goal. When the chosen event happens to a contact, they leave the workflow as converted. Use it to stop reminders once someone pays. Choose Your event (sent by your own system) or MsGine event, and optionally an Only when condition.

Opted-out people are skipped automatically, with no setting needed: a send to someone on your opt-out list is dropped without failing the run.

Publish

While you edit, the workflow is a Draft. Click Publish at the top of the page to make it live. Publishing saves a numbered version, which you can see on the Versions tab. The workflow's badge changes to Active.

People already going through the workflow finish on the version they started on, so you can publish changes safely.

If publishing fails

If something is wrong, a red box titled Workflow definition is not valid appears at the top of the page, listing each problem, and the workflow stays as it was. To find where a problem is:

• Steps with a problem get a red border and a warning icon on the canvas. Click one and its problems are listed at the top of the right-hand panel.
• Problems that belong to no single step, such as "A workflow needs exactly one trigger", are listed in a red box at the top of the right-hand panel.

These checks also run each time your draft saves, so you can fix things as you go. Common causes are a required field left empty, a step that is not connected to the trigger, a typo in an expression, and an On a contact's date trigger whose date field does not exist.

Test safely with sandbox

A sandbox run executes every step but sends nothing and charges nothing.

For a workflow whose trigger is Started manually or by API, publish it and open the Runs tab, then click Run now:

• Input (JSON) becomes trigger, for example { "name": "Amina" }.
• Contact phone (optional) makes the run about that contact, so contact.name and your settings apply. It must be a contact you have saved.
• Sandbox is switched on by default. Leave it on while testing.

Then click Run and open the run you just started to check it.

For other triggers, one way to test is to build and publish the workflow with a manual trigger first, test with Run now, then switch the trigger in the editor and publish again. Selecting a different trigger clears the trigger's own settings, so fill them in again.

Watch your runs

The Runs tab lists every run: when it Started, its Status (running, waiting, completed, failed or cancelled), the Contact, the Mode (Live or sandbox), how many Steps it took and the Outcome. Filter by status at the top.

Click a run to open its Run timeline: the Input it started with, then each step in order with its result, how long it took and any error. A run that is waiting is asleep until its next step is due. You can Cancel run while it is running or waiting.

Pause, resume and archive

• Pause stops the workflow starting new runs. People already inside stay where they are until you click Resume.
• Archive stops the workflow for good and cancels runs in progress. Messages already sent are not affected, and the workflow's history is kept.

Send to an audience (launches)

A workflow that starts with Send to an audience does nothing when you publish it. Once it is Active, a Launches tab appears:

1. Click Launch.
2. To send later, switch on Schedule for later and choose Start at (up to a year ahead). Otherwise it starts straight away.
3. Sandbox is on by default. Switch it off to send for real.
4. Click Launch now or Schedule.

The tab then lists each launch with its run time, status, Entered (people who started the workflow) and Skipped (people the entry rules kept out, such as those in a Never enter if in group or who already went through it). Scheduled and running launches have a Cancel button; cancelling stops letting new people in, while people already inside carry on.

Schedules and dates

On a schedule and On a contact's date run by the clock in your account's timezone, not your computer's. It is set under Settings → Messaging → Messaging policy → Timezone (the default is Africa/Kampala). If you change it, your recurring workflows move to the new clock.

• On a schedule: choose the Groups, how often to Repeat (daily, weekly or monthly), the time in At (HH:MM), and the days. Everyone in the groups goes through at each occurrence. If the system was down at the time, a missed occurrence runs once afterwards. Occurrences that pass while the workflow is paused are skipped.
• On a contact's date: choose the Date field, Days after the date (use a negative number for before: -3 is three days before), the time and, for birthdays and anniversaries, Every year (birthdays, anniversaries). Optionally limit it with Only contacts in. You first create the date field under Contacts → Fields.

Quiet hours and daily limits

Under Settings → Messaging → Messaging policy you can switch on Quiet hours (marketing messages wait until they end) and a Daily cap per contact (the most marketing messages one person gets in a day across all your workflows). These apply to workflows whose Message type is Marketing. Transactional workflows ignore them.

Workflow URL

If the trigger is When a form or app posts to a URL, the right-hand panel shows a Workflow URL box where you click Create URL. See Workflow URLs for the full story.

Recipe: rent reminder 3 days before the due date

Send each tenant an SMS three days before their rent is due.

1. Create the field. Go to Contacts → Fields → New Field. Set the Label to "Due date", leave the Key as due_date and choose the Type Date. Save it.
2. Fill it in. Give each tenant a due date on their contact, or include a "Due date" column when you import a file. Write dates as 2027-01-15 or 15/01/2027; the second is read day first.
3. Create a workflow called "Rent reminder".
4. Set the trigger. Select the trigger and change Starts when to On a contact's date. Set Date field to Due date, Days after the date to -3, and At (HH:MM) to 09:00. Under Only contacts in pick your tenants group, or leave it empty for everyone who has a due date.
5. Add a step. Click Send SMS in the left panel. Fill in:
   • To: {{ contact.phone }}
   • Message: Hi {{ contact.name }}, your rent is due on {{ contact.fields.due_date }}. Please pay on time.
6. Connect them. Drag from the dot on the right of the trigger to the left edge of Send SMS.
7. Choose the message type. Click an empty part of the canvas. A reminder about money owed is not a promotion, so set Message type to Transactional if you do not want it held back by quiet hours.
8. Publish.

Each morning at 09:00 (your account's timezone), everyone whose due date is three days away gets the SMS. Because this trigger allows contacts to go through again, next month's due date triggers a new reminder, as long as you update the date on the contact.

Recipe: welcome series

Greet someone the moment they join a group, then follow up two days later.

1. Create a workflow called "Welcome series".
2. Set the trigger. Change Starts when to When something happens in MsGine, and set Event to Contact added to group. In Only when type trigger.groupName == 'New members', using your group's exact name, so it only starts for that group. (The panel lists the fields this event gives you, such as trigger.groupName.)
3. Add Send SMS with To {{ contact.phone }} and MessageWelcome, {{ contact.name }}! Reply to this number any time if you need help.
4. Add Wait with Wait for 2 and Unit days.
5. Add a second Send SMS with To {{ contact.phone }} and a follow-up Message, for example Hi {{ contact.name }}, how are you finding things so far?
6. Connect them in order: trigger → first Send SMS → Wait → second Send SMS.
7. Publish.

From now on, anyone you add to "New members" gets the welcome SMS straight away and the follow-up two days later. Because Can a contact go through again? is Only once, someone who is removed and added again does not get the series a second time.

Next steps

• Start workflows from a form or your own system: Workflow URLs
• Everything the engine can do, for developers: Workflows API
• Define the fields your contacts carry: Contact fields