FlowRun

FlowRun is responsible for initiating a Flow in a MessageThread. The FlowRun resource reflects the flow's current state of the flow, including session variables, the present costs incurred in association with the FlowRun and the status attribute displaying the flow's execution state.

Endpoints

• GET /flow-runs - Retrieve a list of all FlowRun.

• GET /flow-runs/{id} - Retrieve a specific FlowRun by ID.

• POST /flow-runs - Trigger a new FlowRun in a MessageThread.

• PATCH /flow-runs/{id} - Update a specific FlowRun by ID.

• DELETE /flow-runs/{id} - Delete a specific FlowRun by ID.

Patching a FlowRun

The following attributes can be patched in a FlowRun:

• state - The state attribute can can only be updated once a FlowRun is not in a running state. By patching the state attribute you can delete any personal data or other sensitive information from the state.

• status - The status attribute can be updated to finished, timeout, cancelled or exception. This can be used to manually finish a flow run or to mark it as a timeout or exception.

Attributes

Field	Type	Description
flowId	UUID	Id of the Flow to be triggered.
messageThreadId	UUID	Id of the MessageThread to trigger the flow on.
state	JSON object	The initial state of the flow run, including session variables.
initialMessage	JSON object	The message to be sent to the candidate when the flow is triggered. Type depends on the channel; for WhatsApp, a template is required. If no message is provided, the flow will be triggered without sending a message to the candidate; this will still mean that the candidate will enter the correct flow upon the next message send. Please set to {} if you wish for no initialMessage.
status	String	The current status of the flow run, which can be one of "running", "finished", "timeout", "exception", "queued".
cost	integer	The current cost in credits of the flow run.
createdAt	DateTime	The timestamp when the flow run was created.
updatedAt	DateTime	The timestamp when the flow run was last updated.

HTTP Methods

Field	GET	POST	PATCH
flowId	X	X
messageThreadId	X	X
state	X	X	X
initialMessage	X	X
status	X
cost	X
createdAt	X
updatedAt	X

Required Fields for Creation (POST)

Field	Type	Example value
flowId	UUID	cacc1a00-b59f-44da-8a48-d99db3473389
messageThreadId	UUID	cacc1a00-b59f-44da-8a48-d99db3473389
state	JSON object	{}
initialMessage	JSON object	{"type":"template","template":{"id":"7f9a9715-5e7c-4328-ab47-bb9e595438c9","components":[{"type":"body","parameters":[{"type":"text","text":"John"}]}]}}

Initial Message

The initial message is the message that will be sent to the candidate when the flow is triggered. The type of the initial message depends on the channel, for whatsapp a template is required. If no message is provided, the flow will be triggered without sending a message to the candidate this will still mean that the candidate will enter the correct flow upon sending a message.

The initial message can be any of the available Payload values, see the Message resource for more information.

Example POST body

{
    "data": {
        "type": "flowRuns",
        "attributes": {
            "flowId": "eb4c92e9-2548-4e4c-95d5-adfb94270c3f",
            "messageThreadId": "7135853f-26ac-4a65-9044-cab092806249",
            "state": {},
            "initialMessage": {
                "type": "template",
                "template": {
                    "id": "7f9a9715-5e7c-4328-ab47-bb9e595438c9",
                    "components": [
                        {
                            "type": "body",
                            "parameters": [
                                {
                                    "type": "text",
                                    "text": "John"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Example PATCH body

{
    "data": {
        "type": "flowRuns",
        "id": "7135853f-26ac-4a65-9044-cab092806249",
        "attributes": {
            "status": "finished"
        }
    }
}

Scheduling

If you have generated a flow with a scheduling step where the mode is set to mode: 'custom' you can provide the Schedule Id when starting the flow by including the following:

{
    "data": {
        "type": "flowRuns",
        "id": "7135853f-26ac-4a65-9044-cab092806249",
        "attributes": {
            "status": "finished",
            "state": {
              "scheduleId": "<my-schedule-id>"
              // Optionally you can add multiple schedule ids aswel:
              // "scheduleId: ["<my-schedule-id>", "<your-schedule-id>"]
            }
        }
    }
}

OpenAPI

Create a FlowRun

post

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Body

application/vnd.api+json

Responses

201

flow_run created

application/vnd.api+json

401

access denied

422

when trying to write a non-writable attribute

post

/flow-runs

HTTPcURLJavaScriptPython

POST /public/v2/flow-runs HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 272

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "flowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageThreadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "state": "{ \"variable\": \"value\" }",
      "initialMessage": {},
      "context": {},
      "status": "running",
      "publicApiInitiated": true
    }
  }
}

{
  "data": {
    "id": "98e5af31-5fbb-4166-b792-9b8764b835b1",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:05+00:00",
      "updatedAt": "2024-08-20T10:45:05+00:00",
      "flowId": "6d6e3b3d-e0b0-4b9d-b42b-ff0b58746cee",
      "messageThreadId": "06bd4b24-7a67-4c09-a5af-0e88c569ab6f",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 0
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/6d6e3b3d-e0b0-4b9d-b42b-ff0b58746cee"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/06bd4b24-7a67-4c09-a5af-0e88c569ab6f"
        }
      }
    }
  },
  "meta": {}
}

Destroy a Candidate

delete

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

204

candidate destroyed

401

access denied

404

Candidate not found

delete

/candidates/{id}

HTTPcURLJavaScriptPython

DELETE /public/v2/candidates/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

No content

Retrieve a single flow_run

get

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found

application/vnd.api+json

401

access denied

404

FlowRun not found

get

/flow-runs/{id}

HTTPcURLJavaScriptPython

GET /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "7460b017-59e7-439a-a1a0-b9e95b301b1c",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:03+00:00",
      "updatedAt": "2024-08-20T10:45:03+00:00",
      "flowId": "25cbfffb-0105-41fe-afdc-454c4aa1bc4b",
      "messageThreadId": "92137559-ea63-4beb-91cf-bf6d477dbf14",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 29
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/25cbfffb-0105-41fe-afdc-454c4aa1bc4b"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/92137559-ea63-4beb-91cf-bf6d477dbf14"
        }
      }
    }
  },
  "meta": {}
}

