Journeys

A flow is structure inside one call. A journey is structure across calls and days: dial, branch on how it went, wait, try again, and fall back to a message when the phone is never going to be answered.

What a journey is made of

┌──────────┐   answered, owes > 5000   ┌──────────┐
│  remind  │──────────────────────────▶│ arrange  │
│  (call)  │                           │  (call)  │
└────┬─────┘                           └────┬─────┘
     │ no answer                             │ agreed
     ▼                                       ▼
┌──────────┐        ┌──────────┐        ┌──────────┐
│   wait   │───────▶│  remind  │        │   end    │
│   24h    │        │ (revisit)│        │ converted│
└──────────┘        └──────────┘        └──────────┘
                          │ 3 visits reached
                          ▼
                    ┌──────────┐        ┌──────────┐
                    │ message  │───────▶│   end    │
                    │   sms    │        │unreachable│
                    └──────────┘        └──────────┘

That graph is the single most common journey anybody builds, and it can be drawn two ways. As above, a call node that may be visited three times, with a no-answer case looping back through a wait, is the retry — drawn rather than configured. Or a retry node holds the same idea on one block: how many times to go back, how long to wait between attempts, and where to go when they run out. The two are equivalent — max_visits: 3 on the call is attempts: 2 on a retry node, because attempts counts the tries after the first.

Draft, then publish

curl -s -X PUT https://voice.sphoro.com/v1/journeys/$JOURNEY_ID/draft \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "remind",
    "max_lifetime": "168h",
    "variables": { "amount_due": "number" },
    "nodes": [
      {
        "id": "remind", "name": "Payment reminder", "type": "call", "max_visits": 3, "on_exhausted": "sms",
        "call": { "agent_id": "'"$AGENT_ID"'", "variables": {"first_name": "{{first_name}}"} },
        "cases": [
          { "to": "arrange", "label": "answered and owes more than 5,000",
            "when": {"conditions": [{"variable": "amount_due", "operator": "gt", "value": 5000}]} },
          { "to": "converted", "label": "answered and paid",
            "when": {"conditions": [{"variable": "agreed_to_pay", "operator": "eq", "value": true}]} },
          { "to": "hold", "label": "no answer" }
        ]
      },
      { "id": "hold", "type": "wait",
        "wait": { "for": "24h", "window": {"after": "10:00", "before": "19:00", "timezone": "Asia/Kolkata"} },
        "cases": [{ "to": "remind" }] },
      { "id": "sms", "type": "message",
        "message": { "channel": "sms", "text": "Hello {{first_name}}, we tried to reach you about your balance. Please call us on 020 4000 1234." },
        "cases": [{ "to": "unreachable" }] },
      { "id": "arrange", "type": "call", "call": {"agent_id": "'"$PLAN_AGENT"'"},
        "cases": [{ "to": "converted" }] },
      { "id": "converted",   "type": "end", "end": {"outcome": "converted"} },
      { "id": "unreachable", "type": "end", "end": {"outcome": "unreachable"} }
    ]
  }'

curl -s -X POST https://voice.sphoro.com/v1/journeys/$JOURNEY_ID/publish \
  -H "Authorization: Bearer $SPHORO_API_KEY"

Executions already running continue on the version they started on. That is deliberate: a contact halfway through a three-call sequence should finish the sequence they began, not jump into a graph where their next node no longer exists.

Starting a journey on its own

Besides being enrolled — by hand, from a list, or with POST /v1/journey_executions — a journey can add people itself. Its triggers are part of the graph, so they go live when you publish, and they are paused and resumed without a publish with PATCH /v1/journeys/{id} and {"auto_entry_off": true}.

Somebody already walking the journey is not added again, and calls a journey places never trigger one.

Events and goals

An event is something your system tells a journey happened to one contact — paid, booked. Deliver one with POST /v1/journey_executions/{id}/events and {"event": "paid", "data": {...}}, or without an API key to {webhook_url}/events with the contact's phone. It is kept as events.<name>, releases an await step waiting for it, and is checked against the journey's goal: a condition that ends the journey early, from wherever the contact is standing — {"goal": {"when": {"conditions": [{"variable": "events.paid", "operator": "exists"}]}, "outcome": "paid"}} stops the reminders the moment they pay.

Journey-wide settings

calling_hours is a window every call step keeps to, on top of your account's compliance hours. reentry says whether somebody may go through the journey again: empty once their last run has finished, "never", or a length of time such as "720h".

Results

GET /v1/journeys/{id}/stats?version=N counts contacts — not visits — per step, per way out (exits, keyed as the editor names a step's ports), per outcome, and each A/B split's paths by outcome. The editor draws the same numbers on the canvas.

curl -s -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"name": "Asha", "phone": "+919000000000", "event_id": "lead-4812", "utm_source": "google"}'

The node types

On every node

The journey itself carries start_position, the same {"x", "y"} shape, for where the editor draws its Start block. Presentation only, like position — and kept inside the definition so a layout survives being published, exported and imported.

A call node

A wait node

A retry node

{ "id": "again", "name": "Try again", "type": "retry",
  "retry": { "attempts": 2, "to": "remind", "delay": "24h",
             "window": {"after": "10:00", "before": "19:00"} },
  "cases": [{ "to": "sms", "label": "gave up" }] }

A retry node's cases are only ever the way out once its attempts are used up, and it needs at least one. On that last arrival it does not wait: a delay before "we stopped trying" only delays the fallback. It counts its own attempts, so max_visits and on_exhausted are refused on it.

An api node

Message, actions and end

{ "type": "message", "message": { "channel": "sms", "text": "Hello {{first_name}}…" } }
{ "type": "actions", "actions": { "workflow_id": "wfl_…", "input": {"outcome": "{{outcome}}"} } }
{ "type": "end",     "end": { "outcome": "converted" } }

A message node's channel is sms, whatsapp or email; to defaults to the contact's own number or address. An end node's outcome is the label the funnel report counts under — converted, unreachable, opted_out. Empty is completed.

Cases: the ways out

Tried in order of priority, then declaration. The first whose when holds is taken, and a case with no when is the catch-all — so it must be last.

{
  "to": "arrange",
  "label": "answered and owes more than 5,000",
  "when": { "logic": "and", "conditions": [
    { "variable": "amount_due",    "operator": "gt", "value": 5000 },
    { "variable": "agreed_to_pay", "operator": "eq", "value": false }
  ]}
}

Deliberately the same condition shape a flow edge uses: an account that has learned to write amount gte 5000 in an in-call flow should not have to learn a second language to write it here. Declare anything numeric in the journey's variables map, for the same reason and with the same silent failure if you do not.

Bounds, because a journey can loop

"No answer, wait a day, try again" is a cycle, and it is the most common journey there is. So cycles cannot be banned — they are bounded at run time instead.

Running one contact through it

curl -s -X POST https://voice.sphoro.com/v1/journey_executions \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "journey_id": "'"$JOURNEY_ID"'",
    "contact": {"phone": "+919876543210", "email": "priya@example.com"},
    "variables": {"first_name": "Priya", "amount_due": 8400}
  }'

# Where is this contact, and how did they get there?
curl -s https://voice.sphoro.com/v1/journey_executions/$EXECUTION_ID \
  -H "Authorization: Bearer $SPHORO_API_KEY"

An execution carries its timeline: which nodes it visited, which case fired at each, and the calls it placed. That is the debugging story — a contact who ended up somewhere unexpected has a trail saying exactly which condition took them there.

Journey, flow, or neither?

Sphoro Voice also exposes the whole journey schema to a coding assistant, which is a far better way to draft a graph than typing this JSON — see build with AI.