Run workflow
Runs the builder version of a workflow for real, as if the trigger had fired: messages are sent and cost credits,
webhooks are called, contacts are changed and conversations are assigned. The payload is the sample payload for
contact_id (or the generic test contact), with the keys of payload merged on top. A
wait node parks the execution (status waiting) and it is resumed later with the same
version. The run is recorded as an execution with source manual. This endpoint is throttled like sending
messages; team users also need the permission to send messages.
Base URL:
POST: https://api.smsgatewayapi.com/v1/flows/{flow_id}/runExample:
POST: https://api.smsgatewayapi.com/v1/flows/flw_5d41402abc4b2a76b9719d911017c592/run
| Parameter | Input | Description | |
|---|---|---|---|
| client_id | API client ID | Developer › API & Webhooks › API credentials | Required |
| client_secret | API client secret | A cs_ credential, shown once when you create it under Developer › API & Webhooks › API credentials | Required |
| flow_id | workflow ID | The public ID (flw_...) of the workflow as returned by List workflows; the numeric ID is accepted too | Required |
| contact_id | contact ID | Public ID (con_...) or numeric ID of one of your contacts; its data fills the contact part of the payload | Optional |
| payload | object | Keys that override the sample payload, e.g. { "message": { "body": "STOP" } } | Optional |
<?php
//PHP - cURL
$ch = curl_init();
$url = "https://api.smsgatewayapi.com/v1/flows/{flow_id}/run";
$client_id = "XXX"; // Your API client ID (required)
$client_secret = "YYY"; // Your API client secret (required)
$data = [
'contact_id' => "con_5d41402abc4b2a76b9719d911017c592", //Contact the workflow runs for (optional)
'payload' => [ //Overrides for the sample payload (optional)
"message" => ["body" => "STOP"]
]
];
curl_setopt($ch, CURLOPT_URL, "$url");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"X-Client-Id: $client_id",
"X-Client-Secret: $client_secret",
"Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
?>
Example request:
{
"contact_id": "con_5d41402abc4b2a76b9719d911017c592",
"payload": {
"message": { "body": "STOP" }
}
}
Example success response:
{
"flow": "flw_5d41402abc4b2a76b9719d911017c592",
"execution": "7c1e5b2a-3d4f-4a6b-9c8d-0e1f2a3b4c5d",
"status": "completed",
"version_number": 1,
"version_status": "published",
"result": {
"visited_nodes": [
{ "id": "trigger", "type": "triggerNode", "label": "Inbound message", "result": "triggered", "subtitle": "inbound_message", "incoming_edge_id": null },
{ "id": "is_stop", "type": "conditionNode", "label": "Message is STOP?", "result": "matched", "branch": "true", "incoming_edge_id": "e1" },
{ "id": "opt_out", "type": "actionNode", "label": "Opt out", "result": "executed", "incoming_edge_id": "e2" }
],
"actions": [
{
"type": "opt_out",
"status": "executed",
"summary": "Contact 32470123456 afgemeld"
}
],
"stopped_reason": "completed"
}
}
status is completed, waiting (parked on a wait node; the result then also carries wait_seconds), stopped or failed. The summary of an action is free text; rely on status and details in your code.
Example error response:
{
"error": 1403,
"errorMsg": "Unauthorized action: this team user does not have access to the specified items."
}