Destroy a FlowRun

delete

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

204

flow_run destroyed

401

access denied

404

FlowRun not found

delete

/flow-runs/{id}

HTTPcURLJavaScriptPython

DELETE /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

No content

Update a FlowRun

patch

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Body

application/vnd.api+json

Responses

200

flow_run updated

application/vnd.api+json

401

access denied

404

FlowRun not found

422

Invalid Request opening message can not be updated

patch

/flow-runs/{id}

HTTPcURLJavaScriptPython

PATCH /public/v2/flow-runs/{id} HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 272

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "flowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageThreadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "state": "{ \"variable\": \"value\" }",
      "initialMessage": {},
      "context": {},
      "status": "running",
      "publicApiInitiated": true
    }
  }
}

{
  "data": {
    "id": "9b438057-cd8c-4de7-a966-0345ec1414e5",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:04+00:00",
      "updatedAt": "2024-08-20T10:45:04+00:00",
      "flowId": "d972cc73-1487-4ac0-99e7-b5f592d9d94f",
      "messageThreadId": "725791eb-9f29-4211-98d0-c1ca4db35723",
      "state": {
        "first_name": "Henk"
      },
      "initialMessage": {},
      "status": "finished",
      "cost": 30
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/d972cc73-1487-4ac0-99e7-b5f592d9d94f"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/725791eb-9f29-4211-98d0-c1ca4db35723"
        }
      }
    }
  },
  "meta": {}
}

Retrieve a single flow_run including flow

get

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found with included flow

application/vnd.api+json

get

/flow_runs/{id}?include=flow

HTTPcURLJavaScriptPython

GET /public/v2/flow_runs/{id}?include=flow HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

200

flow_run found with included flow

{
  "data": {
    "id": "a9a37c94-173b-4f6d-b9bf-7983a7ef9322",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:02+00:00",
      "updatedAt": "2024-08-20T10:45:02+00:00",
      "flowId": "7f873317-66a6-4312-bc77-3a1056726687",
      "messageThreadId": "37bb741c-e4ac-42b3-aaba-01415126ef9c",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 55
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/7f873317-66a6-4312-bc77-3a1056726687"
        },
        "data": {
          "type": "flows",
          "id": "7f873317-66a6-4312-bc77-3a1056726687"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/37bb741c-e4ac-42b3-aaba-01415126ef9c"
        }
      }
    }
  },
  "meta": {},
  "included": [
    {
      "id": "7f873317-66a6-4312-bc77-3a1056726687",
      "type": "flows",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "name": "aperiam",
        "reminderInterval": 15,
        "reminderMessage": "Are you still there? There are still a few questions left to finish your application.",
        "sessionTimeout": 1440,
        "publishedAt": null,
        "unpublishedChanges": true,
        "flowGenerationId": null
      },
      "relationships": {
        "flowGeneration": {
          "links": {
            "related": "/public/v2/flow-generations?filter[flowId]=7f873317-66a6-4312-bc77-3a1056726687"
          }
        },
        "nodes": {
          "links": {
            "related": "/public/v2/nodes?filter[flowId]=7f873317-66a6-4312-bc77-3a1056726687"
          }
        }
      }
    }
  ]
}

