Skip to main content

Integration Guide

Once you have built your live flow on the Truestate Platform, we are ready to begin the integration.

Who is this integration for?​

This integration has been created to allow customers to build a personalised UI for their end users to run sessions on a prebuilt Live Flow.

Truestate exposes the lifecycle of a live flow session discussed earlier through the following apis:

  1. create session
  2. get session
  3. get sessions
  4. add user input
  5. cancel session

You can view the fine details in our rest api reference at https://api.truestate.io/docs#/live_flow_sessions

1. Obtain your Live Flow ID​

Each Live Flow is stored in the Truestate System and can be referenced by the live_flow_id.

This id can be found at the end of your browser's url when viewing the live flow on the Truestate platform

For example:

https://platform.truestate.io/live-flows/f6a0e47b-23ca-471a-83da-1ed29e2c1dbe

-> 

live_flow_id = f6a0e47b-23ca-471a-83da-1ed29e2c1dbe

2. Create your first session​

Now we can run the Live Flow using the Create Session api.

You can find the details on how to use the api in our HTTPS API Docs here:

https://api.truestate.io/docs#/live_flow_sessions/create_session_live_flows__live_flow_id__sessions__post

3. View the Session object​

Once we have created the session, we can always view the session object using the Get Session Api detailed here:

https://api.truestate.io/docs#/live_flow_sessions/get_session_live_flows__live_flow_id__sessions__session_id___get

The session object contains all potential information about a running session that you'll need to populate the UI.

Things like:

  • The Session Status ['status']
  • The trigger body ['inputs']
  • The Current Step ['current_step']
  • All Steps ['steps']
  • Session Error (if the session failed) ['error']

4. Integrating in User Input (optional)​

Truestate Live Flows also support end user interaction throughout (using the User Input node).

4.1 Watch for Session Status​

When the session is waiting for the user to input data this will be indicated in the ['status'] field of the Session object as WAITING_FOR_USER_INPUT.

4.2 Get the User Prompt​

In your liveflow, your User Input node would have a 'prompt' value specified. In most use cases you would want to display this 'prompt' to the end user before waiting for their input.

You can find this 'prompt' value in the ['current_step']['prompt']' field of the session object.

4.3 Send User Input To Session​

When you're ready to send TrueState the user input, you can send it using the following api call:

https://api.truestate.io/docs#/live_flow_sessions/add_user_input_to_session_live_flows__live_flow_id__sessions__session_id__user_input_post

Note: This API can only be called when the session status is WAITING_FOR_USER_INPUT.

5. Cancelling a session (optional)​

Cancelling a session isn't strictly necessary, but if you wanted to end a session before it has finished you can call the "Cancel Session" api call detailed below here:

https://api.truestate.io/docs#/live_flow_sessions/cancel_session_live_flows__live_flow_id__sessions__session_id__cancel_patch

When cancelled the Session will immediately stop with status FAILED.