Outbound Journeys

Journeys allow you to orchestrate multi-step messaging flows using the InstaMessage platform.

You can create and manage Journeys in InstaMessage from the Journeys screen.

This section covers:

• Triggering outbound Journeys via the API
• Passing injected_fields at Journey start
• Checking Journey publish status
• Publishing a Journey programmatically

A Journey is a predefined messaging flow that can include:

• One or more messages
• Delays and conditional logic
• Channel-specific steps (SMS, WhatsApp, etc.)
• Optional personalisation using injected_fields

Journeys are designed in the UI and executed by the platform once triggered.

Outbound Journeys are triggered by your system via the API.

Common use cases include:

• Order confirmations
• Delivery updates
• Customer onboarding sequences
• Automated follow-ups

This documentation applies to outbound Journeys only.

Inbound Journeys (triggered by customer messages) are supported in the platform but require additional setup and are documented separately.

Inbound Journeys may prompt customers for required fields interactively rather than receiving them at trigger time.

Before a Journey can be triggered:

1. It must be created in the dashboard
2. It must be published

Only published Journeys can be triggered via the API.

Use the Journey trigger endpoint to start a Journey for a specific recipient.

POST https://api.instamessage.co.uk/v1/journeys/{journey_id}/trigger

Some Journey steps may reference injectable fields.

These fields must be supplied when the Journey is triggered, otherwise execution may fail or pause depending on Journey configuration.

Example placeholders inside a Journey message:

Hi {{first_name}}, your order {{order_id}} is on its way.

These values must be provided at trigger time.

{
  "to": "+447123456789",
  "injected_fields": {
    "first_name": "Alex",
    "order_id": "ORD-12345"
  }
}

Journeys must be published before they can be triggered.

You can check whether a Journey is published using the publish status endpoint.

GET https://api.instamessage.co.uk/v1/journeys/{journey_id}/published

Example response

{
  "journey_id": "journey_123",
  "published": true,
  "published_at": "2025-06-01T12:00:00Z"
}

Journeys can be published programmatically via the API.

This is useful for:

• CI/CD workflows
• Environment promotion
• Automating Journey rollout

Publish Journey endpoint

POST https://api.instamessage.co.uk/v1/journeys/{journey_id}/published

Example request

{
  "published": true
}

Once published, the Journey becomes immediately triggerable.

Common Journey-related errors include:

• Triggering an unpublished Journey
• Missing required injected fields
• Invalid Journey ID

Example error:

{
  "error": "journey_not_published",
  "message": "The Journey must be published before it can be triggered"
}

• Journeys are created and configured in the UI
• Only published Journeys can be triggered
• Injectable fields must be supplied at trigger time
• Journeys execute asynchronously
• Delivery outcomes are reported via webhooks and message status APIs

• Send individual messages → Send a Message
• Track delivery → Delivery Receipts & Message Status
• Handle inbound replies → Inbound Messages & Replies
• Configure webhooks → Webhook Quick-Start
• Manage contacts → Contacts