Retrieve a single flow_run including messageThread

get

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Path parameters

idstringRequired

Responses

200

flow_run found with included messageThread

application/vnd.api+json

get

/flow_runs/{id}?include=messageThread

HTTPcURLJavaScriptPython

GET /public/v2/flow_runs/{id}?include=messageThread HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

200

flow_run found with included messageThread

{
  "data": {
    "id": "aee1a798-34b9-482e-bddf-d1c58ef7e438",
    "type": "flowRuns",
    "attributes": {
      "createdAt": "2024-08-20T10:45:02+00:00",
      "updatedAt": "2024-08-20T10:45:02+00:00",
      "flowId": "9b5007f1-38fe-4e14-a235-a3a075a46c39",
      "messageThreadId": "e811c955-a9be-4730-8ad7-1153416fc0e0",
      "state": {},
      "initialMessage": {},
      "status": "finished",
      "cost": 38
    },
    "relationships": {
      "flow": {
        "links": {
          "related": "/public/v2/flows/9b5007f1-38fe-4e14-a235-a3a075a46c39"
        }
      },
      "messageThread": {
        "links": {
          "related": "/public/v2/message-threads/e811c955-a9be-4730-8ad7-1153416fc0e0"
        },
        "data": {
          "type": "messageThreads",
          "id": "e811c955-a9be-4730-8ad7-1153416fc0e0"
        }
      }
    }
  },
  "meta": {},
  "included": [
    {
      "id": "e811c955-a9be-4730-8ad7-1153416fc0e0",
      "type": "messageThreads",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "channel": "whatsapp",
        "identifier": "31652071191",
        "candidateId": null
      },
      "relationships": {
        "candidate": {
          "links": {
            "related": null
          }
        },
        "flowRuns": {
          "links": {
            "related": "/public/v2/flow-runs?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        },
        "messages": {
          "links": {
            "related": "/public/v2/messages?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        },
        "conversation": {
          "links": {
            "related": "/public/v2/conversations?filter[messageThreadId]=e811c955-a9be-4730-8ad7-1153416fc0e0"
          }
        }
      }
    }
  ]
}

Retrieve all FlowRuns

get

Authorizations

Bearer

AuthorizationstringRequired

Bearer

Responses

200

flow_runs found

application/vnd.api+json

401

access denied

get

/flow-runs

HTTPcURLJavaScriptPython

GET /public/v2/flow-runs HTTP/1.1
Host: {defaultHost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "11948e49-4480-4cf7-85dd-92fcba2ea8d8",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "ca3a046a-d71d-45af-b62d-93f272372157",
        "messageThreadId": "64c98b9d-fe20-4e67-a518-391b1ef20a07",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 36
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/ca3a046a-d71d-45af-b62d-93f272372157"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/64c98b9d-fe20-4e67-a518-391b1ef20a07"
          }
        }
      }
    },
    {
      "id": "b9d9425a-ff3d-4f7a-8119-3775a7ddf0f1",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "2cf095b7-f93c-44dc-ae56-5325c2de5f6e",
        "messageThreadId": "587b954c-599f-4001-a26d-17f33fa3596b",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 15
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/2cf095b7-f93c-44dc-ae56-5325c2de5f6e"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/587b954c-599f-4001-a26d-17f33fa3596b"
          }
        }
      }
    },
    {
      "id": "1c59170d-e8e0-4c17-835b-a7ad3d2b7e7c",
      "type": "flowRuns",
      "attributes": {
        "createdAt": "2024-08-20T10:45:02+00:00",
        "updatedAt": "2024-08-20T10:45:02+00:00",
        "flowId": "99e55620-aa7b-4737-8cd3-943a606f8505",
        "messageThreadId": "7f09643d-0068-4f30-853b-0e70ca3f973a",
        "state": {},
        "initialMessage": {},
        "status": "finished",
        "cost": 53
      },
      "relationships": {
        "flow": {
          "links": {
            "related": "/public/v2/flows/99e55620-aa7b-4737-8cd3-943a606f8505"
          }
        },
        "messageThread": {
          "links": {
            "related": "/public/v2/message-threads/7f09643d-0068-4f30-853b-0e70ca3f973a"
          }
        }
      }
    }
  ],
  "meta": {
    "total": 3,
    "totalUnfiltered": 3,
    "currentSize": 25,
    "currentPage": 1,
    "maxPage": 1
  }
}