Guides

Journeys API

The journeys API Can be used to programmatically trigger journey flows and subflows individually or in bulk.

Prerequisites

To call the journeys API, first obtain your organization's OrgId and Access Token, as described in the API Authentication documentation.

You'll also need to have created and published a journey that you would like to trigger.

Trigger Journey Flow

API documentation for the trigger journey flow endpoint can be found at Trigger a journey flow or subflow.

Request

The call is a POST to https://medchatapp.com/chatbotapi/external/orgs/{orgId}/journeys/{chatBotId}/instances/bulk, where {orgId} is your organization's ID and {chatBotId} is the ID assigned to the Journey that you'd like to trigger, which can be obtained from the last part of the URL when viewing your saved Journey in Automation Studio.

The JSON request body contains a couple of top-level properties and a list of instances to trigger:

{
  "flowId": null,               // null if triggering a main flow
  "timeZone": "America/Chicago" // IANA timezone to indicate the timezone that any datetime parameters are represented as
  "instances":
  [
    {
      "parameters" : 
      {
        "patientId": "100000",
        "patientName": "John Smith",
        "appointmentId": "40-XYZ-11123",
        "appointmentDateTime": "2023-12-01 08:00:00"      
      }
    },
    {
      "parameters": 
      {
        "patientId": "100001",
        "patientName": "Jane Green",
        "appointmentId": "92-XBX-11934",
        "appointmentDateTime": "2023-12-01 08:30:00"      
      }
    }
    ...
  ]
}
  • flowId- Should be null when triggering a main flow. Provide the subflow ID when triggering a journey subflow.
  • timeZone - The TZ identifier of the IANA timezone that any provided datetimes are represented in. If all provided datetimes are in UTC, specify "UTC". Required if there are any datetime parameters on the journey.
  • instances - An array of instances that should be triggered, each with its unique set of parameters.
    • parameters- A dictionary of strings representing the parameter values for the instance to be used when triggering the journey flow. There should be one key/value pair for each attribute configured as a parameter on the journey.
📘

Triggering journey subflows

The same endpoint for triggering a journey main flow for new instances is used to trigger a journey subflow on existing instances. The only difference is the subflow ID must be provided as flowId in the request when triggering a subflow.

Existing instances will be identified using the "Instance identifier" parameter(s) in the instances array.

Response

Expect a 204 - No Content response on a successful call.

If there is a problem with the request, the API will return a 400 - Bad Request with an array of error messages.

Cancel Journey Flow via API

Just as when needing to trigger a Journey via API, first obtain your organization's OrgId and Access Token, as described in the API Authentication documentation for canceling a Journey execution. Please generate a Scoped Access Token for Journeys - create.journey_instances.

Use the following call for canceling the Journey flow:

DELETEhttps://medchatapp.com/chatbotapi/orgs/{orgId}/journeys/{chatBotId}/instances/{journeyInstanceId}/execution

You'll need your Journey chatBotID and journeyInstanceID to cancel a specific instance.

  • Journey chatBotID: In Medchat, navigate to Automation Studio and pull up your Journey bot. The ID will be the UUID/GUID on the URL.
  • JourneyInstanceID: In Medchat, navigate to Journeys > [Journey Name] and search for your specific record. Clicking on the record will pull up the right-side bar UUID/GUID for your instance (see image below)

Please reach out to your Medchat solution designer or [email protected] for assistance.


Updated 10 days ago